# What Is the Role of instruction.md in k-skill?

> Discover how instruction.md is the core of k-skill, defining skills behavior, inputs, workflows, and error handling for documentation, CLI, and execution.

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

---

**The [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) file serves as the single source of truth for every skill in the k-skill repository, defining behavior, inputs, workflows, and error handling while powering documentation generation, CLI stub creation, and runtime execution.**

The [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) file is the cornerstone of the NomaDamas/k-skill architecture. Every skill directory contains this markdown file to specify what the skill does, when to use it, and how it handles failures. Understanding the role of [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) in k-skill is essential for developers who want to create, modify, or debug skills within this ecosystem.

## Authoritative Skill Specification

Each skill directory—such as `zipcode-search` or `used-car-price-search`—contains an [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) that acts as the canonical reference for both humans and tools. This file details:

- **Skill purpose** – What the skill does and when to use it
- **Prerequisites** – Required setup or dependencies
- **Input parameters** – Expected arguments and data types
- **Step-by-step workflow** – The execution logic
- **Completion criteria** – Success indicators
- **Failure modes** – Error handling and edge cases

Because [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) exists in every skill folder, it provides a consistent, human-readable specification that developers can reference without diving into implementation code.

## CLI Stub Generation and Synchronization

The k-skill toolchain uses [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) to generate executable CLI wrappers. The script [`scripts/generate-skill-stubs.js`](https://github.com/NomaDamas/k-skill/blob/main/scripts/generate-skill-stubs.js) reads both [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) and [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) to produce a generated file called [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md). This generated stub includes a header comment indicating its automated origin:

```markdown
<!-- k-skill:cli-stub — generated by scripts/generate-skill-stubs.js; edit skill.json / instruction.md instead -->

```

Once generated, [`scripts/sync-cli-skills.js`](https://github.com/NomaDamas/k-skill/blob/main/scripts/sync-cli-skills.js) copies each skill's [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) into the `packages/k-skill-cli/skills/` directory. The copy operation uses `path.join(skillDir, "instruction.md")` to ensure the CLI package has access to the latest specifications at runtime.

## Runtime Assembly and Execution

When the CLI executes a skill, the runtime loads the specification directly from [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md). In [`packages/k-skill-cli/src/assemble.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/src/assemble.js), the system reads the file using:

```javascript
fs.readFileSync(path.join(dir, "instruction.md"), "utf8")

```

This allows the runtime to inject the human-readable description into the skill execution context, ensuring that the documentation available to developers matches the behavior presented to end users.

For example, running the zipcode search skill via the CLI works because [`assemble.js`](https://github.com/NomaDamas/k-skill/blob/main/assemble.js) loads the corresponding [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) and hands it to the runtime:

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

```

## Testing and Validation

The repository enforces the presence of [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) through continuous integration. The test file [`scripts/skill-docs.test.js`](https://github.com/NomaDamas/k-skill/blob/main/scripts/skill-docs.test.js) verifies that every skill directory contains both [`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 validation ensures the rule "[`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) must be kept" is never violated, preventing accidental loss of the specification.

## Working with instruction.md Programmatically

You can read a skill's specification programmatically using the same approach the CLI uses internally. The following snippet mirrors the logic found in [`packages/k-skill-cli/src/assemble.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/src/assemble.js):

```javascript
const fs = require('fs');
const path = require('path');

function getInstruction(skillName) {
  const file = path.join(__dirname, '..', skillName, 'instruction.md');
  return fs.readFileSync(file, 'utf8');
}

// Example: retrieve the specification for the zip code search skill
console.log(getInstruction('zipcode-search'));

```

This pattern allows external tools to parse skill definitions without hardcoding paths, maintaining compatibility with the k-skill ecosystem.

## Summary

- **Authoritative specification**: Every skill's [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) defines behavior, inputs, workflows, and error handling in human-readable format.
- **CLI integration**: [`scripts/generate-skill-stubs.js`](https://github.com/NomaDamas/k-skill/blob/main/scripts/generate-skill-stubs.js) creates [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) wrappers from [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md), while [`scripts/sync-cli-skills.js`](https://github.com/NomaDamas/k-skill/blob/main/scripts/sync-cli-skills.js) copies specifications to `packages/k-skill-cli/skills/`.
- **Runtime dependency**: [`packages/k-skill-cli/src/assemble.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/src/assemble.js) loads [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) at runtime via `fs.readFileSync` to provide execution context.
- **CI enforcement**: [`scripts/skill-docs.test.js`](https://github.com/NomaDamas/k-skill/blob/main/scripts/skill-docs.test.js) validates that every skill directory contains the required [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) file.

## Frequently Asked Questions

### What happens if instruction.md is missing from a skill directory?

The continuous integration tests in [`scripts/skill-docs.test.js`](https://github.com/NomaDamas/k-skill/blob/main/scripts/skill-docs.test.js) will fail, blocking the build. This enforcement ensures that no skill can be deployed without its canonical specification, maintaining ecosystem integrity according to the NomaDamas/k-skill source code.

### Can I edit the generated SKILL.md file directly?

No. The generated [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) files contain a comment explicitly stating they are generated by [`scripts/generate-skill-stubs.js`](https://github.com/NomaDamas/k-skill/blob/main/scripts/generate-skill-stubs.js) and instructing developers to edit [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) or [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) instead. Changes to [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) would be overwritten during the next stub generation cycle.

### How does the CLI runtime access instruction.md files?

The [`scripts/sync-cli-skills.js`](https://github.com/NomaDamas/k-skill/blob/main/scripts/sync-cli-skills.js) script copies each skill's [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) into `packages/k-skill-cli/skills/` during the build process. At runtime, [`packages/k-skill-cli/src/assemble.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/src/assemble.js) loads the file using `fs.readFileSync(path.join(dir, "instruction.md"), "utf8")` and injects its contents into the execution context.

### What is the relationship between skill.json and instruction.md?

While [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) provides the human-readable specification, [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) contains structured metadata. The stub generator [`scripts/generate-skill-stubs.js`](https://github.com/NomaDamas/k-skill/blob/main/scripts/generate-skill-stubs.js) reads both files to create the CLI wrapper, ensuring that machine-readable configuration and human-readable documentation remain synchronized.