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

> Discover the purpose of skill.json in k-skill. This file defines metadata, capabilities, and documentation, guiding CLI and build tooling for skill discovery, registration, and execution. Learn more in our complete guide.

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

---

**The [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) located in its root directory alongside implementation files like `src/` and [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) combines descriptive metadata with functional declarations. Here is the configuration from [`zipcode-search/skill.json`](https://github.com/NomaDamas/k-skill/blob/main/zipcode-search/skill.json):

```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`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) files to build the command interface. When you install the k-skill bundle, the following registration occurs automatically:

```bash

# 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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) for inline help generation

This automation ensures that skills remain modular; developers only need to edit [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) to change how the framework interacts with their code.

## Key Files in the skill.json Workflow

Several files interact with [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) during development and runtime:

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

## Summary

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