You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.

2026-06-2311.2k

compose-plan

XiaomiMiMo/MiMo-Code

Use when you have a spec or requirements for a multi-step task, before touching code

2026-06-2311.2k

compose-report

XiaomiMiMo/MiMo-Code

Use after implementation is verified and before merge — consolidates multiple spec iterations into a single final-state report, marks related specs, and records key lessons

2026-06-2311.2k

self-extend

XiaomiMiMo/MiMo-Code

Use when you want to evolve your own capabilities — create new tools to avoid repeating patterns, add hooks to improve your own behavior, build skills to accumulate domain knowledge, or override built-in tools to adapt to project needs. This is your self-iteration interface.

2026-06-2211.2k

name	compose:new-skill
hidden	true
description	Use when creating new skills or editing existing skills for the project or personal skill library

Writing Skills

Overview

A skill is a reusable reference guide — techniques, patterns, or tools — that helps agents find and apply effective approaches.

Skills are: Reusable techniques, patterns, tools, reference guides

Skills are NOT: Narratives about how you solved a problem once

When to Create a Skill

Create when:

Technique wasn't intuitively obvious
You'd reference this again across projects
Pattern applies broadly (not project-specific)
Others would benefit from this knowledge

Don't create for:

One-off solutions
Standard practices well-documented elsewhere
Project-specific conventions (put in project config like CLAUDE.md)
Mechanical constraints enforceable with regex/validation (automate it instead)

Skill Types

Type	Purpose	Examples
Technique	Concrete method with steps	condition-based-waiting, root-cause-tracing
Pattern	Way of thinking about problems	flatten-with-flags, test-invariants
Reference	API docs, syntax guides	tool documentation, library guides

SKILL.md Format

---
name: skill-name
description: Use when [specific triggering conditions]
---

# Skill Name

## Overview
Core principle in 1-2 sentences.

## When to Use
Bullet list with symptoms and use cases.
When NOT to use.

## Core Pattern
Before/after code comparison or step-by-step process.

## Quick Reference
Table or bullets for scanning common operations.

## Common Mistakes
What goes wrong + fixes.

Frontmatter Rules

name: letters, numbers, hyphens only (max 64 chars)
description: third-person, starts with "Use when...", max 1024 chars
Description should ONLY describe triggering conditions — never summarize the skill's workflow

Description: Why This Matters

Testing revealed that when a description summarizes the skill's workflow, agents may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused the agent to do ONE review, even though the skill's flowchart clearly showed TWO reviews.

The trap: Descriptions that summarize workflow create a shortcut the agent will take. The skill body becomes documentation it skips.

# BAD: summarizes workflow — agent may follow this instead of reading skill
description: Use when executing plans - dispatches subagent per task with code review

# BAD: too much process detail
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

# GOOD: just triggering conditions
description: Use when executing implementation plans with independent tasks

# GOOD: symptoms-focused
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

Writing Style

# BAD: first person
description: I can help you with async tests when they're flaky

# BAD: too abstract, doesn't include when to use
description: For async testing

# GOOD: third person, starts with "Use when"
description: Use when implementing any feature or bugfix, before writing implementation code

Skill Discovery Optimization (SDO)

Agents read descriptions to decide which skills to load. Make it answer: "Should I read this skill right now?"

Keyword Coverage

Use words agents would search for:

Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
Symptoms: "flaky", "hanging", "zombie", "pollution"
Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
Tools: Actual commands, library names, file types

Descriptive Naming

Use active voice, verb-first:

condition-based-waiting not async-test-helpers
creating-skills not skill-creation
root-cause-tracing not debugging-techniques

Directory Structure

skills/
  skill-name/
    SKILL.md              # Main reference (required)
    supporting-file.*     # Only if needed

Keep inline: Principles, concepts, code patterns (short examples).

Separate files for:

Heavy reference (100+ lines) — API docs, comprehensive syntax
Reusable tools — Scripts, utilities, templates

Skill Location

Personal skills: .mimocode/skills/<name>/SKILL.md

Token Efficiency

Skills load into context — every token counts.

Target word counts:

Frequently-loaded skills: < 200 words total
Other skills: < 500 words (still be concise)

Techniques:

# BAD: Document all flags inline
search-conversations supports --text, --both, --after DATE, --before DATE

# GOOD: Reference --help
search-conversations supports multiple modes and filters. Run --help for details.

# BAD: Repeat instructions from another skill
When searching, dispatch subagent with template...
[20 lines of repeated instructions]

# GOOD: Cross-reference
Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.

Cross-referencing: Use skill name only with explicit markers:

**REQUIRED BACKGROUND:** You MUST understand compose:tdd
**REQUIRED SUB-SKILL:** Use eslint-setup
Never use @ links (force-loads files, burns context)

Code Examples

One excellent example beats many mediocre ones. Choose the most relevant language:

Testing techniques → TypeScript/JavaScript
System debugging → Shell/Python
Data processing → Python

Don't implement in 5+ languages. Don't create fill-in-the-blank templates.

Testing

Before deploying, verify the skill works:

Run a realistic scenario WITHOUT the skill — observe baseline behavior
Run the same scenario WITH the skill — verify improvement
If the skill enforces discipline, test under pressure (time + sunk cost + fatigue)

For discipline-enforcing skills (TDD, verification requirements), watch for rationalization:

Excuse	Reality
"Too simple to test"	Simple code breaks. Test takes 30 seconds.
"I'll test after"	Tests passing immediately prove nothing.
"The skill is obviously clear"	Clear to you ≠ clear to other agents.

REQUIRED BACKGROUND: Use compose:tdd principles for testing discipline-enforcing skills.

Checklist

Name uses only letters, numbers, hyphens
Description starts with "Use when..." (third person, no workflow summary)
Keywords throughout for search (errors, symptoms, tools)
Content is concise — SKILL.md under 500 lines
One excellent example (not multi-language)
Tested with realistic scenarios
No redundant explanations of what the agent already knows
Supporting files only for tools or heavy reference