git:20260614.d043ce7 to git:20260816.ff0cd32

17 added, 119 removed. Audit A to A.

---

name: skill-creator

description: Guide for creating effective skills. Use when users want to create or update a skill that extends agent's capabilities.

---

# Skill Creator

Guidance for creating modular skill packages that extend Kimi's capabilities.

## Core Principles

- ### Concise is Key

- Context window is limited. Skills share space with system prompt, history, and user requests. Only add information Kimi doesn't already know. Prefer concise examples over verbose explanations.

- ### Degrees of Freedom

- Match specificity to task fragility:

- - **High freedom (text)**: Multiple valid approaches, context-dependent decisions

- - **Medium freedom (pseudocode/scripts with params)**: Preferred pattern with acceptable variation

- - **Low freedom (specific scripts)**: Fragile operations requiring consistency

- ### Anatomy

- ```

- skill-name/

- ├── SKILL.md (required)

- │ ├── YAML frontmatter: name, description, optional type

- │ └── Markdown instructions

- └── Bundled Resources (optional)

- ├── scripts/ - Executable code

- ├── references/ - Documentation loaded on demand

- └── assets/ - Templates, images, fonts

- ```

- **SKILL.md frontmatter**: `name` and `description` are required. `type` is optional (`standard` or `flow`). Description must include what the skill does AND when to use it.

- **SKILL.md body**: Instructions loaded only after skill triggers. Keep under 500 lines.

- **Resources**:

- - `scripts/`: Deterministic, reusable code (token efficient)

- - `references/`: Large docs/schemas loaded when needed (keep >10k word files here)

- - `assets/`: Output resources (templates, images)

- **Do NOT include**: README.md, CHANGELOG.md, or other auxiliary docs.

- ### Progressive Disclosure

+ - **Concise is Key** — context is limited; only add info Kimi doesn't already know; prefer concise examples over verbose explanations.

+ - **Degrees of Freedom** — match specificity to task fragility: high freedom (text), medium (pseudocode/scripts with params), low (specific scripts needing consistency).

+ - **Anatomy** — `SKILL.md` (required: YAML frontmatter `name`+`description`, optional `type`; body under 500 lines) + optional resources: `scripts/` (executable code), `references/` (large docs, loaded on demand — keep >10k-word files here), `assets/` (templates/images). Do NOT include README.md/CHANGELOG.md.

- Three-level loading system:

- 1. **Metadata** (name + description) - Always in context

- 2. **SKILL.md body** - When skill triggers

- 3. **Bundled resources** - As needed

+ ## Progressive Disclosure

- Keep SKILL.md lean; move detailed info to references. Link reference files from SKILL.md with clear guidance on when to read them. Avoid deeply nested references.

+ 1. **Metadata** (name + description) — always in context

+ 2. **SKILL.md body** — when skill triggers

+ 3. **Bundled resources** — as needed

- **Patterns**:

- - High-level guide with references: Core workflow in SKILL.md, details in linked files

- - Domain-specific org: `references/finance.md`, `references/sales.md`, etc.

- - Conditional details: Basic content in SKILL.md, advanced features linked

+ Keep SKILL.md lean; link reference files with clear guidance on when to read them; avoid deeply nested references.

## Locations

- Skills are discovered from the following locations, in priority order (most specific wins):

- 1. `--skills-dir` (overrides default discovery)

- 2. Project: `.kimi/skills`, `.claude/skills`, `.codex/skills`, `.agents/skills`

- 3. User: `~/.config/agents/skills`, `~/.agents/skills`, `~/.kimi/skills`, `~/.claude/skills`, `~/.codex/skills`

- 4. Built-in: bundled with kimi-cli

- Within each layer, brand-specific directories (`.kimi`, `.claude`, `.codex`) take priority over generic ones (`.agents`, `.config/agents`). Use `--skills-dir` to test skills without placing them in the standard paths.

