Skill Creator
Create and manage Claude Code skills with proper structure and conventions.
Skill Anatomy
Skills live in .claude/skills/<skill-name>/ and have two forms:
Simple Skills (Documentation Only)
my-skill/ └── SKILL.md
Complex Skills (With Scripts)
my-automation/ ├── SKILL.md ├── run.py ├── list.py └── cleanup.py
SKILL.md Format
All skills require a SKILL.md with YAML frontmatter:
--- name: skill-name description: Brief description. Use when [trigger conditions]... --- # Skill Title [Instructions and documentation]
Required Frontmatter Fields
name (required)
- •Maximum 64 characters
- •Lowercase letters, numbers, and hyphens only
- •Cannot contain XML tags
- •Cannot contain reserved words: "anthropic", "claude"
description (required)
- •Maximum 1024 characters
- •Must be non-empty
- •Cannot contain XML tags
- •Should describe what the skill does AND when to use it
Optional Frontmatter Fields
--- name: my-skill description: Does X. Use when Y... license: MIT allowed-tools: - Bash - Read metadata: author: your-name version: 1.0.0 ---
Progressive Disclosure
Skills load content in stages to minimize context usage:
| Level | When Loaded | Token Cost | Content |
|---|---|---|---|
| Level 1: Metadata | Always (startup) | ~100 tokens | name and description from frontmatter |
| Level 2: Instructions | When triggered | <5k tokens | SKILL.md body |
| Level 3+: Resources | As needed | Unlimited | Bundled files, scripts (via bash) |
Key principle: Claude loads SKILL.md only when the skill is triggered, and reads additional files only when referenced.
Best Practices (from Anthropic docs)
Naming Conventions
Use gerund form (verb + -ing) for skill names:
- •
processing-pdfs - •
analyzing-spreadsheets - •
managing-databases
Or domain prefixes:
- •
rust-error-handling - •
git-worktree-manager
Writing Descriptions
Always write in third person (injected into system prompt):
- •Good: "Processes Excel files and generates reports"
- •Avoid: "I can help you process Excel files"
- •Avoid: "You can use this to process Excel files"
Be specific and include triggers:
# Good description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. # Bad description: Helps with documents
Content Guidelines
- •Keep SKILL.md body under 500 lines
- •Split large content into separate files
- •Keep file references one level deep from SKILL.md
- •Add table of contents to files >100 lines
- •Use consistent terminology throughout
- •Avoid time-sensitive information
- •Be concise - Claude is already smart
Degrees of Freedom
Match specificity to task fragility:
- •High freedom: Multiple approaches valid, use text instructions
- •Medium freedom: Preferred pattern exists, use pseudocode/templates
- •Low freedom: Operations are fragile, provide exact scripts
Available Scripts
create_skill.py
Creates a simple documentation skill.
python3 create_skill.py --name "my-pattern" --description "Use when implementing X..." python3 create_skill.py --name "rust-caching" --description "Caching patterns for Rust" --category rust
create_complex_skill.py
Creates a skill with script templates.
python3 create_complex_skill.py --name "my-automation" --description "Automate X tasks" --scripts "run,list,cleanup"
list_skills.py
Lists all existing skills.
python3 list_skills.py # Summary view python3 list_skills.py --verbose # Show scripts for complex skills
Workflow Examples
User says: "Create a skill for database migrations"
python3 create_skill.py --name "db-migrations" --description "Database migration patterns. Use when creating or managing database schema changes."
User says: "I need a skill that automates deployment"
python3 create_complex_skill.py --name "deploy-manager" --description "Automate deployment workflows. Use when deploying, rolling back, or checking deployment status." --scripts "deploy,rollback,status"
User says: "What skills do we have?"
python3 list_skills.py
Checklist for Effective Skills
Before sharing a skill, verify:
- • Description is specific and includes trigger conditions
- • Description written in third person
- • SKILL.md body under 500 lines
- • No time-sensitive information
- • Consistent terminology throughout
- • File references one level deep
- • Scripts have clear documentation (for complex skills)