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

The 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 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 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 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 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 to generate executable CLI wrappers. The script scripts/generate-skill-stubs.js reads both instruction.md and skill.json to produce a generated file called SKILL.md. This generated stub includes a header comment indicating its automated origin:

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

Once generated, scripts/sync-cli-skills.js copies each skill's 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. In packages/k-skill-cli/src/assemble.js, the system reads the file using:

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 loads the corresponding instruction.md and hands it to the runtime:

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 through continuous integration. The test file scripts/skill-docs.test.js verifies that every skill directory contains both skill.json and instruction.md. This validation ensures the rule "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:

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 defines behavior, inputs, workflows, and error handling in human-readable format.
• CLI integration: scripts/generate-skill-stubs.js creates SKILL.md wrappers from instruction.md, while scripts/sync-cli-skills.js copies specifications to packages/k-skill-cli/skills/.
• Runtime dependency: packages/k-skill-cli/src/assemble.js loads instruction.md at runtime via fs.readFileSync to provide execution context.
• CI enforcement: scripts/skill-docs.test.js validates that every skill directory contains the required 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 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 files contain a comment explicitly stating they are generated by scripts/generate-skill-stubs.js and instructing developers to edit skill.json or instruction.md instead. Changes to 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 script copies each skill's instruction.md into packages/k-skill-cli/skills/ during the build process. At runtime, 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 provides the human-readable specification, skill.json contains structured metadata. The stub generator scripts/generate-skill-stubs.js reads both files to create the CLI wrapper, ensuring that machine-readable configuration and human-readable documentation remain synchronized.

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