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

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 for metadata, 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:

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

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

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:

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:

1. The wrapper locates the zipcode-search skill folder.
2. It detects that 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 file.

Query Kakao Map for location data:

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:

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	Declares skill metadata, description, and credential requirements	zipcode-search/skill.json
instruction.md	Contains the Node.js example and Python example with exact commands	zipcode-search/instruction.md
scripts/*	The runnable implementation invoked by exec	zipcode-search/scripts/zipcode_search.py

The 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 in the repository root (NomaDamas/k-skill)
• CLI execution rules: AGENTS.md → "Unified CLI skill instruction rules" section
• Skill-specific examples: Each skill's instruction.md (e.g., 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 handles runtime detection and process spawning automatically.
• Check each skill's 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 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 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 in the repository.

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

The -- separator distinguishes wrapper arguments (handled by 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}