/creating-skills-skill

name: creating-skills
description: Use when creating new Claude Code skills or improving existing ones - ensures skills are discoverable, scannable, and effective through proper structure, CSO optimization, and real examples

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)

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

# 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

# ❌ 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

// ✅ 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 comme