meta
Guide for writing and improving Claude Code skills. Use when creating new skills, debugging why skills aren't activating, or improving skill descriptions and structure.
When & Why to Use This Skill
This Claude skill serves as a comprehensive meta-guide and framework for developers to design, implement, and optimize Claude Code skills. It provides standardized structures, YAML frontmatter requirements, and systematic debugging workflows to ensure AI agents activate correctly and perform tasks with high reliability. By focusing on trigger term optimization and structural integrity, it helps users package complex agentic workflows into discoverable and efficient capabilities.
Use Cases
- Skill Creation: Providing the standardized directory structure and SKILL.md templates required to build new capabilities for Claude Code.
- Activation Troubleshooting: Using the systematic checklist to diagnose why skills aren't triggering, including fixing YAML syntax errors and missing frontmatter markers.
- Intent Optimization: Refining skill descriptions with specific trigger terms and keywords to improve Claude's ability to recognize when to invoke a particular tool.
- Security Configuration: Implementing 'allowed-tools' restrictions within the skill metadata to ensure the agent operates within safe and defined permission boundaries.
- Workflow Standardization: Transitioning simple slash commands into complex, multi-file skill workflows for more robust automation tasks.
| name | meta |
|---|---|
| description | Guide for writing and improving Claude Code skills. Use when creating new skills, debugging why skills aren't activating, or improving skill descriptions and structure. |
Writing effective Claude Code skills
Required structure
skill-name/
├── SKILL.md (required)
├── reference.md (optional)
├── scripts/ (optional)
└── templates/ (optional)
SKILL.md frontmatter
---
name: lowercase-with-hyphens
description: Explain WHAT it does AND WHEN to use it. Include trigger terms users would say.
allowed-tools: [Read, Write, Bash] # optional: restrict permissions
---
Critical best practices
- Keep skills focused - one capability per skill
- Write specific descriptions - include actual terms users would mention
- Test activation - verify Claude invokes it when expected
- Use allowed-tools - restrict permissions for security
Description examples
❌ Bad: "Helps with data" ✅ Good: "Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with .xlsx files."
❌ Bad: "Manages configuration" ✅ Good: "Read and update YAML/JSON config files. Use when modifying settings, environment variables, or application configuration."
Debugging checklist
If Claude doesn't use your skill:
- Description lacks trigger terms users would say
- YAML syntax errors (check
---markers, indentation) - Description not specific enough about WHEN to use it
- Wrong file path or permissions
Finding and fixing frontmatter issues
Check if frontmatter exists:
# View first 10 lines of SKILL.md
head -10 ~/.claude/skills/*/SKILL.md
Common frontmatter problems:
- Missing frontmatter block - File starts with
#instead of---- Fix: Add YAML block at top of file
- Missing closing
---- Only one---marker- Fix: Ensure both opening and closing markers exist
- Missing required fields - No
name:ordescription:- Fix: Add both required fields
- Wrong indentation - YAML is indentation-sensitive
- Fix: Use 2 spaces, no tabs
- Missing description trigger terms - Generic description
- Fix: Add specific keywords users would say
Validation script:
# Check all skills for frontmatter
for skill in ~/.claude/skills/*/SKILL.md; do
echo "=== $skill ==="
if head -1 "$skill" | grep -q "^---$"; then
echo "✓ Has frontmatter"
else
echo "✗ Missing frontmatter"
fi
done
Systematic skill debugging workflow
When debugging skills that aren't working:
List all skills - Verify skill exists
ls -la ~/.claude/skills/Check frontmatter - Validate YAML structure
head -10 ~/.claude/skills/skill-name/SKILL.mdVerify required fields - Ensure name and description exist
name:must match directory namedescription:must include trigger terms
Test description specificity - Does it explain WHEN to use?
- Include file types, actions, or domain terms
- Avoid generic phrases like "helps with" or "manages"
Check allowed-tools - If restricted, verify needed tools included
allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]Review content - Ensure instructions are clear and actionable
Skills vs slash commands
Use skills for:
- Complex workflows with multiple files
- Automatic contextual invocation
- Comprehensive capabilities
Use slash commands for:
- Simple single prompts
- Manual explicit control
- Quick frequently-used operations