Skill Creator

Enhanced by ThepExcel — This version includes additional best practices from official Anthropic documentation plus practical insights from real-world skill development.

This skill provides comprehensive guidance for creating effective skills that Claude can discover and use successfully.

About Skills

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge.

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 and repetitive tasks

Core Principles

Concise is Key

The context window is a public good. Skills share the context window with everything else Claude needs: system prompt, conversation history, other Skills' metadata, and the actual user request.

Default assumption: Claude is already very smart. Only add context Claude doesn't already have. Challenge each piece of information:

• "Does Claude really need this explanation?"
• "Can I assume Claude knows this?"
• "Does this paragraph justify its token cost?"

Prefer concise examples over verbose explanations.

Set Appropriate Degrees of Freedom

Match the level of specificity to the task's fragility and variability:

Freedom Level	When to Use	Example
High (text instructions)	Multiple approaches valid, context-dependent	Code review guidelines
Medium (pseudocode/params)	Preferred pattern exists, some variation OK	Report generation template
Low (specific scripts)	Fragile operations, consistency critical	Database migrations

Analogy: A narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).

Test with All Target Models

Skills effectiveness depends on the underlying model. Test with all models you plan to use:

Model	Consideration
Haiku	Does the skill provide enough guidance?
Sonnet	Is the skill clear and efficient?
Opus	Does the skill avoid over-explaining?

What works for Opus might need more detail for Haiku. Aim for instructions that work across models.

Skill Structure

Anatomy of a Skill

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

Naming Conventions

Use action-oriented names that clearly describe what the skill does. Lowercase letters, numbers, and hyphens only.

Multiple patterns are acceptable — ask user preference if unclear:

Pattern	Examples	When to Use
Gerund (verb-ing)	processing-pdfs, analyzing-data	Traditional, widely used
Verb-noun	prompt-ai-image-video, design-business-model	Clear action + object
Noun-verb-ing	power-query-coaching, problem-solving	Domain + activity
Recognized terms	triz, deep-research	Widely known concepts

Good	Avoid
prompt-ai-image-video	pdf (too vague)
processing-pdfs	helper, utils
create-visualization	anthropic-*, claude-*

Writing Effective Descriptions

The description field enables skill discovery. Always write in third person.

Good	Avoid
"Processes Excel files and generates reports"	"I can help you process Excel files"
"Extracts text from PDF documents"	"You can use this to extract PDF text"

Include both what the skill does and when to use it:

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.

SKILL.md Components

YAML Frontmatter (required)

Field	Rules
name	Max 64 chars, lowercase + numbers + hyphens only
description	Max 1024 chars, non-empty, third person

No other fields in frontmatter.

Body (Markdown)

Instructions and guidance for using the skill. Only loaded AFTER the skill triggers.

Important: "When to Use" sections in the body are useless — Claude only sees the description when deciding to trigger.

Bundled Resources

Scripts (scripts/)

Executable code for tasks requiring deterministic reliability.

• When to include: Same code rewritten repeatedly, or deterministic reliability needed
• Benefits: Token efficient, deterministic, can execute without loading into context

References (references/)

Documentation loaded as needed into context.

• When to include: Large documentation Claude should reference while working
• Best practice: If files >10k words, include grep patterns in SKILL.md
• Avoid duplication: Info lives in SKILL.md OR references, not both

Assets (assets/)

Files used in output, not loaded into context.

• Examples: Templates, logos, fonts, boilerplate code

What NOT to Include

Do NOT create extraneous documentation:

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

Skills are for AI agents, not humans. No auxiliary context about creation process.

Progressive Disclosure

Skills use a three-level loading system:

Level	When Loaded	Size Limit
Metadata (name + description)	Always	~100 words
SKILL.md body	When triggered	<500 lines
Bundled resources	As needed	Unlimited

Progressive Disclosure Patterns

See references/progressive-disclosure.md for detailed patterns:

• Pattern 1: High-level guide with references
• Pattern 2: Domain-specific organization
• Pattern 3: Conditional details

