Skill Creator

Guide for creating effective skills that extend Claude's capabilities.

About Skills

Skills are modular, self-contained packages that provide:

• Specialized workflows - Multi-step procedures for specific domains

• Tool integrations - Instructions for working with specific file formats or APIs

• Domain expertise - Company-specific knowledge, schemas, business logic

• Bundled resources - Scripts, references, and assets for complex tasks

Core Principles

Concise is Key

The context window is a public good. Only add context Claude doesn't already have.

• Challenge each piece of information: "Does Claude really need this?"

• Prefer concise examples over verbose explanations

• Default assumption: Claude is already very smart

Set Appropriate Degrees of Freedom

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

Anatomy of a Skill

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 (Required)

Frontmatter (YAML):

• name : Skill identifier (lowercase, hyphenated)

• description : What it does AND when to trigger it

Body (Markdown):

• Instructions and guidance

• Only loaded AFTER the skill triggers

Bundled Resources (Optional)

scripts/ - Executable code for deterministic tasks

• When: Same code rewritten repeatedly, or reliability needed

• Benefits: Token efficient, deterministic

references/ - Documentation loaded as needed

• When: Detailed info Claude should reference while working

• Best practice: Keep SKILL.md lean, load refs only when needed

assets/ - Files used in output

• When: Templates, images, boilerplate needed in final output

• Examples: logo.png, template.docx, starter code

What NOT to Include

• README.md

• INSTALLATION_GUIDE.md

• CHANGELOG.md

• User-facing documentation

• Setup/testing procedures

Skill Creation Process

1. Understand with Concrete Examples

• What functionality should the skill support?

• What would users say to trigger it?

• Get example use cases

2. Plan Reusable Contents

For each example:

• Consider how to execute from scratch

• Identify helpful scripts, references, assets

3. Create the Skill Structure

mkdir skill-name touch skill-name/SKILL.md

4. Write SKILL.md

Frontmatter example:

name: my-skill description: Does X when Y. Triggers include A, B, C.

Body: Include only essential procedural instructions.

5. Add Resources (if needed)

• Create scripts/, references/, assets/ as needed

• Test scripts to ensure they work

• Delete any unused example files

6. Iterate

• Use the skill on real tasks

• Notice struggles or inefficiencies

• Update SKILL.md or resources

• Test again

Progressive Disclosure Patterns

Pattern 1: High-level guide with references

PDF Processing

Quick start

[Basic example]

Advanced features

• Form filling: See FORMS.md
• API reference: See REFERENCE.md

Pattern 2: Domain-specific organization

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

Pattern 3: Framework variants

cloud-deploy/ ├── SKILL.md (workflow + selection) └── references/ ├── aws.md ├── gcp.md └── azure.md

Best Practices

• Keep SKILL.md under 500 lines

• Split content into reference files when approaching limit

• Keep references one level deep from SKILL.md

• Include table of contents for files >100 lines

• Use imperative/infinitive form in writing