Use when creating new skill files, editing existing SKILL.md files, or reviewing skills before deployment — covers structure, CSO (discoverability), and quality standards
The English summary is being prepared. Showing the original description.
Run score Not tested
See how to installReview the instructions the agent will receive before you install.
A skill is a reference guide for proven techniques, patterns, or tools. Skills help future Claude instances find and apply effective approaches.
Skills are: Reusable techniques, patterns, tools, reference guides
Skills are NOT: Narratives about how you solved a problem once, project-specific conventions (those go in CLAUDE.md)
Frontmatter (YAML):
name, descriptionname: Letters, numbers, hyphens only — no parentheses or special charsdescription: Third-person, describes ONLY when to use (NOT what it does) — see CSO section---
name: skill-name
description: Use when [specific triggering conditions and symptoms]
user-invocable: true # only if user should invoke with /skill-name
---
# 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 comparison or workflow steps.
## Quick Reference
Table or bullets for scanning.
## Common Mistakes
What goes wrong + fixes.
The description field is the discovery mechanism. Claude reads it to decide which skills to load.
NEVER summarize the skill's workflow in the description.
Why this matters: Testing revealed that when a description summarizes the workflow, Claude follows the description instead of reading the full skill body. A description saying "code review between tasks" caused Claude to do ONE review, even though the skill's flowchart showed TWO reviews. Changing the description to triggering conditions only fixed it.
The trap: Descriptions that summarize workflow create a shortcut Claude will take. The skill body becomes documentation Claude skips.
# BAD: Summarizes workflow — Claude may follow this instead of reading skill
description: Use when executing plans - dispatches subagent per task with code review between tasks
# GOOD: Just triggering conditions
description: Use when executing implementation plans with independent tasks in the current session
Content rules:
Include words Claude would search for:
Skills that load frequently must be concise.
| Skill type | Target word count |
|---|---|
| Frequently-loaded workflows | < 200 words |
| Other skills | < 500 words |
Techniques:
--help instead of documenting all flags inline| Type | Description | Examples |
|---|---|---|
| Technique | Concrete method with steps | root-cause-trace, cross-layer-check |
| Pattern | Way of thinking about problems | careful, tdd |
| Reference | API docs, tool documentation | playwright, cocoindex-code |
.claude/skills/
skill-name/
SKILL.md # Main reference (required)
supporting-file.* # Only if needed for heavy reference or reusable tools
Keep inline: principles, concepts, code patterns < 50 lines.
Separate file for: heavy reference (100+ lines), reusable scripts/templates.
Before deploying any skill:
name uses only letters, numbers, hyphensdescription starts with "Use when..." — no workflow summaryclaude/README.md skills table (required by self-maintenance rule)| Mistake | Fix |
|---|---|
| Description summarizes workflow | Rewrite as triggering conditions only |
| Multiple language examples | Pick the most relevant language, one good example |
| Narrative storytelling | Convert to reusable technique/pattern |
| Project-specific rules in skill | Move to CLAUDE.md |
| Generic labels (step1, helper2) | Use semantic names |
| Flowchart for linear instructions | Use numbered list instead |
| No entry in README | Add to skills table immediately |
Create when:
Don't create for:
No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Route a codebase question to the right tool — structural graph, semantic search, or risk analysis. Use when you need to find or understand code without knowing exact file names.
The English summary is being prepared. Showing the original description.
Auto-configure CLAUDE.md and claude/ knowledge docs for a new project. Use when setting up Brain Bootstrap in a new repository. Discovers the codebase, fills in templates, and writes project-specific configuration.
The English summary is being prepared. Showing the original description.
Use before any new feature, component, or behavioral change — when you need to explore requirements and design before writing code
The English summary is being prepared. Showing the original description.
Activate safety guards for the session. Use /careful before critical operations — blocks rm -rf, DROP TABLE, git push --force, kubectl delete namespace, docker system prune via PreToolUse hook.
The English summary is being prepared. Showing the original description.
Generate a user-facing changelog from git commits — categorize, filter noise, translate to user language. Runs in isolated fork context.
The English summary is being prepared. Showing the original description.
Save session state before context gets full or before ending. Writes current task state, branch, and loaded docs to claude/tasks/todo.md so the next session can resume cleanly.
The English summary is being prepared. Showing the original description.