Skill Creator

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 (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 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: koolamusic
• Source: koolamusic/claudefiles
• License: MIT
• Homepage: https://andrewmiracle.com/claudefiles

Install and usage instructions live in the source repository linked above.