Skill Creator

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:

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)

References

• Agent Skills Overview
• Best Practices Guide
• Skills Specification
• Skills Cookbook