Skill Creator for Claude Code

Guide for creating skills in Claude Code's skill directory.

About Skills

Skills are modular packages providing specialized knowledge, workflows, and tools. Transform Claude from general to specialized agent with procedural knowledge.

What Skills Provide

1. Specialized workflows - Multi-step procedures
2. Tool integrations - File formats, APIs
3. Domain expertise - Schemas, business logic
4. Bundled resources - Scripts, references, assets

Core Principles

Concise is Key

Context window is public good. Only add what Claude doesn't know. Challenge each piece: "Does Claude need this?"

Default: Claude is smart. Add only non-obvious info.

Set Appropriate Degrees of Freedom

High freedom (text): Multiple valid approaches, context-dependent Medium freedom (pseudocode/params): Preferred pattern, some variation Low freedom (scripts): Fragile operations, consistency critical

Critical Structure Requirements

MANDATORY: Every skill MUST be structured as a directory, NOT a single file.

Required structure:

• Directory named skill-name/ (lowercase letters, numbers, hyphens only)
• Containing SKILL.md file (UPPERCASE, exactly this filename)

Correct examples:

• ✅ git-commit/SKILL.md
• ✅ pdf-processing/SKILL.md
• ✅ data-analyzer/SKILL.md

Wrong examples:

• ❌ git-commit.md (single file, not directory)
• ❌ git-commit/skill.md (lowercase)
• ❌ git-commit/README.md (wrong filename)

Anatomy

skill-name/
├── SKILL.md (required - UPPERCASE)
│   ├── YAML frontmatter (name, description)
│   └── Markdown instructions
├── reference.md (optional - root-level docs)
├── examples.md (optional - root-level docs)
├── scripts/ (optional)
│   └── helper.py - Executable code
└── templates/ (optional)
    └── template.txt - Files used in output

SKILL.md (required)

• Frontmatter (YAML): name and description - triggers when Claude uses skill
• Body (Markdown): Instructions for using skill

Bundled Resources (optional)

Scripts (scripts/) - Executable code for deterministic/repeated tasks

• Token efficient, deterministic
• May execute without loading to context
• Examples: scripts/rotate_pdf.py, scripts/fill_form.py

Reference docs (root-level .md files) - Docs loaded as needed

• Database schemas, API docs, detailed workflows
• Keeps SKILL.md lean
• Load only when Claude determines needed
• Examples: reference.md, api_docs.md, workflows.md
• Note: These are individual files at root, NOT in a references/ subdirectory

Templates (templates/) - Files used in output, not loaded to context

• Templates, boilerplate code, starter files
• Used in final output by copying/modifying
• Examples: templates/starter-project/, templates/document.docx

What NOT to Include

No auxiliary docs:

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md

Only info needed for AI agent to work.

Progressive Disclosure

Three-level loading:

1. Metadata - Always in context (~100 words)
2. SKILL.md body - When triggered (<5k words)
3. Bundled resources - As needed (unlimited)

Keep SKILL.md <500 lines. Split when approaching limit.

Pattern: High-level guide with references

## Quick start

[core example]

## Advanced

- **Forms**: See ./forms.md
- **API**: See ./api-reference.md

Skill Creation Process

1. Understand skill with concrete examples
2. Plan reusable contents (scripts, references, assets)
3. Initialize skill (run init_skill.py)
4. Edit skill (implement resources, write SKILL.md)
5. Iterate based on usage

Step 1: Understanding with Concrete Examples

Skip if usage patterns clear.

Ask for concrete examples:

• "What functionality should skill support?"
• "Examples of usage?"
• "What triggers this skill?"

Avoid overwhelming - ask most important questions first.

Conclude when functionality clear.

Step 2: Planning Reusable Contents

Analyze each example:

1. How to execute from scratch?
2. What scripts/references/assets help?

Example: pdf-editor

• Query: "Rotate this PDF"
• Analysis: Same code each time → scripts/rotate_pdf.py

Example: frontend-webapp-builder

• Query: "Build todo app"
• Analysis: Same boilerplate → templates/hello-world/ starter project

Example: big-query

• Query: "How many users logged in today?"
• Analysis: Re-discovering schemas → schema.md (root-level reference)

Output: List of reusable resources needed.

Step 3: Initialize Skill

Skip if skill exists.

Run init script from repo root:

python3 ./skills/skill-creator/scripts/init_skill.py <skill-name> --path <output-directory>

Example:

python3 ./skills/skill-creator/scripts/init_skill.py brainwriting --path ./.claude/skills

Creates:

• Skill directory
• SKILL.md template with frontmatter
• Example resource directories
• Example files (customize/delete)

Step 4: Edit Skill

Learn Patterns

Consult:

• Multi-step processes: workflows.md
• Output formats: output-patterns.md

Start with Resources

Implement resources first: scripts, reference docs, templates. May need user input (brand assets, docs).

Test scripts - run to verify no bugs. Delete unused example files.

Update SKILL.md

Writing: Use imperative/infinitive form.

Frontmatter:

• name: Skill name
• description: What it does + when to use. Specific, comprehensive, direct. Claude uses this to choose from 100+ skills.

Body: Instructions for using skill and resources.

Script will:

1. Validate skill (YAML, structure, naming, descriptions)

Default priority:

1. ./.claude/skills/ (project-local)
2. ~/.claude/skills/ (user-global)
3. Custom path if specified

Validation checks:

• YAML frontmatter format, required fields
• Naming conventions, directory structure
• Description quality
• File organization, resource references

If validation fails, fix errors and re-run.

Step 6: Iterate

Test skill on real tasks. Notice struggles → identify improvements → implement → test.