Our review
This skill explains the structure and creation of SKILL.md files for Claude Code skills, including frontmatter metadata and discovery best practices.
Strengths
- Clearly defines the description field for automatic triggering
- Distinguishes skills from plugins, hooks, and slash commands
- Provides examples of good and bad descriptions
- Documents required and optional frontmatter fields
Limitations
- Only covers file format, not skill content
- Specific to Claude Code, not applicable to other platforms
- No template for advanced use cases
Use this skill when creating or editing a SKILL.md file to define a new skill.
Do not use it for implementing advanced functionality like CLI tools, MCP servers, or hooks, which require a plugin.
Security analysis
SafeThe skill only uses safe tools (Read, Glob, Grep) that do not alter the system. It contains no destructive commands, exfiltration attempts, or obfuscated content. It is purely informational documentation.
No concerns found
Examples
I want to create a new skill for my project. Can you explain the SKILL.md format and what fields are required?How do I write a good description for skill discovery in SKILL.md? Give me examples of good and bad descriptions.What is the difference between a skill and a plugin in Claude Code? When should I use each?name: example-skill description: Use when working with examples, tutorials, or skill documentation. Invoke when the user asks about skill configuration, manifest structure, or creating new skills. allowed-tools: Read, Glob, Grep
Example Skill
This is an example skill demonstrating the SKILL.md format.
What Skills Provide
Skills are instructions and context injected into the agent's system prompt. They help the agent understand:
- When to use certain techniques or tools
- Project-specific conventions and patterns
- Domain knowledge and best practices
What Skills Do NOT Provide
Skills are not for:
- CLI tools (use package managers or plugins)
- MCP servers (use plugins with plugin.json)
- Hooks (use plugins)
- Slash commands (use plugins)
For those capabilities, create a full Claude Code plugin with .claude-plugin/plugin.json.
SKILL.md Format
Skills are defined by a single SKILL.md file with YAML frontmatter:
---
name: my-skill
description: When to use this skill...
allowed-tools: Read, Write, Bash
---
# My Skill
Instructions and documentation here...
Required Frontmatter Fields
| Field | Description |
|-------|-------------|
| name | Skill identifier (kebab-case, 1-64 chars) |
| description | Critical - tells Claude when to invoke the skill |
Optional Frontmatter Fields
| Field | Description |
|-------|-------------|
| allowed-tools | Comma-separated or YAML array of allowed tools |
Discovery
The description field is crucial for skill discovery. Claude uses it to decide when to invoke the skill.
Good descriptions:
- "Use when managing git branches, resolving merge conflicts, or reviewing commit history"
- "Use when working with React components, hooks, or state management"
Bad descriptions:
- "Git utilities" (too vague)
- "React helper" (won't trigger reliably)
Example Use Cases
This skill covers:
- Explaining skill structure and format
- Helping users create new skills
- Demonstrating best practices for skill documentation
API Documentation Generator
Documentation
Automatically generates OpenAPI/Swagger API documentation.
Technical Writer
Documentation
Writes clear technical documentation following top style guides.
Pivot Decision Framework
Documentation
Documents a strategic pivot or persevere decision with evidence, analysis, and rationale. Use when evaluating whether to change direction on a product, feature, or strategy based on market feedback.