Use before creating or editing any SKILL.md files, and immediately after making skill changes to verify quality. Invoked when user asks about skill structure, descriptions, or best practices. Provides expert guidance on naming, descriptions for discoverability, progressive context reveal, and validation workflows. Critical for ensuring skills are discoverable and effective - prevents poorly structured skills that Claude won't use properly.
Provides expert guidance for creating high-quality Claude Code skills. Triggers when users ask about skill structure, descriptions, or best practices, and when creating/editing SKILL.md files to validate quality and ensure discoverability.
/plugin marketplace add bbrowning/bbrowning-claude-marketplace/plugin install bbrowning-claude@bbrowning-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
reference/best-practices.mdreference/examples.mdreference/skill-review.mdreference/skill-structure.mdtemplates/skill-template.mdThis skill provides comprehensive guidance for creating high-quality Claude Code skills that are modular, discoverable, and effective.
Skills are modular capabilities that extend Claude's functionality. They are:
SKILL.md filesSkills differ from slash commands (user-invoked) - they're capabilities Claude chooses to use.
Every skill requires a directory containing SKILL.md with YAML frontmatter:
---
name: Your Skill Name
description: Clear, specific one-line description
---
# Instructions and content
For detailed structure information including optional files, see reference/skill-structure.md.
mkdir -p .claude/skills/my-skillSKILL.md with frontmatterFor a complete template, see templates/skill-template.md.
DO:
DON'T:
Match specificity to task requirements:
Example:
# Low freedom (specific)
When processing invoice PDFs:
1. Extract date field using format YYYY-MM-DD
2. Validate amount matches total
3. Output to invoices.json
# High freedom (flexible)
Analyze the document and extract relevant financial information.
Use progressive disclosure for complex skills within the skill directory:
my-skill/
├── SKILL.md # Concise entry point
├── reference/ # Detailed documentation
│ ├── api-docs.md
│ └── examples.md
├── scripts/ # Helper utilities
│ └── validator.py
└── templates/ # Starting templates
└── output.json
IMPORTANT: Skills must be self-contained within their directory:
../../CLAUDE.md or project files)See reference/skill-structure.md for detailed organization patterns.
For comprehensive best practices, see reference/best-practices.md. Key highlights:
# Good
description: Guides creation of React components following project conventions, including TypeScript types, styled-components, and test patterns
# Vague
description: Helps with React stuff
Limit tool access when needed:
---
name: Read-Only Analysis
allowed-tools: [Read, Grep, Glob]
---
See reference/examples.md for complete skill examples including:
IMPORTANT: Whenever you make changes to a skill file (creating, editing, or updating SKILL.md or related files), you MUST immediately review the skill against best practices.
After making any skill changes:
reference/skill-review.md:
For comprehensive review guidelines, see reference/skill-review.md.
This review step is not optional - it ensures every skill change maintains quality and follows best practices.
Whether reviewing your own skills or others', systematic review ensures quality and effectiveness.
Quick checklist for skill review:
For comprehensive review guidelines, see reference/skill-review.md.
Focus on one specific capability with clear instructions.
Provide structured steps with validation between stages.
Use progressive disclosure: essentials in SKILL.md, details in reference files.
Limit tools for safety-critical or read-only operations.
Skill not discovered: Check description specificity and key terms Too verbose: Move details to reference files Unclear when to use: Improve description and add usage examples Inconsistent results: Reduce degrees of freedom, add specific steps
reference/skill-structure.md: Complete structure and organization detailsreference/best-practices.md: Comprehensive best practices guidereference/examples.md: Real-world skill examplesreference/skill-review.md: Comprehensive skill review guidelinestemplates/skill-template.md: Starting template for new skillsCreating a new skill? Ask:
When writing skills, remember: skills extend Claude's knowledge, so focus on what Claude doesn't already know and make it easily discoverable through clear descriptions and names.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.