Skill Creator

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

About Skills

Skills are modular 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: "Does Claude really need this?" Prefer concise examples over verbose explanations.

Set Appropriate Degrees of Freedom

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

Progressive Disclosure

Three-level loading to manage context efficiently:

Metadata (name + description) - Always in context (~100 words)
SKILL.md body - When skill triggers (<5k words, under 500 lines)
Bundled resources - As needed (unlimited, loaded on demand)

Skill Anatomy

skill-name/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Optional: executable code (Python/Bash)
├── references/           # Optional: docs loaded into context as needed
└── assets/               # Optional: files used in output (templates, icons)

SKILL.md Frontmatter

Only name and description are required. The description is the primary trigger — it determines when the skill loads.

---
name: my-skill
description: Use when [specific triggering conditions and symptoms]
---

Description rules:

Start with "Use when..." — focus on triggering conditions
Include specific symptoms, situations, and contexts
Write in third person
NEVER summarize the skill's workflow in the description (Claude may follow the summary instead of reading the full skill)

Bundled Resources

scripts/: Deterministic, reusable code. Token-efficient. Test by running them.
references/: Documentation Claude reads as needed. Keep SKILL.md lean by moving detailed info here. For large files (>10k words), include grep patterns in SKILL.md.
assets/: Files for output (templates, images, fonts). Not loaded into context.

Do NOT include: README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, or auxiliary docs about the creation process.

Creation Process

Step 1: Understand with Concrete Examples

Ask the user:

What should the skill support?
Example usage scenarios?
What triggers should activate this skill?

Step 2: Plan Reusable Contents

For each example, identify what scripts, references, and assets would help when executing these workflows repeatedly.

Step 3: Initialize the Skill

Create the skill directory with a SKILL.md containing frontmatter (name + description) and the appropriate resource subdirectories (scripts/, references/, assets/) as needed.

Step 4: Edit the Skill

Consult these guides based on your needs:

Multi-step processes: See references/workflows.md
Output formats/quality standards: See references/output-patterns.md
Official authoring guidance: See references/anthropic-best-practices.md

Start with reusable resources, then write SKILL.md. Use imperative/infinitive form.

Step 5: Validate & Package

Verify the skill has valid frontmatter (name + description, kebab-case name, under 1024 chars), then package with zip -r skill-name.skill skill-name/ if distributing.

Step 6: Iterate with TDD

Skill creation IS Test-Driven Development applied to process documentation.

Follow RED-GREEN-REFACTOR:

RED — Baseline test (before writing/editing the skill):

Create pressure scenarios (3+ combined pressures for discipline skills)
Run scenarios with a subagent WITHOUT the skill
Document exact behavior: choices, rationalizations (verbatim), failures

GREEN — Write minimal skill:

Address the specific rationalizations observed in RED
Don't add content for hypothetical cases
Run same scenarios WITH skill — agent should now comply

REFACTOR — Close loopholes:

Identify new rationalizations from testing
Add explicit counters for each
Build rationalization table, red flags list
Re-test until bulletproof

The Iron Law: No skill without a failing test first. This applies to new skills AND edits.

For the complete testing methodology (pressure scenarios, pressure types, plugging holes, meta-testing), see references/testing-skills-with-subagents.md.

For psychology of persuasion techniques in discipline-enforcing skills, see references/persuasion-principles.md.

Claude Search Optimization (CSO)

Future Claude needs to FIND your skill:

Rich description — "Use when..." with concrete triggers and symptoms
Keyword coverage — Error messages, symptoms, synonyms, tool names
Descriptive naming — Verb-first, active voice (condition-based-waiting not async-test-helpers)
Token efficiency — Frequently-loaded skills <200 words; move details to references

Skill Types & Testing

Type	Examples	Test With
Discipline (rules)	TDD, verification	Pressure scenarios, rationalization resistance
Technique (how-to)	condition-based-waiting	Application + edge cases
Pattern (mental model)	flatten-with-flags	Recognition + counter-examples
Reference (docs/APIs)	API guides	Retrieval + application accuracy

Progressive Disclosure Patterns

Pattern 1: High-level guide linking to references for advanced features Pattern 2: Domain-specific organization (only load relevant domain file) Pattern 3: Conditional details (basic inline, advanced linked)

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

Common Mistakes

Descriptions that summarize workflow (Claude takes shortcut, skips body)
Narrative storytelling instead of reusable patterns
Multi-language dilution (one excellent example beats many mediocre ones)
Code in flowcharts (can't copy-paste)
Deeply nested references (keep one level deep)
Skipping testing ("obviously clear" to you != clear to agents)

Flowcharts

Use ONLY for non-obvious decisions, process loops, or A-vs-B choices. Never for reference material, code examples, or linear instructions.

skill-creator