Creating Claude Skills

Overview

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

Core principle: Skills are composable, portable, efficient, and powerful. They work across all Claude platforms (apps, Code, API) and load only when relevant.

About This Skill

This skill synthesizes two complementary approaches:

1. Anthropic's Official Process - The standard 6-step workflow for creating general-purpose skills
2. Superpowers TDD Methodology - Test-driven approach for workflow/discipline skills

Both approaches produce high-quality skills, but serve different purposes. This skill teaches when and how to use each.

When to Use This Skill

Use this skill when:

• Creating a new skill from scratch
• Updating an existing skill
• Converting workflows into reusable skills
• Packaging domain expertise for Claude
• Building tool integrations or file format handlers

Prerequisites:

• Understanding of the task/workflow you want to teach Claude
• Access to relevant documentation, APIs, or resources
• Clear examples of how the skill should be used

Two Approaches: When to Use Which

Use Anthropic's Approach When

Best for:

• General-purpose skills (document creation, API integrations, creative tools)
• Skills with bundled resources (scripts, references, assets)
• Cross-platform skills (work in Claude apps, Code, and API)
• Skills requiring executable scripts
• First-time skill creators

Examples from Anthropic:

• pdf-editor - Document manipulation with Python scripts
• mcp-builder - MCP server creation with reference docs
• artifacts-builder - Frontend development with asset templates
• brand-guidelines - Company branding with asset files

Process: 6 steps (Understand → Plan → Initialize → Edit → Package → Iterate)

Use Superpowers TDD Approach When

Best for:

• Workflow enforcement skills (TDD, systematic debugging, verification)
• Discipline skills that resist rationalization
• Claude Code-specific workflows
• Skills that teach processes, not tools
• Skills requiring behavioral compliance testing

Examples from Superpowers:

• test-driven-development - Enforces RED-GREEN-REFACTOR
• systematic-debugging - 4-phase debugging framework
• verification-before-completion - Evidence before assertions
• brainstorming - Socratic design refinement

Process: RED-GREEN-REFACTOR cycle adapted for documentation

Anthropic's 6-Step Process

This is the official, recommended approach for most skills. Follow these steps in order.

Step 1: Understanding the Skill with Concrete Examples

Skip this step only when the skill's usage patterns are already clearly understood.

To create an effective skill, clearly understand concrete examples of how the skill will be used. Ask questions like:

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

Output: Clear sense of the functionality the skill should support

Step 2: Planning the Reusable Skill Contents

Analyze each example by:

1. Considering how to execute it from scratch
2. Identifying what scripts, references, and assets would be helpful

Decision guide:

Scripts (scripts/) - Use when:

• Same code is being rewritten repeatedly
• Deterministic reliability is needed
• Example: scripts/rotate_pdf.py for PDF rotation

References (references/) - Use when:

• Claude should reference documentation while working
• Examples: API docs, schemas, policies, workflow guides
• Example: references/schema.md for database structure

Assets (assets/) - Use when:

• Skill needs files used in final output
• Examples: Templates, images, icons, boilerplate code
• Example: assets/template.pptx for PowerPoint templates

Output: List of reusable resources to include in skill

Step 3: Initializing the Skill

For official Anthropic workflow (if you have access to init_skill.py):

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

For Claude Code / manual creation:

mkdir -p ~/.claude/skills/<skill-name>/{scripts,references,assets}
touch ~/.claude/skills/<skill-name>/SKILL.md

Create basic SKILL.md:

---
name: my-skill-name
description: Replace with description of what the skill does and when to use it
---

# Skill Name

[Instructions will go here]

Skip this step if skill already exists and you're iterating.

Step 4: Edit the Skill

Remember: You're creating this for another instance of Claude to use. Focus on information that would be beneficial and non-obvious.

Start with Bundled Resources

Implement the scripts/, references/, and assets/ files identified in Step 2.

Important: Delete any example files not needed. Don't keep placeholder directories.

Update SKILL.md

Writing style: Use imperative/infinitive form (verb-first instructions), not second person.

• ✅ Good: "To accomplish X, do Y"
• ✅ Good: "Load the schema from references/schema.md"
• ❌ Bad: "You should do X"
• ❌ Bad: "If you need to do X"

Answer these questions:

1. What is the purpose of the skill, in a few sentences?
2. When should the skill be used? (Be specific about triggers)
3. How should Claude use the skill? (Reference all bundled resources)

Structure:

---
name: skill-name
description: [Third-person description with WHAT and WHEN]
---

# Skill Name

## Overview
[What is this skill? Core principle in 1-2 sentences]

## When to Use
- Use when [specific trigger 1]
- Use when [specific trigger 2]
- Don't use when [anti-pattern]

## Process / Workflow
[Step-by-step instructions]

