creating-skills

What this skill does

# Creating Skills

## Overview

**Skills are reference guides for proven techniques, patterns, or tools.** Write them to help future Claude instances quickly find and apply effective approaches.

Skills must be **discoverable** (Claude can find them), **scannable** (quick to evaluate), and **actionable** (clear examples).

**Core principle**: Default assumption is Claude is already very smart. Only add context Claude doesn't already have.

## When to Use

**Create a skill when:**
- Technique wasn't intuitively obvious
- Pattern applies broadly across projects
- You'd reference this again
- Others would benefit

**Don't create for:**
- One-off solutions specific to single project
- Standard practices well-documented elsewhere
- Project conventions (put those in `.claude/CLAUDE.md`)

## Required Structure

### Frontmatter (YAML)

```yaml
---
name: skill-name-with-hyphens
description: Use when [triggers/symptoms] - [what it does and how it helps]
tags: relevant-tags
---
```

**Rules:**
- Only `name` and `description` fields supported (max 1024 chars total)
- Name: letters, numbers, hyphens only (max 64 chars). Use gerund form (verb + -ing)
- Avoid reserved words: "anthropic", "claude" in names
- Description: Third person, starts with "Use when..." (max 1024 chars)
- Include BOTH triggering conditions AND what skill does
- Match specificity to task complexity (degrees of freedom)

### Document Structure

```markdown
# Skill Name

## Overview
Core principle in 1-2 sentences. What is this?

## When to Use
- Bullet list with symptoms and use cases
- When NOT to use

## Quick Reference
Table or bullets for common operations

## Implementation
Inline code for simple patterns
Link to separate file for heavy reference (100+ lines)

## Common Mistakes
What goes wrong + how to fix

## Real-World Impact (optional)
Concrete results from using this technique
```

## Degrees of Freedom

**Match specificity to task complexity:**

- **High freedom**: Flexible tasks requiring judgment
  - Use broad guidance, principles, examples
  - Let Claude adapt approach to context
  - Example: "Use when designing APIs - provides REST principles and patterns"

- **Low freedom**: Fragile or critical operations
  - Be explicit about exact steps
  - Include validation checks
  - Example: "Use when deploying to production - follow exact deployment checklist with rollback procedures"

**Red flag**: If skill tries to constrain Claude too much on creative tasks, reduce specificity. If skill is too vague on critical operations, add explicit steps.

## Claude Search Optimization (CSO)

**Critical:** Future Claude reads the description to decide if skill is relevant. Optimize for discovery.

### Description Best Practices

```yaml
# ❌ BAD - Too vague, doesn't mention when to use
description: For async testing

# ❌ BAD - First person (injected into system prompt)
description: I help you with flaky tests

# ✅ GOOD - Triggers + what it does
description: Use when tests have race conditions or pass/fail inconsistently - replaces arbitrary timeouts with condition polling for reliable async tests

# ✅ GOOD - Technology-specific with explicit trigger
description: Use when using React Router and handling auth redirects - provides patterns for protected routes and auth state management
```

### Keyword Coverage

Use words Claude would search for:
- **Error messages**: "ENOENT", "Cannot read property", "Timeout"
- **Symptoms**: "flaky", "hanging", "race condition", "memory leak"
- **Synonyms**: "cleanup/teardown/afterEach", "timeout/hang/freeze"
- **Tools**: Actual command names, library names, file types

### Naming Conventions

**Use gerund form (verb + -ing):**
- ✅ `creating-skills` not `skill-creation`
- ✅ `testing-with-subagents` not `subagent-testing`
- ✅ `debugging-memory-leaks` not `memory-leak-debugging`
- ✅ `processing-pdfs` not `pdf-processor`
- ✅ `analyzing-spreadsheets` not `spreadsheet-analysis`

**Why gerunds work:**
- Describes the action you're taking
- Active and clear
- Consistent with Anthropic conventions

**Avoid:**
- ❌ Vague names like "Helper" or "Utils"
- ❌ Passive voice constructions

## Code Examples

**One excellent example beats many mediocre ones.**

### Choose Language by Use Case

- Testing techniques → TypeScript/JavaScript
- System debugging → Shell/Python
- Data processing → Python
- API calls → TypeScript/JavaScript

### Good Example Checklist

- [ ] Complete and runnable
- [ ] Well-commented explaining **WHY** not just what
- [ ] From real scenario (not contrived)
- [ ] Shows pattern clearly
- [ ] Ready to adapt (not generic template)
- [ ] Shows both BAD (❌) and GOOD (✅) approaches
- [ ] Includes realistic context/setup code

### Example Template

```typescript
// ✅ GOOD - Clear, complete, ready to adapt
interface RetryOptions {
  maxAttempts: number;
  delayMs: number;
  backoff?: 'linear' | 'exponential';
}

async function retryOperation<T>(
  operation: () => Promise<T>,
  options: RetryOptions
): Promise<T> {
  const { maxAttempts, delayMs, backoff = 'linear' } = options;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await operation();
    } catch (error) {
      if (attempt === maxAttempts) throw error;

      const delay = backoff === 'exponential'
        ? delayMs * Math.pow(2, attempt - 1)
        : delayMs * attempt;

      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }

  throw new Error('Unreachable');
}

// Usage
const data = await retryOperation(
  () => fetchUserData(userId),
  { maxAttempts: 3, delayMs: 1000, backoff: 'exponential' }
);
```

### Don't

- ❌ Implement in 5+ languages (you're good at porting)
- ❌ Create fill-in-the-blank templates
- ❌ Write contrived examples
- ❌ Show only code without comments

## File Organization

### Self-Contained (Preferred)

```
typescript-type-safety/
  SKILL.md    # Everything inline
```

**When:** All content fits in ~500 words, no heavy reference needed

### With Supporting Files

```
api-integration/
  SKILL.md           # Overview + patterns
  retry-helpers.ts   # Reusable code
  examples/
    auth-example.ts
    pagination-example.ts
```

**When:** Reusable tools or multiple complete examples needed

### With Heavy Reference

```
aws-sdk/
  SKILL.md       # Overview + workflows
  s3-api.md      # 600 lines API reference
  lambda-api.md  # 500 lines API reference
```

**When:** Reference material > 100 lines

## Token Efficiency

Skills load into every conversation. Keep them concise.

### Target Limits

- **SKILL.md**: Keep under 500 lines
- Getting-started workflows: <150 words
- Frequently-loaded skills: <200 words total
- Other skills: <500 words
- Files > 100 lines: Include table of contents

**Challenge each piece of information**: "Does Claude really need this explanation?"

### Compression Techniques

```markdown
# ❌ BAD - Verbose (42 words)
Your human partner asks: "How did we handle authentication errors in React Router before?"
You should respond: "I'll search past conversations for React Router authentication patterns."
Then dispatch a subagent with the search query: "React Router authentication error handling 401"

# ✅ GOOD - Concise (20 words)
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]
```

**Techniques:**
- Reference tool `--help` instead of documenting all flags
- Cross-reference other skills instead of repeating content
- Show minimal example of pattern
- Eliminate redundancy
- Use progressive disclosure (reference additional files as needed)
- Organize content by domain for focused context

## Workflow Recommendations

For multi-step processes, include:

1. **Clear sequential steps**: Break complex tasks into numbered operations
2. **Feedback loops**: Build in verification/validation steps
3. **Error handling**: What to check when things go wrong
4. **Checklists**: For processes with many steps or easy-to-miss details

**Example structure:**
```markdown
## Workflo