This page explains how to optimize skill files so that agents can discover and correctly load them. CSO governs the description field in SKILL.md frontmatter: what to put in it, what to leave out, and why the wrong content causes agents to ignore the skill body entirely.
For the broader skill file format (all frontmatter fields, section structure, etc.), see SKILL.md Format and Structure. For testing that a skill is discovered under realistic conditions, see Testing Skills with Pressure Scenarios.
Agents do not read every skill on every request. They scan description fields across all available skills and decide which ones to load for the current task. The description is the only signal an agent sees before committing to load a skill.
Discovery flow:
Sources: skills/writing-skills/SKILL.md140-178
The description field is the primary CSO lever. It lives in the YAML frontmatter of every SKILL.md file.
| Property | Value |
|---|---|
| Max total frontmatter size | 1024 characters |
| Recommended description length | Under 500 characters |
| Required prefix | Use when... |
| Voice | Third person (injected into system prompt) |
| Allowed frontmatter fields | name and description only |
Sources: skills/writing-skills/SKILL.md96-103
The description must describe when to use the skill — never what the skill does or how it works.
Sources: skills/writing-skills/SKILL.md150-172
This is the central insight behind CSO. When a description summarizes the skill's workflow, agents treat the description as a shortcut and skip reading the skill body.
Documented example from testing:
A description that said "code review between tasks" caused agents to perform one review. The skill's flowchart explicitly showed two reviews (spec compliance, then code quality). When the description was changed to "Use when executing implementation plans with independent tasks" — no workflow summary — agents correctly read the flowchart and followed the two-stage process.
The trap: Descriptions that summarize workflow create a shortcut Claude will take. The skill body becomes documentation Claude skips.
Sources: skills/writing-skills/SKILL.md154-158
Sources: skills/writing-skills/SKILL.md160-196
| Bad | Good | |
|---|---|---|
| Workflow summary | Use when executing plans - dispatches subagent per task with code review between tasks | Use when executing implementation plans with independent tasks in the current session |
| Process detail | Use for TDD - write test first, watch it fail, write minimal code, refactor | Use when implementing any feature or bugfix, before writing implementation code |
| Too vague | For async testing | Use when tests have race conditions, timing dependencies, or pass/fail inconsistently |
| Wrong person | I can help you with async tests | Use when tests have timing issues |
| Technology leak | Use when tests use setTimeout/sleep and are flaky | Use when tests have race conditions or timing dependencies |
Sources: skills/writing-skills/SKILL.md160-196
Agents find skills by matching description text against the problem they're working on. The description should contain words an agent would naturally use when describing a problem.
| Category | Examples |
|---|---|
| Error messages | "Hook timed out", "ENOTEMPTY", "race condition" |
| Symptoms | flaky, hanging, zombie, pollution |
| Synonyms | timeout/hang/freeze, cleanup/teardown/afterEach |
| Tools | Actual command names, library names, file extensions |
Include multiple synonyms for the same concept. An agent debugging a hanging test may search for "hang", "freeze", or "timeout" — cover all of them.
Sources: skills/writing-skills/SKILL.md199-205
The name field in frontmatter also affects discoverability. Names must use only letters, numbers, and hyphens — no parentheses or special characters.
| Style | Bad | Good |
|---|---|---|
| Active voice, verb-first | skill-creation | creating-skills |
| Action focus | async-test-helpers | condition-based-waiting |
| Gerunds for processes | skill-usage | using-skills |
| Core insight | debugging-techniques | root-cause-tracing |
| Problem-specific | data-structure-refactoring | flatten-with-flags |
Gerunds (verb + -ing) work well for process skills because they describe the action being taken.
Sources: skills/writing-skills/SKILL.md208-275
Skills that are loaded frequently (especially getting-started workflows) consume context tokens on every invocation. Keeping descriptions and skill bodies concise matters.
| Skill Type | Target |
|---|---|
| Getting-started workflows | < 150 words each |
| Frequently-loaded skills | < 200 words total |
| Other skills | < 500 words |
Reference --help instead of documenting all flags inline:
# In SKILL.md
search-conversations supports multiple modes and filters. Run --help for details.
Rather than listing every flag in the skill body.
Cross-reference other skills instead of repeating workflow:
Always use subagents (50-100x context savings). REQUIRED: Use superpowers:other-skill-name for workflow.
Compress examples to minimal form:
| Style | Word count | Example |
|---|---|---|
| Verbose | ~42 words | your human partner: "How did we handle authentication errors in React Router before?" You: I'll search past conversations for React Router authentication patterns. [Dispatch subagent with search query...] |
| Compressed | ~20 words | Partner: "How did we handle auth errors in React Router?" You: Searching... [Dispatch subagent → synthesis] |
Verify word count with wc -w skills/path/SKILL.md.
Sources: skills/writing-skills/SKILL.md213-264
The relationship between the description field and the skill body can be modeled as a contract between two concerns:
If the description contains workflow content, the body contract breaks: agents substitute description for body.
Sources: skills/writing-skills/SKILL.md150-158
Before deploying a skill, verify these CSO properties:
| Check | Criterion |
|---|---|
Starts with Use when... | First two words of description |
| Triggering conditions only | No steps, workflow, or process summary |
| Third-person voice | Not "I can help..." |
| Under 500 characters (recommended) | wc -c on description string |
| Total frontmatter under 1024 chars | Includes name + description |
| Keyword-rich | Covers synonyms, error messages, symptoms |
Name uses only [a-z0-9-] | No parentheses or special chars |
| Technology scope correct | Tech-specific iff skill is tech-specific |
For the complete pre-deployment checklist including TDD phases, see Skill Creation Checklist.
Sources: skills/writing-skills/SKILL.md96-103 skills/writing-skills/SKILL.md199-210 skills/writing-skills/SKILL.md605-630
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.