## Resources
- **Scripts**: `scripts/example.py` - [description]
- **References**: Load `references/docs.md` for [purpose]
- **Assets**: Use `assets/template.html` for [purpose]

## Examples
[Concrete usage examples]

YAML Frontmatter Best Practices:

---
name: my-skill-name  # lowercase, hyphens only
description: This skill should be used when [specific triggers and conditions] - [what it does and how it helps, in third person]
license: Apache 2.0  # optional
allowed-tools:  # optional, Claude Code only
  - Read(//path/**)
  - Bash(npm install:*)
---

Description guidelines:

• Start with "This skill should be used when..." (third person)
• Be specific about triggering conditions
• Include both WHAT it does AND WHEN to use it
• Keep under 500 characters if possible
• Use keywords Claude would search for

Step 5: Packaging a Skill

For official Anthropic workflow:

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

This validates and creates a distributable zip file.

For Claude Code: Skills in ~/.claude/skills/ are automatically available. No packaging needed.

For API: Use the /v1/skills endpoint to upload your skill folder.

Step 6: Iterate

After testing the skill:

1. Use the skill on real tasks
2. Notice struggles or inefficiencies
3. Identify how SKILL.md or bundled resources should be updated
4. Implement changes and test again

Iteration is expected. Skills improve through real-world usage.

Superpowers TDD Approach

Use this approach for skills that enforce workflows or resist rationalization. This is especially powerful for Claude Code workflow skills.

Key insight: Creating skills IS Test-Driven Development applied to process documentation.

RED Phase: Write Failing Test (Baseline)

Run pressure scenarios with a subagent WITHOUT the skill. Document exact behavior:

• What choices did they make?
• What rationalizations did they use (verbatim)?
• Which pressures triggered violations?

Example pressure scenarios:

• Time pressure: "This is urgent, we need it done quickly"
• Sunk cost: "I already spent hours writing this code"
• Authority: "The senior engineer said this approach is fine"
• Exhaustion: "After debugging for 2 hours, just make it work"

Output: Documented baseline behavior showing how Claude naturally fails without the skill

GREEN Phase: Write Minimal Skill

Write skill that addresses those specific rationalizations. Don't add extra content for hypothetical cases.

Structure for discipline skills:

## The Iron Law

[Clear, unambiguous rule]

## No Exceptions

- Not for "simple cases"
- Not for "just this once"
- Not for "already did the work"
[List specific rationalizations agents use]

## Red Flags - STOP

[List of symptoms that trigger the rule]

## Common Rationalizations

| Excuse | Reality |
|--------|---------|
[Table mapping each rationalization to counter-argument]

Run same scenarios WITH skill. Agent should now comply.

REFACTOR Phase: Close Loopholes

Agent found new rationalization? Add explicit counter. Re-test until bulletproof.

Iteration:

1. Identify NEW rationalizations from testing
2. Add explicit counters (if discipline skill)
3. Build rationalization table from all test iterations
4. Create red flags list
5. Re-test until bulletproof

Output: Skill that resists rationalization under maximum pressure

Progressive Disclosure Design

Skills use a three-level loading system for context efficiency. For details, load reference/progressive-disclosure.md.

Quick summary:

Level 1: Metadata (~100 words, always in context)

• YAML frontmatter only
• Helps Claude discover and select skills

Level 2: SKILL.md Body (<5k words, loaded when skill triggers)

• Core instructions and workflows
• References to bundled resources
• Essential examples

Level 3: Bundled Resources (unlimited, loaded as needed)

• scripts/ - Executable code
• references/ - Detailed documentation
• assets/ - Files used in output

Key principle: Keep SKILL.md lean. Move detailed content to references.

SKILL.md Best Practices

Naming

• Use hyphen-case: my-skill-name
• Match directory name exactly
• Use verb-first for actions: creating-skills not skill-creation
• Use gerunds (-ing) for processes: debugging-with-logs

Description

Bad:

description: For async testing

Good:

description: This skill should be used when tests have race conditions, timing dependencies, or inconsistent pass/fail behavior - replaces arbitrary timeouts with condition polling to eliminate flaky tests

Template:

description: This skill should be used when [triggering conditions and symptoms] - [what it does and how it helps]

Content Organization

Do:

• Start with Overview and When to Use
• Use headings for scannability
• Include Quick Reference tables
• Provide concrete examples
• Reference bundled resources clearly

Don't:

• Write multi-language examples (one excellent example beats many mediocre ones)
• Create generic templates ("fill in the blank" code)
• Duplicate content between SKILL.md and references
• Include narrative storytelling ("In session 2025-10-03, we found...")

Keep It Lean

Target word counts:

• Frequently-loaded skills: <200 words
• General skills: <500 words
• Complex skills: <5000 words (use references for more)

Techniques:

• Move API details to references, not inline
• Use cross-references instead of repeating content
• Compress examples to essential patterns
• Eliminate redundancy

Real-World Examples

Example 1: MCP Builder (Anthropic Official)

Structure:

mcp-builder/
├── SKILL.md (200 lines, ~2000 words)
├── reference/
│   ├── mcp_best_practices.md
│   ├── python_mcp_server.md
│   ├── node_mcp_server.md
│   └── evaluation.md
└── scripts/
    └── [bundled utilities]

Key features:

• Comprehensive 4-phase workflow
• Language-specific guides in references
• SKILL.md provides navigation, references contain details
• Progressive disclosure keeps main file lean

Example 2: Test-Driven Development (Superpowers)

Structure:

test-driven-development/
└── SKILL.md (365 lines, all inline)

Key features:

• The Iron Law: "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST"
• Explicit "No exceptions" list
• Common Rationalizations table
• Red Flags checklist
• Built using TDD methodology for skills

Example 3: Using shadcn/ui (Custom)

Structure:

using-shadcn-ui/
└── SKILL.md (1726 words, all inline)

Key features:

• Installation workflow
• Component categories reference table
• 829 shadcnblocks.com blocks organized by category
• Quick Start examples
• Common mistakes table

Quality Checklist

Before considering a skill complete:

Structure

• Directory name matches skill name in frontmatter
• SKILL.md exists with proper YAML frontmatter
• Name is lowercase, hyphen-case only
• Description is third-person, includes WHAT and WHEN

Content

• Overview explains core principle in 1-2 sentences
• "When to Use" section with specific triggers
• Clear instructions in imperative/infinitive form
• Concrete examples included
• Bundled resources (if any) are referenced clearly

Progressive Disclosure

• SKILL.md is lean (<5k words for complex skills)
• Detailed content moved to references (if needed)
• Scripts included for repeated code (if applicable)
• Assets included for output files (if applicable)

Quality

• No narrative storytelling
• One excellent example, not multi-language versions
• No generic templates or placeholders
• Cross-references use skill names, not file paths
• Keywords included for discoverability

Testing (for Superpowers TDD approach)

• Baseline behavior documented (RED phase)
• Skill addresses specific rationalizations (GREEN phase)
• Loopholes identified and closed (REFACTOR phase)
• Tested under pressure with subagents

Platform-Specific (if applicable)

• allowed-tools defined for Claude Code skills
• Scripts are executable and tested
• Reference files are properly formatted markdown
• Asset files are in correct formats

Common Mistakes

Mistake	Fix
Description in first person ("Use this skill when...")	Third person ("This skill should be used when...")
Using "you should" in instructions	Imperative form ("To do X, run Y")
Everything in SKILL.md	Move detailed content to references/
Multi-language examples	One excellent example in most relevant language
Generic placeholders	Concrete, runnable examples
Narrative storytelling	Reusable techniques and patterns
Missing "When to Use" section	Be explicit about triggering conditions
Vague description	Specific triggers and use cases

Resources

Official Anthropic Documentation:

• Skills announcement: https://www.anthropic.com/news/skills
• Example skills repository: https://github.com/anthropics/skills
• For complete Agent Skills Spec, load reference/anthropic-spec.md
• For progressive disclosure details, load reference/progressive-disclosure.md

Superpowers Skills:

• Writing skills: writing-skills skill for detailed TDD approach
• Testing skills: testing-skills-with-subagents for pressure testing methodology

Key Skills to Study:

• skill-creator (Anthropic) - Interactive skill creation
• mcp-builder (Anthropic) - Complex skill with bundled resources
• test-driven-development (Superpowers) - Discipline skill with rationalization resistance
• using-shadcn-ui (Custom) - Reference-heavy skill

Quick Start Template

---
name: my-skill-name
description: This skill should be used when [specific triggers] - [what it does]
---

# My Skill Name

## Overview

[1-2 sentences explaining core principle]

## When to Use

- Use when [trigger 1]
- Use when [trigger 2]
- Don't use when [anti-pattern]

## Process

[Step-by-step workflow]

## Resources (if applicable)

- **Scripts**: `scripts/example.py` - [purpose]
- **References**: Load `references/docs.md` for [details]
- **Assets**: Use `assets/template.html` for [output]

## Examples

[Concrete usage example]

## Common Mistakes

| Mistake | Fix |
|---------|-----|
[Common errors and solutions]

Final Thoughts

Choose your approach:

• Most skills → Anthropic's 6-step process
• Workflow/discipline skills → Superpowers TDD

Keep it simple:

• Start with minimal SKILL.md
• Add bundled resources only when needed
• Iterate based on real usage

Focus on value:

• What procedural knowledge does Claude need?
• What gets repeated that should be reusable?
• What makes the task easier or more reliable?

Skills are about teaching Claude to be consistently excellent at specialized tasks. Whether you use Anthropic's structured process or Superpowers' TDD approach, the goal is the same: create skills that make Claude measurably better at real-world work.