5.1 KiB
name, description, allowed-tools, version
| name | description | allowed-tools | version |
|---|---|---|---|
| skill-identifier | Brief description of what this skill does and when to use it. IMPORTANT: Include activation triggers in the description itself since Claude Code only uses the description field for discovery. Examples: "Use when...", "Activates for...", "Helps with..." Good: "Generate React components with TypeScript. Use when creating new UI components." Bad: "Helps with components" (too vague) | 1.0.0 |
Skill Name
Brief overview of what this skill does (1-2 sentences maximum).
When to Use
- User action or request that triggers this skill
- Specific scenario where this skill is helpful
- Problem this skill solves
Prerequisites
- Required tools/setup (if any)
- Expected environment or configuration
- Dependencies that must be installed
Core Workflow
1. Step One
Description of first step with details.
# Example command or code
example-command --flag value
2. Step Two
Description of second step with examples.
3. Step Three
Final steps and completion criteria.
Best Practices
- Practice 1: Why and when to apply it
- Practice 2: Common pitfall to avoid
- Practice 3: Optimization or efficiency tip
Example Workflows
Scenario 1: [Common Use Case]
User Request: "Help me do X"
Steps:
- First action
- Second action
- Expected outcome
Example:
// Example code demonstrating the workflow
function example() {
// ...
}
Scenario 2: [Advanced Use Case]
User Request: "I need to handle Y edge case"
Steps:
- Handle edge case
- Validate result
- Confirm success
Troubleshooting
Issue 1: Common Problem
Symptom: What the user sees
Solution:
- Step 1 to fix
- Step 2 to verify
- Alternative approach if needed
Issue 2: Another Problem
Symptom: What the user sees
Solution:
- How to resolve
- How to prevent in future
References
Template Notes (Remove before publishing)
What Claude Code Actually Uses
Claude Code ONLY recognizes these fields:
name- Skill identifier (required)description- What it does AND when to activate (required)allowed-tools- Tool restrictions (optional)
Extended metadata (ignored by Claude Code, but useful for humans):
version- Track changes since skills are files, not versioned packages
Note: Author info is in the plugin's plugin.json, not individual skill files.
All activation hints, keywords, and patterns should go directly in the description field since that's the only field Claude Code uses for skill discovery.
File Organization
Skills can have supporting files loaded progressively:
skill-name/
├── SKILL.md (this file, required)
├── reference.md (optional, advanced topics)
├── examples.md (optional, detailed examples)
├── scripts/ (optional, helper scripts)
└── templates/ (optional, code templates)
Activation Best Practices
Claude Code only uses the description field for discovery!
Put ALL activation hints directly in the description:
description: |
Generate React components with TypeScript and Tailwind CSS.
Use when: creating new components, scaffolding UI elements, building design system.
Activates for: "create component", "new component", "generate component"
Good description examples:
"Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with .xlsx files or data analysis requests."
"Refactor TypeScript imports, organize import statements, remove unused imports. Use when cleaning up imports or seeing import-related errors."
Bad description (too vague):
"Helps with data" ❌ - No activation triggers, no use cases
Model Selection
Claude Code automatically picks the appropriate model. The model field in YAML is ignored.
Tool Restrictions
Use allowed-tools to create read-only or limited-permission skills:
allowed-tools: [Read, Grep, Glob] # Read-only, no file modifications
Available tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch, Task, etc.