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

compose:new-skill

Writing Skills

Overview

When to Create a Skill