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

> Discover how individual skills are defined in k-skill using manifest files and markdown. Explore the self-contained directory structure and essential components like skill.json and instruction.md for comprehensive skill develop...

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

---

**In k-skill, each individual skill is defined as a self-contained directory containing a [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) manifest file that declares the skill's name, description, capability profiles, frontmatter metadata, and optional bundle mappings, alongside an [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/skill.json)** – The core manifest file that defines the skill's identity and capabilities
- **[`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md)** – Author-written documentation describing inputs, workflows, and usage
- **[`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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:

```json
{
  "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`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) stub and supports filtering and categorization within the skill ecosystem.

```json
"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:

```json
"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`](https://github.com/NomaDamas/k-skill/blob/main/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:

```markdown

## 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`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md)** file is auto-generated by [`scripts/generate-skill-stubs.js`](https://github.com/NomaDamas/k-skill/blob/main/scripts/generate-skill-stubs.js) combining data from [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) and [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/src/assemble.js), the runtime scans the workspace to discover every [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/skill.json), [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md)) exist within the skill directory
- Frontmatter metadata parses correctly

### Stub Generation

The [`scripts/generate-skill-stubs.js`](https://github.com/NomaDamas/k-skill/blob/main/scripts/generate-skill-stubs.js) utility processes valid skill definitions to generate standardized [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/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:

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

```

This command demonstrates how the runtime uses the [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) file defines individual skills through name, description, profiles, frontmatter, and optional bundle mappings.
- **Automatic discovery**: [`packages/k-skill-cli/src/assemble.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/src/assemble.js) scans and loads skill definitions without requiring registry updates.
- **Validation enforcement**: [`scripts/skill-docs.test.js`](https://github.com/NomaDamas/k-skill/blob/main/scripts/skill-docs.test.js) ensures directory names match manifest names and required files exist.
- **Documentation pipeline**: [`scripts/generate-skill-stubs.js`](https://github.com/NomaDamas/k-skill/blob/main/scripts/generate-skill-stubs.js) generates [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) files from [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) and [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) content.
- **Zero-code onboarding**: New skills are added by creating a correctly-shaped directory and [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/src/assemble.js), which scans the workspace for every [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) **`bundle`** array. This ensures [`scripts/generate-skill-stubs.js`](https://github.com/NomaDamas/k-skill/blob/main/scripts/generate-skill-stubs.js) includes them in the packaged distribution and the CLI can locate them during execution.