Skill Creator — MiMo Code

Create skills that extend MiMo Code with specialized workflows. Leverages task, bash, read, write, edit, skill tools natively.

Three Gates (Pre-flight)

All must pass before starting. If any is no → stop.

1. MiMo Code 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 — only 3 fields are read by MiMo Code:

name: kebab-case       # Required. Letters, digits, hyphens. Max 64 chars.
description: >         # Required. Max 500 chars. Triggering conditions ONLY.
  Use when [trigger], [trigger], or [symptom].
hidden: true           # Optional. true = loaded but not in available_skills list.

Placement — MiMo Code discovers SKILL.md recursively from:

• Project: .mimocode/skills/, .claude/skills/, .agents/skills/, .codex/skills/
• Global: ~/.config/mimocode/skills/, ~/.claude/skills/, ~/.agents/skills/**
• Config: skills.paths and skills.urls in mimocode.json

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".

Creation: 7 Steps

1. Classify Complexity

Start Simple. Easier to add than remove.

2. Capture Intent

From conversation history first: tools used, steps, corrections, I/O formats. Fill gaps: what should it do? when trigger? expected output? test cases needed?

3. Choose Freedom Level

• High (text): many valid approaches
• Medium (parameterized scripts): preferred pattern exists
• Low (specific scripts): fragile ops, consistency critical

4. Write SKILL.md

Body structure: Overview → When to Use → Core Workflow → Quick Reference → Common Mistakes → Integration

Rules:

• Imperative form, explain the why
• One excellent example > many mediocre
• ALWAYS/NEVER in caps → yellow flag → reframe with reasoning
• Context window is shared — every token must earn its place
• Cross-reference by name (compose:tdd), not @link (force-loads, burns context)
• Target: redundant content < 20%

Skill types need different structures:

5. Validate

• YAML valid, name + description present
• Description < 500 chars, "Use when..." format
• No placeholders, referenced paths exist

6. Smoke Test

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

task({
  action: "spawn",
  agent: "general",
  description: "smoke-test-with-skill",
  prompt: "Follow these instructions:\n\n## Skill: <name>\n<paste SKILL.md>\n\n## Task\n<test task>"
})

Verify baseline differs. Do NOT tell subagent it's being tested.

7. Iterate

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

8. Verify before package

python3 scripts/prove_skill.py <path-to-target-skill>
python3 scripts/prove_skill.py <path-to-target-skill> --strict

Same shared gate as other platforms: intent triggers, portable assets, optional automated check. Prefer scripts/verify.sh or tests/ when the skill has code. Compare reports after edits with baseline_gate.py. See ../references/verification.md and ../references/quality-principles.md.

Evaluation Pipeline

Architecture

MiMo Code subagents return results in response but do NOT reliably write to disk. Controller persists all results. Use spawn for parallel eval, run for blocking graders.

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 — batch 2-3 cases (4-6 concurrent):

task({ action: "spawn", agent: "general", description: "eval-0-with",
       prompt: "<SKILL.md content>\n\nTask: <prompt>" })
task({ action: "spawn", agent: "general", description: "eval-0-without",
       prompt: "Solve this task without any external instructions.\n\nTask: <same prompt>" })

3. Persist on notification — immediately write responses:

evals/iter-N/eval-<ID>/with_skill.md
evals/iter-N/eval-<ID>/without_skill.md

4. Grade — run blocking grader 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 (always pass), flaky (high variance), broken (always fail both).

Metrics

Description Optimization

1. Create 20 realistic eval queries (should-trigger + should-not-trigger near-misses)
2. User reviews
3. Spawn subagent per query to test triggering — 3 runs each
4. Analyze failures → improve description → re-run (up to 5 iterations)
5. Select by test score (not train) to avoid overfitting
6. Apply to frontmatter

Bulletproofing Discipline Skills

Close loopholes explicitly. Build rationalization table from testing:

Red Flags list → easy self-check:

## Red Flags — STOP
- Code before test
- "This is different because..."
**All = Delete. Start over.**

Problem Classification

P0 (blocking) → P1 (noticeable) → P2 (nice).

Compose Integration

Skills can reference compose skills: compose:ask, compose:tdd, compose:verify, compose:plan. Use task tool for subagent dispatch, skill tool for loading skills.

Key: Compose skills do NOT appear in subagents' available_skills. Pass SKILL.md content directly in subagent prompt.

Packaging

1. Validate frontmatter
2. python3 scripts/prove_skill.py <skill> --strict
3. Package only when verification passes:

cd <root> && zip -r my-skill.skill my-skill/ \
  -x "my-skill/evals/*" -x "my-skill/iter-*/*" -x "*__pycache__*"

5 Common Failures

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.