How to Execute Skills Using k-skill CLI Commands

The k-skill CLI provides a unified exec command that lets you run any skill's helper script using npx -y @nomadamas/k-skill@0 exec <skill-name> <script-path> -- <args> or the shorter k-skill exec alias when installed globally.

The NomaDamas/k-skill repository ships a unified command-line interface that simplifies running automation skills. Understanding the k-skill CLI commands allows you to invoke any skill's bundled helper scripts directly from the terminal without navigating complex directory structures or managing Python environments manually.

The Core exec Command Syntax

The primary k-skill CLI command for executing skills follows this pattern:

npx -y @nomadamas/k-skill@0 exec <skill-name> <script-path> -- <skill-specific-args>

This command breaks down into distinct components:

• npx -y @nomadamas/k-skill@0 – Fetches and executes the latest published CLI package without prompting for installation.
• exec – The sub-command that instructs the CLI to execute a skill.
• <skill-name> – The folder name of the skill (e.g., zipcode-search, srt-booking).
• <script-path> – Relative path to the helper script under the skill's scripts/ directory (e.g., scripts/zipcode_search.py).
• -- – A separator that distinguishes CLI options from arguments passed directly to the helper script.
• <skill-specific-args> – Parameters required by the specific skill, such as addresses, dates, or IDs.

Global Installation and Shorter Alias

When you install the package globally using npm i -g @nomadamas/k-skill, the CLI becomes available through a shorter alias. According to the packages/k-skill-cli/package.json configuration, the binary is registered as k-skill【/cache/repos/github.com/NomaDamas/k-skill/main/packages/k-skill-cli/package.json#L2-L9】.

The global syntax becomes:

k-skill exec <skill-name> <script-path> -- <skill-specific-args>

This eliminates the need to prefix commands with npx -y on every execution.

Practical Examples from the Source Code

The repository's skill directories contain instruction.md files with concrete execution examples.

Korean Postal Code Lookup (zipcode-search)

To find a Korean postal code using the zipcode-search skill, execute:

npx -y @nomadamas/k-skill@0 exec zipcode-search scripts/zipcode_search.py -- "서울특별시 강남구 테헤란로 123"

This example appears in zipcode-search/instruction.md at lines 101-102【/cache/repos/github.com/NomaDamas/k-skill/main/zipcode-search/instruction.md#L101-L102】.

SRT Train Seat Booking (srt-booking)

For searching SRT train seats, use:

npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py -- seats 수서 부산 20260328 080000 --train-id <train_id>

This command is documented in srt-booking/instruction.md between lines 85-97【/cache/repos/github.com/NomaDamas/k-skill/main/srt-booking/instruction.md#L85-L97】.

Interpark Ticket Availability (ticket-availability)

Check ticket availability with:

npx -y @nomadamas/k-skill@0 exec ticket-availability scripts/ticket_availability.py -- schedule "https://tickets.interpark.com/goods/26000541"

Reference this pattern in ticket-availability/instruction.md at lines 62-63【/cache/repos/github.com/NomaDamas/k-skill/main/ticket-availability/instruction.md#L62-L63】.

Running Health Checks

Most skills support a health-check mode:

npx -y @nomadamas/k-skill@0 exec <skill-name> scripts/<script>.py -- health

This pattern appears across multiple skill instruction files to verify proper configuration before executing irreversible operations.

How the CLI Executes Skills Internally

The k-skill CLI implementation relies on several key files within packages/k-skill-cli/:

• packages/k-skill-cli/bin/k-skill.js – The executable entry point that parses exec arguments and dispatches to the skill assembler.
• packages/k-skill-cli/src/assemble.js – Assembles the runtime-aware instruction set before execution, handling environment detection for browsers, vaults, and proxies.
• packages/k-skill-cli/src/execute.js – Carries out the exec command by invoking the helper script with supplied arguments.

The runtime enforces safety by gating irreversible actions behind an explicit user clarify step, ensuring destructive operations require confirmation.

Summary

• Use npx -y @nomadamas/k-skill@0 exec followed by skill name, script path, and arguments to run skills without installation.
• Install globally with npm i -g @nomadamas/k-skill to use the shorter k-skill exec alias.
• Place -- before skill-specific arguments to prevent the CLI from interpreting them as its own options.
• Reference packages/k-skill-cli/package.json for binary definitions and entry points.
• Each skill's instruction.md file contains exact command examples for that specific automation.

Frequently Asked Questions

How do I run a k-skill without installing it globally?

Use the npx command: npx -y @nomadamas/k-skill@0 exec <skill-name> <script-path> -- <args>. The -y flag auto-accepts the download and @nomadamas/k-skill@0 pins to the latest version, allowing immediate execution without permanent installation.

What does the -- separator do in k-skill CLI commands?

The -- separator distinguishes between arguments intended for the k-skill CLI itself and those meant for the skill's helper script. Everything after -- gets passed directly to the Python script (e.g., scripts/zipcode_search.py), preventing the CLI from interpreting skill parameters like --train-id as its own flags.

Where are the executable scripts located within a skill?

Executable scripts reside in the scripts/ subdirectory of each skill folder. For example, the zipcode-search skill stores its main logic in scripts/zipcode_search.py, which you reference as <script-path> when invoking the exec command.

How does the CLI handle irreversible actions?

According to the runtime implementation in packages/k-skill-cli/src/execute.js, the CLI gates irreversible actions behind an explicit user clarify step. This forces confirmation before destructive operations execute, ensuring users understand the consequences before proceeding.

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