+ Priority (most specific wins): `--skills-dir` → project (`.kimi`/`.claude`/`.codex`/`.agents` skills) → user (`~/.config/agents/skills`, `~/.agents/skills`, `~/.kimi/skills`, ...) → built-in. Brand-specific dirs (`.kimi`, `.claude`, `.codex`) beat generic (`.agents`, `.config/agents`).

## Supported Forms

- ### Subdirectory form (canonical)

- ```

- <skills-root>/<skill-name>/SKILL.md

- ```

- Use this for skills with bundled resources.

- ### Flat form

- ```

- <skills-root>/<skill-name>.md

- ```

- Use this for single-file skills with no extra resources. The file stem is used as the skill name when `name` is omitted from frontmatter.

+ - **Subdirectory (canonical)**: `<skills-root>/<skill-name>/SKILL.md` — use for bundled resources.

+ - **Flat**: `<skills-root>/<skill-name>.md` — single-file skills; stem = name when `name` omitted.

## Creation Process

- 1. **Understand**: Gather concrete usage examples

- 2. **Plan**: Identify reusable resources (scripts, references, assets)

- 3. **Initialize**: Create directory with SKILL.md and resource folders

- 4. **Edit**: Implement resources and write SKILL.md

- 5. **Validate**: Check frontmatter, naming, structure, and discovery

- 6. **Iterate**: Improve based on real usage

- ### Naming

- - Lowercase letters, digits, hyphens only

- - Under 64 characters

- - Verb-led phrases: `gh-address-comments`, `linear-address-issue`

- - Folder name matches skill name

- ### Writing SKILL.md

- **Frontmatter**:

- ```yaml

- ---

- name: skill-name

- description: What it does. Use when: (1) condition A, (2) condition B...

- ---

- ```

- For a flow skill, add `type: flow` and include a `mermaid` or `d2` fenced code block:

- ```yaml

- ---

- name: approval-flow

- description: Route requests through an approval flow. Use when: user asks for gated workflows.

- type: flow

- ---

- ```

- **Body**: Use imperative form. Include:

- - Multi-step workflows with decision points

- - Output formats and quality standards

- - Links to reference files for detailed info

+ 1. Understand → 2. Plan (identify reusable resources) → 3. Initialize (dir + SKILL.md + resource folders) → 4. Edit → 5. Validate (frontmatter, naming, structure, discovery) → 6. Iterate.

- ### Testing

+ **Naming**: lowercase letters/digits/hyphens, <64 chars, verb-led (e.g. `gh-address-comments`); folder name matches skill name.

- Test all scripts before use. For many similar scripts, test a representative sample. Verify the skill is discoverable by running:

+ **Frontmatter**: `name`, `description` (what + when to use); `type: flow` adds a `mermaid`/`d2` block.

- ```bash

- kimi --skills-dir <path-to-parent-skills-root>

- ```

+ **Body**: imperative form; multi-step workflows with decision points; output formats/quality standards; links to reference files.

- ### Validation

+ ## Testing & Validation

- Before considering a skill complete, verify:

- - [ ] Frontmatter starts with `---` and ends with `---`

- - [ ] `name` matches the directory or file stem

- - [ ] `description` is present and describes what + when

- - [ ] `type` is either `standard` or `flow` (omit for standard)

- - [ ] Flow skills contain a valid `mermaid` or `d2` code block

- - [ ] No README.md, CHANGELOG.md, or other auxiliary docs

- - [ ] Resource files are referenced clearly from SKILL.md

+ Test scripts (representative sample for many similar ones); verify discovery with `kimi --skills-dir <parent-root>`. Before complete: frontmatter starts/ends with `---`; `name` matches dir/stem; `description` present (what + when); `type` is `standard` or `flow` (omit for standard); flow skills have a valid `mermaid`/`d2` block; no README.md/CHANGELOG.md; resources referenced clearly from SKILL.md.