What Is the Purpose of skill.json in k-skill? A Complete Guide

The skill.json file serves as the single source of truth for every individual k-skill, defining metadata, capability profiles, and documentation frontmatter that the CLI and build tooling use to discover, register, and execute skills.

In the NomaDamas/k-skill repository, every skill ships with a skill.json located in its root directory alongside implementation files like src/ and instruction.md. This JSON configuration drives the entire skill lifecycle, from CLI command generation to runtime environment validation, without requiring changes to central framework code.

Core Functions of skill.json in k-skill

The skill.json file fulfills five critical roles that make the k-skill ecosystem extensible and self-describing.

Metadata Definition and CLI Registration

The name and description fields declare the skill’s identity and purpose. The k-skill-cli package reads these values to automatically construct the command tree, mapping each skill to a command path like /k-skill:<skill-name>. This eliminates manual CLI registration; adding a new skill directory with a valid skill.json immediately makes it available to users.

Runtime Capability Hinting

The profiles array lists required capabilities such as lookup, proxy, vault, browser, or operations. Before executing a skill, the agent checks this array to verify the current environment satisfies dependencies—for example, confirming a browser session exists for web automation skills or that secret keys are available for vault-dependent operations. This prevents runtime failures by validating prerequisites upfront.

Documentation Generation

The frontmatter field contains a YAML-style block with license, category, locale, and development phase metadata. When you run npm run generate:skill-stubs, the tooling extracts this block to generate the aggregate SKILL.md file and individual feature documentation in docs/features/<skill>.md. This keeps human-readable guides synchronized with machine-readable configuration.

Bundle Declaration

The optional bundle field maps helper scripts or static assets that must accompany the skill. The build system copies these files into the final package during compilation, ensuring the skill operates correctly when distributed without manual file management.

Version-Agnostic Integration

Because every skill adheres to the same skill.json schema, the generic CLI, documentation generator, and release tooling remain unchanged when new skills are added. This schema consistency allows the repository to scale to dozens of skills without central code modifications.

skill.json Schema and Structure

A typical skill.json combines descriptive metadata with functional declarations. Here is the configuration from 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" ],
  "frontmatter": "name: zipcode-search\ndescription: Look up a Korean postcode and official English address from a known address with the official ePost integrated search page.\nlicense: MIT\nmetadata:\n  category: utility\n  locale: ko-KR\n  phase: v2"
}

The profiles array in this example declares that the skill requires the lookup capability, while the frontmatter string provides structured data for documentation generators.

How skill.json Powers the k-skill CLI

The CLI implementation in packages/k-skill-cli/ recursively scans the repository for skill.json files to build the command interface. When you install the k-skill bundle, the following registration occurs automatically:

# The CLI reads zipcode-search/skill.json and generates the command stub

k-skill zipcode-search --address "서울특별시 강남구 테헤란로 212"

The CLI performs three actions based on the skill.json content:

1. Validates that the lookup profile is available in the current environment
2. Routes the request to the skill’s implementation directory
3. Links the command to instruction.md for inline help generation

This automation ensures that skills remain modular; developers only need to edit skill.json to change how the framework interacts with their code.

Key Files in the skill.json Workflow

Several files interact with skill.json during development and runtime:

• zipcode-search/skill.json — Core metadata definition declaring name, profiles, and frontmatter
• instruction.md — Human-readable usage guide linked to the skill’s CLI entry
• SKILL.md — Auto-generated aggregate documentation compiled from all skill frontmatter blocks
• packages/k-skill-cli/ — CLI source code that parses every skill.json to create command stubs
• docs/features/*.md — Individual feature documentation generated from the frontmatter section of each skill.json

Summary

• skill.json acts as the single source of truth for skill metadata in the k-skill framework
• The CLI (packages/k-skill-cli/) uses name and profiles to generate commands and validate runtime requirements
• Documentation is auto-generated from the frontmatter field via npm run generate:skill-stubs
• The profiles array enables environment-aware execution by declaring required capabilities like browser or vault
• The bundle field ensures all dependencies ship with the skill package
• The standardized schema allows version-agnostic skill addition without modifying central framework code

Frequently Asked Questions

What happens if skill.json is missing from a skill directory?

The k-skill-cli will not register the skill, making it invisible to the command tree and documentation generators. The build system relies on this file to determine how to package and expose the skill, so its absence prevents integration entirely.

How does the profiles array affect skill execution?

The agent inspects the profiles array before running a skill to verify the environment satisfies declared requirements. For example, a skill listing "browser" in profiles will only execute if a browser automation session is active, while "vault" indicates the need for secret key access.

Can skill.json include custom fields outside the standard schema?

While the schema supports extensibility through the optional bundle field and free-form frontmatter content, the CLI and documentation generators only process standardized keys like name, description, and profiles. Custom fields at the root level are preserved in the JSON but do not trigger built-in tooling behavior.

Where is the skill.json schema validated?

Validation occurs within the packages/k-skill-cli/ source code, which parses each skill.json during the build and runtime phases. The CLI checks for required fields and valid profile names, throwing errors if the schema is violated before the skill is registered in the command tree.

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