example-skill
Use when working with examples, tutorials, or skill documentation. Invoke when the user asks about skill configuration, manifest structure, or creating new skills.
When & Why to Use This Skill
This Claude skill provides comprehensive guidance for creating, configuring, and optimizing agent skills within the Claude Code ecosystem. It streamlines the development of SKILL.md files, ensures correct YAML frontmatter implementation, and offers best practices for skill discovery to enhance agent performance and context management.
Use Cases
- Generating compliant SKILL.md files: Assisting developers in structuring skill manifests with required fields like name, description, and allowed-tools.
- Optimizing skill discovery: Providing expert advice on writing high-quality descriptions that ensure the agent invokes the correct skill at the right time.
- Architectural guidance: Helping users distinguish between skills and plugins (MCP servers, CLI tools) to ensure the proper extension method is used for specific tasks.
- Standardizing project conventions: Capturing domain-specific knowledge and coding patterns into a structured format that the agent can readily utilize as system context.
| 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