Skill Creator

Create effective skills that extend Claude's capabilities with specialized knowledge, workflows, and tools.

What Skills Provide

1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Company-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, and assets for complex tasks

Core Principles

Concise is Key

The context window is shared with system prompt, conversation history, and user requests.

Default assumption: Claude is already very smart. Only add context Claude doesn't already have. Challenge each piece: "Does Claude really need this?" and "Does this justify its token cost?"

Prefer concise examples over verbose explanations.

Set Appropriate Degrees of Freedom

Match specificity to task fragility:

Freedom Level	When to Use	Format
High	Multiple approaches valid, context-dependent	Text instructions
Medium	Preferred pattern exists, some variation OK	Pseudocode/scripts with params
Low	Fragile operations, consistency critical	Specific scripts, few params

Skill Anatomy

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/      - Executable code
    ├── references/   - Documentation loaded as needed
    └── assets/       - Files used in output (templates, etc.)

SKILL.md Structure

• Frontmatter (YAML): name and description fields - these determine when the skill triggers
• Body (Markdown): Instructions loaded AFTER the skill triggers

Bundled Resources

Type	Purpose	When to Include
scripts/	Deterministic, reusable code	Same code rewritten repeatedly
references/	Documentation loaded as needed	Large docs Claude should reference while working
assets/	Files used in output (not loaded into context)	Templates, images, boilerplate

Do NOT include: README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, or other auxiliary docs.

Progressive Disclosure

Three-level loading system:

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - When skill triggers (<5k words, ideally <500 lines)
3. Bundled resources - As needed by Claude

Pattern: Domain-specific organization

bigquery-skill/
├── SKILL.md (overview + navigation)
└── references/
    ├── finance.md
    ├── sales.md
    └── product.md

Claude loads only the relevant reference file.

Skill Creation Process

Step 1: Understand with Examples

Ask clarifying questions:

• "What functionality should this skill support?"
• "Can you give examples of how it would be used?"
• "What would trigger this skill?"

Step 2: Plan Reusable Contents

For each example, identify:

1. What scripts would help (repeated code)
2. What references would help (schemas, docs)
3. What assets would help (templates, boilerplate)

Step 3: Create the Skill

Create the skill directory in .claude/skills/:

mkdir -p .claude/skills/my-skill-name

Naming Convention:

• Standard skills: plan, implement, verify, standards-* (overwritten on install)
• Custom skills: Any other name (preserved during updates)

For project-specific skills, use a unique name that doesn't match standard patterns.

Step 4: Write SKILL.md

Frontmatter

---
name: skill-name
description: What the skill does AND when to use it. Include all trigger contexts here since the body is only loaded after triggering.
---

Description guidelines:

• Include both what it does AND specific triggers/contexts
• All "when to use" info goes here, not in the body
• Example: "PDF processing for rotation, merging, text extraction. Use when working with .pdf files for editing, combining, or extracting content."

Body

Write concise instructions:

• Use imperative/infinitive form
• Keep under 500 lines
• Reference bundled resources with clear "when to read" guidance
• Move detailed docs to references/ files

Step 5: Test and Iterate

1. Use the skill on real tasks
2. Notice struggles or inefficiencies
3. Update SKILL.md or bundled resources
4. Test again

Writing Guidelines

Good Patterns

## Quick Start

Extract text with pdfplumber:
[concise code example]

## Advanced Features

- **Form filling**: See [references/forms.md](references/forms.md)
- **API reference**: See [references/api.md](references/api.md)

Avoid

• Deeply nested references (keep one level deep)
• Duplicating info between SKILL.md and references
• Verbose explanations when examples suffice
• "When to Use" sections in the body (put in description)

Checklist

Before finalizing:

• Frontmatter has name and comprehensive description
• Description includes trigger contexts
• Body is under 500 lines
• References exist for large documentation
• Scripts are tested and working
• No unnecessary auxiliary files (README, CHANGELOG, etc.)
• Skill name follows convention (custom = unique name, standard = standards-*)