Create new Skills for Claude Code including YAML frontmatter, descriptions, instructions, and structure...
Build production-quality Skills for Claude Code with proper structure, discoverable descriptions, and best practices.
Description Formula: [What it does] + [When to use it] + [Trigger terms users say]
Name Rules: Lowercase letters, numbers, hyphens only; max 64 characters; no spaces
Description Rules: Max 1024 characters; must be specific with trigger terms
Use AskUserQuestion to understand what they need:
What should the Skill do?
When should it activate?
Scope decision
Structure complexity
Tool restrictions
The description determines discoverability. Use this proven formula:
[Specific operations] + [When to use] + [Trigger terms]
Example walkthrough:
Key elements:
See examples/descriptions.md for more patterns.
Validate and format the name:
Examples:
Single file when:
Multi-file when:
Recommended structure for complex Skills:
skill-name/
├── SKILL.md # Core instructions (loaded first)
├── reference.md # Detailed API/reference (loaded if needed)
├── examples.md # Additional examples (loaded if needed)
├── scripts/ # Utility scripts
│ ├── helper.py
│ └── process.sh
└── templates/ # Template files
└── template.txt
# Personal Skill
mkdir -p ~/.claude/skills/skill-name
# Project Skill
mkdir -p .claude/skills/skill-name
# Multi-file structure
mkdir -p ~/.claude/skills/skill-name/{templates,scripts,examples}
Template structure:
---
name: skill-name
description: [Use the formula from Phase 2]
allowed-tools: Read, Grep, Glob # Optional: only if restricting tools
---
# Skill Name
Brief introduction explaining what this Skill does.
## Quick Start
Provide the most common use case with a concrete example.
## Instructions
Step-by-step guidance for Claude:
1. [First step with specific actions]
2. [Second step with expected behavior]
3. [Continue pattern]
## Examples
Show concrete code examples:
```language
# Example code that demonstrates usage
List any dependencies:
pip install required-package
#### Add supporting files if multi-file
Reference from SKILL.md:
```markdown
For detailed API reference, see [reference.md](reference.md).
Use the helper script:
```bash
python scripts/helper.py input.txt
### Phase 6: Validation
Before finalizing, check:
- [ ] Description follows formula (what + when + triggers)
- [ ] Description under 1024 characters
- [ ] Name is lowercase-with-hyphens, under 64 chars
- [ ] YAML has opening and closing `---`
- [ ] YAML uses spaces not tabs
- [ ] Instructions are clear and actionable
- [ ] Examples are concrete and tested
- [ ] Dependencies are documented
- [ ] Tool restrictions (if any) are appropriate
See [reference/validation-checklist.md](reference/validation-checklist.md) for complete checklist.
### Phase 7: Testing
1. **Restart Claude Code** (required for Skills to load)
2. **Test discovery**:
- Ask using trigger terms from your description
- Verify Skill activates automatically
- Try variations of trigger phrases
3. **Test workflow**:
- Follow instructions as Claude
- Verify all examples work
- Check edge cases
4. **Debug if needed**:
```bash
# Check Skill was loaded
# Ask: "What Skills are available?"
# View Skill file
cat ~/.claude/skills/skill-name/SKILL.md
# Check for YAML syntax errors
claude --debug
Causes:
Solutions:
Causes:
Solutions:
Common mistakes:
--- (line 1)--- (before Markdown content)Fix:
---
name: skill-name
description: Description text here
---
# Markdown starts here
After using a Skill, improve it:
When creating Skills, remember:
Why descriptions matter: Claude uses them for discovery. Vague descriptions = never activated.
Why multi-file structure works: Progressive loading. Claude reads SKILL.md first, supporting files only when needed. Keeps context focused.
Why tool restrictions are powerful: Creates safe, focused Skills. Read-only analysis Skills can't accidentally modify files.
Why trigger terms are crucial: Users don't know your Skill exists. They ask questions naturally. Trigger terms bridge their words to your Skill.
Basic Skill template: templates/basic-skill.md
Advanced multi-file template: templates/advanced-skill.md
Description examples: examples/descriptions.md
After creating a Skill:
Remember: Great Skills have specific descriptions with trigger terms. That's the difference between a Skill that gets used and one that never activates.