Key rules:

• Keep references one level deep from SKILL.md
• For files >100 lines, include table of contents at top

Skill Creation Process

Overview

1. Understand — Gather concrete usage examples
2. Plan — Identify reusable resources
3. Initialize — Run init_skill.py
4. Edit — Implement resources and SKILL.md
5. Package — Run package_skill.py
6. Iterate — Refine based on real usage

Step 1: Understanding with Concrete Examples

Skip only when usage patterns are already clearly understood.

Ask clarifying questions:

• "What functionality should this skill support?"
• "Can you give examples of how this would be used?"
• "What would a user say that should trigger this skill?"

Related skill: For extracting expertise from domain experts, consider using /extract-expertise — it provides structured conversations to capture mental models, workflows, and best practices that can inform skill development.

Step 2: Planning Reusable Contents

Analyze each example by:

1. How would you execute this from scratch?
2. What scripts/references/assets would help when doing this repeatedly?

Task Type	Analysis	Resource
PDF rotation	Same code each time	scripts/rotate_pdf.py
Frontend webapp	Same boilerplate	assets/hello-world/
BigQuery queries	Rediscovering schemas	references/schema.md

Step 3: Initializing the Skill

Always run init_skill.py for new skills:

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

The script creates:

• Skill directory with proper structure
• SKILL.md template with frontmatter
• Example scripts/, references/, assets/ directories

Step 4: Editing the Skill

Remember: you're creating this for another Claude instance to use. Include non-obvious procedural knowledge.

Consult design patterns:

• Multi-step processes: See references/workflows.md
• Output formats: See references/output-patterns.md
• Anti-patterns: See references/anti-patterns.md
• Evaluation: See references/evaluation.md

Implementation order:

1. Start with reusable resources (scripts, references, assets)
2. Test scripts by actually running them
3. Delete unused example files
4. Update SKILL.md

Step 5: Packaging the Skill

scripts/package_skill.py <path/to/skill-folder>

The script validates then packages:

• YAML frontmatter format
• Naming conventions
• Description quality
• File organization

Step 6: Iteration

Iteration workflow:

1. Use the skill on real tasks
2. Observe struggles or inefficiencies
3. Identify improvements
4. Implement and test again

See references/evaluation.md for the Claude A/B iteration pattern.

Content Guidelines

Avoid Time-Sensitive Information

Don't include info that becomes outdated:

# Bad
If you're doing this before August 2025, use the old API.

# Good — use "old patterns" section
## Current method
Use the v2 API endpoint.

## Old patterns
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
The v1 API used: api.example.com/v1/messages
</details>

Use Consistent Terminology

Choose one term and use it throughout:

Good (consistent)	Bad (inconsistent)
Always "API endpoint"	Mix "endpoint", "URL", "route", "path"
Always "field"	Mix "field", "box", "element", "control"
Always "extract"	Mix "extract", "pull", "get", "retrieve"

Quality Checklist

Before sharing a skill:

Core Quality

• Description is specific with key terms
• Description includes what + when (third person)
• SKILL.md body under 500 lines
• No time-sensitive information
• Consistent terminology throughout
• Examples are concrete, not abstract
• File references one level deep
• Workflows have clear steps

Code and Scripts

• Scripts handle errors (don't punt to Claude)
• No magic constants (all values justified)
• Required packages listed and verified
• No Windows-style paths (use forward slashes)
• Validation steps for critical operations

Testing

• At least three evaluations created
• Tested with target models (Haiku/Sonnet/Opus)
• Tested with real usage scenarios

Related Skills

When	Suggest
Extract expertise from domain expert	/extract-expertise — structured conversations to capture mental models
Research domain knowledge	/deep-research — gather facts before building skill

These skills are optional but highly valuable for skill development.

---

References:

• workflows.md — Sequential, conditional, feedback loops
• output-patterns.md — Templates, examples, terminology
• anti-patterns.md — Common mistakes to avoid
• evaluation.md — Evaluation-driven development, Claude A/B pattern