How Individual Skills Are Defined in k-skill: A Complete Guide to the Manifest-Based Architecture

In k-skill, each individual skill is defined as a self-contained directory containing a skill.json manifest file that declares the skill's name, description, capability profiles, frontmatter metadata, and optional bundle mappings, alongside an instruction.md documentation file.

The NomaDamas/k-skill repository implements a modular architecture where capabilities are organized into discrete, discoverable units. Understanding how individual skills are defined in k-skill requires examining the manifest-driven system that enables runtime discovery, validation, and execution without modifying core framework code.

The Skill Directory Structure

Each individual skill resides in its own top-level directory (e.g., zipcode-search/, korean-spell-check/). This self-contained approach means all assets, documentation, and metadata live together, allowing the skill to function as an independent package within the workspace.

A complete skill directory typically contains:

• skill.json – The core manifest file that defines the skill's identity and capabilities
• instruction.md – Author-written documentation describing inputs, workflows, and usage
• SKILL.md – A generated stub that ties the manifest to the runtime CLI
• Implementation scripts – Helper binaries or scripts referenced in the bundle (e.g., Python, Bash, or Node files)

The skill.json Manifest

The foundation of how individual skills are defined in k-skill rests in the skill.json file. This JSON manifest provides the runtime and CLI with essential metadata required for discovery and execution.

name and description

The name field serves as the unique identifier used when invoking the skill via CLI commands (npx ... exec <name>). The description provides a human-readable summary of the skill's purpose.

From the zipcode-search skill:

{
  "name": "zipcode-search",
  "description": "Look up a Korean postcode and official English address from a known address with the official ePost integrated search page.",
  "profiles": ["lookup"]
}

profiles for Capability Negotiation

The profiles array declares capability profiles such as lookup, proxy, browser, or operations. These profiles drive runtime selection and capability negotiation, allowing the system to match tasks with appropriate skills based on their declared capabilities.

frontmatter Metadata

The frontmatter field contains a YAML block storing additional metadata including license, locale, category, and development phase. This metadata is used to generate the human-readable SKILL.md stub and supports filtering and categorization within the skill ecosystem.

"frontmatter": "name: zipcode-search\ndescription: Look up a Korean postcode ...\nlicense: MIT\nmetadata:\n  category: utility\n  locale: ko-KR\n  phase: v2"

bundle for Asset Mapping

The optional bundle array specifies file-mapping objects that instruct the build system which scripts, binaries, or assets belong to the skill and should be packaged during installation. Each mapping defines source and destination paths:

"bundle": [
  { "from": "scripts/zipcode_search.py", "to": "scripts/zipcode_search.py" },
  { "from": "bin/zipcode_helper", "to": "bin/zipcode_helper" }
]

Supporting Documentation Files

instruction.md

The instruction.md file contains the skill's author-written documentation, detailing inputs, workflows, and execution patterns. This file provides the contextual knowledge necessary for users (and AI systems) to understand how to interact with the skill correctly.

Example excerpt showing input specifications:

## Inputs

- 주소 키워드
  - 도로명 + 건물번호
  - 시/군/구 + 도로명
  - 동/리 + 지번

## Workflow

1. Query the official ePost page ...
2. Fetch the HTML with curl ...
3. Prefer the shipped helper for repeatable execution ...

Generated SKILL.md

The SKILL.md file is auto-generated by scripts/generate-skill-stubs.js combining data from skill.json and instruction.md. This stub serves as the CLI-adapter interface that bridges the manifest definition with the runtime execution environment.

Runtime Discovery and Validation

The k-skill CLI implements automated processes to manage individual skill definitions without manual registration.

Discovery via assemble.js

In packages/k-skill-cli/src/assemble.js, the runtime scans the workspace to discover every skill.json manifest. This scanning mechanism builds the runtime mapping that connects skill names to their respective directories and capabilities.

Validation via skill-docs.test.js

The scripts/skill-docs.test.js file enforces integrity constraints on skill definitions. This validation suite ensures:

• Each manifest's name matches its containing directory name
• Required files (skill.json, instruction.md) exist within the skill directory
• Frontmatter metadata parses correctly

Stub Generation

The scripts/generate-skill-stubs.js utility processes valid skill definitions to generate standardized SKILL.md files, ensuring consistent documentation formatting across all skills in the repository.

Executing a Defined Skill

Once defined, individual skills are executed through the unified CLI interface. The system resolves the skill name to its directory via the assembled manifest map, then executes the specified script with provided arguments:

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

This command demonstrates how the runtime uses the skill.json definition to locate the zipcode-search directory and execute the bundled Python script with the provided address parameter.

Summary

• Self-contained directories: Each skill occupies a top-level folder (e.g., zipcode-search/) containing all necessary assets and metadata.
• Manifest-driven definition: The skill.json file defines individual skills through name, description, profiles, frontmatter, and optional bundle mappings.
• Automatic discovery: packages/k-skill-cli/src/assemble.js scans and loads skill definitions without requiring registry updates.
• Validation enforcement: scripts/skill-docs.test.js ensures directory names match manifest names and required files exist.
• Documentation pipeline: scripts/generate-skill-stubs.js generates SKILL.md files from skill.json and instruction.md content.
• Zero-code onboarding: New skills are added by creating a correctly-shaped directory and skill.json—no changes to core framework code required.

Frequently Asked Questions

What happens if the name in skill.json does not match the directory name?

According to scripts/skill-docs.test.js, the validation suite will fail because the test enforces that each manifest's name field must exactly match its containing directory name. This constraint ensures the runtime can reliably map CLI invocations to filesystem locations.

Can a skill exist without a bundle array in skill.json?

Yes. The bundle field is optional. Skills that rely entirely on external APIs or standard system commands without custom helper scripts do not need to declare bundle mappings. The runtime will still discover and execute the skill based on the core manifest fields.

How does the runtime know which skills are available?

The runtime discovers available skills through packages/k-skill-cli/src/assemble.js, which scans the workspace for every skill.json file. This assembly process builds a runtime mapping that connects skill identifiers to their filesystem locations and declared capability profiles.

Where should implementation scripts be placed within a skill directory?

Implementation scripts should reside in the scripts/ or bin/ subdirectories within the skill's top-level folder, then explicitly mapped in the skill.json bundle array. This ensures scripts/generate-skill-stubs.js includes them in the packaged distribution and the CLI can locate them during execution.

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