Skill Creator

Guide for creating effective skills for Claude Code.

What Skills Provide

1. •Specialized workflows - Multi-step procedures for specific domains
2. •Tool integrations - Instructions for working with 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 a public good. Challenge each piece of information: "Does Claude really need this?" Prefer concise examples over verbose explanations.

Degrees of Freedom

Match specificity to task fragility:

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

Skill Structure

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown instructions
└── Optional Resources
    ├── scripts/      - Executable code (Python/Bash)
    ├── references/   - Docs loaded on demand
    └── assets/       - Templates, images for output

SKILL.md

• •Frontmatter: name and description are the PRIMARY trigger mechanism
• •Body: Instructions loaded AFTER skill triggers

Supporting Files

scripts/ - For deterministic, repeatable code:

scripts/rotate_pdf.py

references/ - Documentation loaded as needed:

references/api-docs.md
references/schemas.md

assets/ - Files used in output (not loaded into context):

assets/template.docx
assets/logo.png

What NOT to Include

• •README.md
• •CHANGELOG.md
• •INSTALLATION_GUIDE.md
• •Any human-facing auxiliary documentation

Progressive Disclosure

Three-level loading:

1. •Metadata (name + description) - Always in context (~100 words)
2. •SKILL.md body - When skill triggers (<500 lines)
3. •Bundled resources - As needed (unlimited)

Pattern 1: High-level guide with references

# PDF Processing

## Quick start
[core example]

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

Pattern 2: Domain organization

bigquery-skill/
├── SKILL.md
└── references/
    ├── finance.md
    ├── sales.md
    └── product.md

User asks about sales → only load sales.md

Pattern 3: Conditional details

## Basic usage
[simple instructions]

**For advanced config**: See [advanced.md](references/advanced.md)

Creation Process

1. Understand with Examples

Ask:

• •"What functionality should this skill support?"
• •"What would a user say to trigger this?"
• •"What are common use cases?"

2. Plan Reusable Contents

For each example, identify:

• •What scripts would be rewritten repeatedly?
• •What references would Claude need?
• •What assets would be used in output?

3. Create the Skill

mkdir -p .github/skills/my-skill

4. Write SKILL.md

Frontmatter:

---
name: my-skill
description: [What it does AND when to use it. This is the trigger.]
---

Body:

• •Use imperative form ("Create...", "Run...")
• •Keep under 500 lines
• •Reference supporting files with clear "when to read" guidance

5. Validate

/validate-skill .github/skills/my-skill

6. Iterate

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

Frontmatter Options

See .claude/references/skills-guide.md for all options:

Naming Conventions

• •Lowercase letters, digits, hyphens only
• •Under 64 characters
• •Prefer verb-led phrases: create-report, review-pr
• •Directory name must match name field