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)

skill-creator