# How to Run k‑Skill Examples: Complete Guide for Python and Node.js

> Learn to run k-skill examples easily using the npx command. This guide provides clear steps for Python and Node.js, making k-skill execution straightforward.

- Repository: [NomaDamas/k-skill](https://github.com/NomaDamas/k-skill)
- Tags: how-to-guide
- Published: 2026-08-04

---

**Use the `npx @nomadamas/k-skill exec` command followed by the skill name, script path, and arguments after `--` to run any k‑Skill example in a single step.**

The **k‑Skill** repository is a monorepo containing over 150 independent Korean utility skills. Each skill follows a standardized structure with [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) for metadata, [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) for usage guides, and a `scripts/` directory containing runnable implementations. This guide explains how to execute examples using the unified CLI wrapper that works across both JavaScript/TypeScript and Python runtimes.

## Installing k‑Skills

Before running examples, install the skill collection using **npx‑skills**. You can install either the entire repository or individual skills.

Install every skill globally:

```bash
npx --yes skills add NomaDamas/k-skill --all -g

```

Install only a specific skill (e.g., `zipcode-search`):

```bash
npx --yes skills add NomaDamas/k-skill --skill zipcode-search -g

```

The `--all -g` flag is recommended for first-time users who want to explore multiple examples without repeated installation steps.

## Running Python Skill Examples

To run a **Python** example, use the `exec` subcommand with the skill name, script path, and arguments separated by `--`.

Search for a Korean postcode using the `zipcode-search` skill:

```bash
npx -y @nomadamas/k-skill@0 exec zipcode-search scripts/zipcode_search.py -- \
  --query "강남구"

```

What happens internally in [`packages/k-skill-cli/scripts/exec.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/scripts/exec.js):

1. The wrapper locates the `zipcode-search` skill folder.
2. It detects that [`scripts/zipcode_search.py`](https://github.com/NomaDamas/k-skill/blob/main/scripts/zipcode_search.py) is a Python file.
3. It spawns a Python child process and forwards `"강남구"` as the `--query` argument.

## Running Node.js Skill Examples

The same CLI pattern works for **JavaScript/TypeScript** implementations. Replace the script extension and arguments per the skill's [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) file.

Query Kakao Map for location data:

```bash
npx -y @nomadamas/k-skill@0 exec kakao-map scripts/kakao_map.js -- \
  --query "역삼동"

```

Other popular skills use the identical structure:
- `korea-weather` – fetch weather forecasts
- `lotto-results` – retrieve Korean lottery results
- `korean-heritage-search` – search national heritage databases

## Listing Available Skills and Entry Points

Before running an example, discover what commands are available:

```bash
npx -y @nomadamas/k-skill@0 list --json

```

This outputs a JSON array mapping each skill name to its entry-point scripts, useful for automation pipelines or IDE integration.

## Understanding Skill Structure

Each k‑Skill folder follows a predictable layout that enables the CLI wrapper to operate generically:

| File | Purpose | Example Location |
|------|---------|----------------|
| [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) | Declares skill metadata, description, and credential requirements | [`zipcode-search/skill.json`](https://github.com/NomaDamas/k-skill/blob/main/zipcode-search/skill.json) |
| [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) | Contains the Node.js example and Python example with exact commands | [`zipcode-search/instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/zipcode-search/instruction.md) |
| `scripts/*` | The runnable implementation invoked by `exec` | [`zipcode-search/scripts/zipcode_search.py`](https://github.com/NomaDamas/k-skill/blob/main/zipcode-search/scripts/zipcode_search.py) |

The [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) file is your primary reference—copy the exact command shown there and substitute your own argument values after `--`.

## Where to Find Reference Documentation

- **Installation commands**: [`README.md`](https://github.com/NomaDamas/k-skill/blob/main/README.md) in the repository root (`NomaDamas/k-skill`)
- **CLI execution rules**: [`AGENTS.md`](https://github.com/NomaDamas/k-skill/blob/main/AGENTS.md) → "Unified CLI skill instruction rules" section
- **Skill-specific examples**: Each skill's [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) (e.g., [`zipcode-search/instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/zipcode-search/instruction.md))

## Summary

- **Install** skills with `npx skills add NomaDamas/k-skill --all -g` or `--skill <name> -g` for individual skills.
- **Run** any k‑Skill example with `npx -y @nomadamas/k-skill@0 exec <skill> <script> -- <args>`.
- The `exec` command in [`packages/k-skill-cli/scripts/exec.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/scripts/exec.js) handles runtime detection and process spawning automatically.
- Check each skill's [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) for the precise command template and required credentials.

## Frequently Asked Questions

### What is the difference between `npx skills add` and `npx @nomadamas/k-skill exec`?

`npx skills add` installs skill definitions onto your system using the **npx‑skills** ecosystem. `npx @nomadamas/k-skill exec` invokes the lightweight runtime wrapper that actually executes a skill's script. You need both: first install, then execute.

### Can I run k‑Skill examples without installing them first?

No. The `exec` wrapper relies on locally installed skill metadata and scripts. The installation step populates the skill registry that [`packages/k-skill-cli/scripts/exec.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/scripts/exec.js) searches when resolving skill names to folder paths.

### Where do I find the exact command for a specific skill example?

Open the skill's [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) file. Every skill includes concrete command lines labeled "Node.js example" or "Python example" that you can copy and modify. For `zipcode-search`, this is at [`zipcode-search/instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/zipcode-search/instruction.md) in the repository.

### Why must arguments come after `--` in k‑Skill commands?

The `--` separator distinguishes **wrapper arguments** (handled by [`exec.js`](https://github.com/NomaDamas/k-skill/blob/main/exec.js)) from **script arguments** (passed to the skill's implementation). Everything before `--` controls the CLI; everything after is forwarded to the Python or Node.js process unmodified.