Kimi Skill Creator

Skill Creator — Kimi Code

Create skills that extend Kimi Code with specialized workflows. Leverages native Agent, AgentSwarm, Bash, Read, Write, Edit, Skill, AskUserQuestion tools.

Three Gates (Pre-flight)

All must pass. If any is no → stop.

1. Kimi can't already do this well? → Skill is overhead.
2. User will use it 5+ times? → One-shot → direct prompt.
3. Model has it built-in? → Skill adds complexity, not value.

Skill Anatomy

skill-name/
├── SKILL.md          # Required — frontmatter + instructions
├── scripts/          # Optional — executable code
├── references/       # Optional — loaded on demand
└── assets/           # Optional — templates, icons, fonts

Frontmatter — Kimi Code reads these fields:

name: kebab-case              # Required (dir type). Case-insensitive.
description: >                # Required (dir type). Model uses this to decide when to load.
  Use when [trigger], [trigger], or [symptom].
type: prompt                  # prompt (default) | inline (same) | flow (manual only)
whenToUse: >                  # Trigger scenario. Also accepts when-to-use / when_to_use.
  当用户让我 [场景] 时
disableModelInvocation: false # true = block auto-invocation (only /skill: manual)
arguments:                    # Named params: $name in body. Also: $ARGUMENTS, $0, $1
  - target
  - mode

Placeholders in body: $ARGUMENTS, $0/$1/$, ${KIMI_SKILL_DIR}

Discovery — priority: Project > User > Extra > Built-in

• Project: .kimi-code/skills/, .agents/skills/
• User: ~/.kimi-code/skills/, ~/.agents/skills/
• Extra: extra_skill_dirs in config.toml

Invocation: /skill:name args (slash) or auto via description + whenToUse (unless disableModelInvocation: true or type: flow). Max nesting: 3 levels.

The #1 Mistake: Description Trap

When description summarizes the workflow, the model follows the description and skips the body.

# ❌ BAD: Summarizes workflow → model takes shortcut
description: Use for TDD — write test first, watch it fail, write minimal code

# ✅ GOOD: Triggering conditions only → forces model to read the body
description: Use when implementing features or bugfixes, before writing code

Formula: [Action verb] + [value]. Use when [trigger 1], [trigger 2], ... Include 5+ triggers. Add exclusions. Be slightly "pushy". Use whenToUse for scenario description (Chinese-friendly).

Creation: 7 Steps

1. Classify Complexity

| Tier | SKILL.md | Dirs | |------|----------|------| | Simple | many mediocre

• ALWAYS/NEVER in caps → yellow flag → reframe with reasoning
• Context window is shared — every token must earn its place
• Keep SKILL.md 100 lines
• No README, CHANGELOG, or extraneous files

Skill types need different structures:

| Type | Focus | Key section | |------|-------|-------------| | Discipline | Rules | Rationalization table + Red Flags | | Technique | How-to | Step-by-step + edge cases | | Pattern | Mental model | When to apply + counter-examples | | Reference | API/docs | Searchable index + retrieval paths |

Kimi-specific patterns:

• Use arguments for parameterized skills: $target, $mode in body
• Use type: flow for skills that should ONLY be invoked manually (no auto-trigger)
• Use disableModelInvocation: true to force explicit /skill: invocation

5. Validate

• YAML valid, name + description present
• whenToUse provides clear scenario
• No placeholders, referenced paths exist

6. Smoke Test

Spawn 2 subagents via Agent tool — one WITH skill, one WITHOUT:

Agent({
  prompt: "Follow these instructions:\n\n## Skill: \n\n\n## Task\n",
  description: "smoke-test-with-skill",
  subagent_type: "coder"
})

Verify baseline differs. Do NOT tell subagent it's being tested. Use AgentSwarm for batch parallel testing.

7. Iterate

Improve → re-test → repeat until user satisfied or progress stalls.

Evaluation Pipeline

Architecture

Subagents return results in response but do NOT reliably write to disk. Controller persists all results. Use Agent (foreground) or AgentSwarm (batch parallel) for eval runs.

Flow

1. Test cases — 10-20 prompts, 7:2:1 ratio (common/edge/anomalous):

[{"id": 0, "prompt": "user task", "expectations": ["includes X"]}]

2. Paired subagents — use AgentSwarm for batch parallel:

AgentSwarm({
  prompt_template: "## Skill: \n\n\nTask: ",
  items: ["eval-0: ", "eval-1: ", ...],
  subagent_type: "coder"
})

Baseline: same prompts without skill content.

3. Persist results — write responses to:

evals/iter-N/eval-/with_skill.md
evals/iter-N/eval-/without_skill.md

4. Grade — Agent per case:

{"expectations": [{"text": "...", "with_skill": "pass", "without_skill": "fail", "evidence": "..."}]}

5. Aggregate via Bash + Python → benchmark.md:

| Metric | with_skill | without_skill | Delta |
| Pass rate | 85% ± 5% | 35% ± 8% | +50% |

6. Analyze — non-discriminating, flaky, broken assertions.

7. Present — use AskUserQuestion for structured feedback collection.

Metrics

| Metric | Target | |--------|--------| | Routing accuracy | > 90% | | Output usability | > 80% | | Redundant tokens | && zip -r my-skill.skill my-skill/ \ -x "my-skill/evals/" -x "my-skill/iter-/" -x "__pycache__*"

Validate: name + description present, whenToUse clear, no placeholders, paths exist.

## 5 Common Failures

| # | Failure | Fix |
|---|---------|-----|
| 1 | Description too vague | 5+ trigger phrases + whenToUse |
| 2 | SKILL.md dumping ground (800+ lines) | < 500 lines, split to references/ |
| 3 | ALWAYS/NEVER caps | Explain reasoning |
| 4 | No smoke test | Run Step 6 before shipping |
| 5 | Description summarizes workflow | Triggering conditions ONLY |

## Meta-Advice

1. **Description is everything.** Great skill + bad description = invisible.
2. **Explain why.** Model generalizes better with reasoning.
3. **Draft then look fresh.** First draft: too detailed or too vague.
4. **Generalize from feedback.** Encode the principle, not the fix.
5. **Context window is shared.** Every token earns its place.
6. **Test before deploying.** 15 min testing saves hours debugging.
7. **Use Kimi-native tools.** `AgentSwarm` for parallel eval, `AskUserQuestion` for structured feedback, `TodoList` for progress tracking.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [taxueseek](https://github.com/taxueseek)
- **Source:** [taxueseek/skill-optimizer](https://github.com/taxueseek/skill-optimizer)
- **License:** MIT

Install and usage instructions live in the source repository linked above.