skill-creator

name	skill-creator
description	Guide for creating effective skills. Use when creating a new skill, updating an existing skill, or verifying skills work before deployment. Covers skill structure, creation process, testing methodology, and packaging.

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:

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 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:

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - When skill triggers (<5k words, under 500 lines)
3. 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):

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

GREEN — Write minimal skill:

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

REFACTOR — Close loopholes:

1. Identify new rationalizations from testing
2. Add explicit counters for each
3. Build rationalization table, red flags list
4. 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:

1. Rich description — "Use when..." with concrete triggers and symptoms
2. Keyword coverage — Error messages, symptoms, synonyms, tool names
3. Descriptive naming — Verb-first, active voice (condition-based-waiting not async-test-helpers)
4. 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.