​

Creating Skills

​

What is a Skill?

• Reusable techniques, patterns, tools, reference guides
• Documentation that helps agents discover and apply proven approaches
• Living documentation that evolves through testing and refinement

• Narratives about how you solved a problem once
• One-off solutions to specific problems
• Project-specific conventions (those belong in CLAUDE.md)

​

When to Create a Skill

​

Skill Types

​

Directory Structure

skills/
  skill-name/
    SKILL.md              # Main reference (required)
    supporting-file.*     # Only if needed

1. Heavy reference (100+ lines) - API docs, comprehensive syntax
2. Reusable tools - Scripts, utilities, templates

• Principles and concepts
• Code patterns (< 50 lines)
• Everything else

​

SKILL.md Structure

​

Frontmatter

---
name: skill-name-with-hyphens
description: Use when [specific triggering conditions and symptoms]
---

• Only two fields: name and description
• Max 1024 characters total
• name: Letters, numbers, and hyphens only (no parentheses, special chars)
• description: Third-person, describes ONLY when to use (NOT what it does)

​

Content Sections

# Skill Name

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

## When to Use
[Small inline flowchart IF decision non-obvious]

Bullet list with SYMPTOMS and use cases
When NOT to use

## Core Pattern (for techniques/patterns)
Before/after code comparison

## Quick Reference
Table or bullets for scanning common operations

## Implementation
Inline code for simple patterns
Link to file for heavy reference or reusable tools

## Common Mistakes
What goes wrong + fixes

## Real-World Impact (optional)
Concrete results

​

Claude Search Optimization (CSO)

# ❌ BAD: Summarizes workflow - Claude may follow this instead of reading skill
description: Use when executing plans - dispatches subagent per task with code review between tasks

# ❌ BAD: Too much process detail
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

# ✅ GOOD: Just triggering conditions, no workflow summary
description: Use when executing implementation plans with independent tasks in the current session

# ✅ GOOD: Triggering conditions only
description: Use when implementing any feature or bugfix, before writing implementation code

# ❌ BAD: Document all flags in SKILL.md
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# ✅ GOOD: Reference --help
search-conversations supports multiple modes and filters. Run --help for details.

# ❌ BAD: Repeat workflow details
When searching, dispatch subagent with template...
[20 lines of repeated instructions]

# ✅ GOOD: Reference other skill
Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.

​

Code Examples

• Testing techniques → TypeScript/JavaScript
• System debugging → Shell/Python
• Data processing → Python

• Is complete and runnable
• Has clear comments explaining WHY
• Comes from a real scenario
• Shows the pattern clearly
• Is ready to adapt (not a generic template)

• Implement in 5+ languages
• Create fill-in-the-blank templates
• Write contrived examples

​

File Organization Patterns

defense-in-depth/
  SKILL.md

condition-based-waiting/
  SKILL.md
  example.ts

pptx/
  SKILL.md
  pptxgenjs.md
  ooxml.md
  scripts/

​

Complete Example: Creating a Simple Skill

---
name: condition-based-waiting
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently
---

# Condition-Based Waiting

## Overview

Wait for conditions, not arbitrary timeouts. Tests should wait for the actual state change, not guess how long it takes.

## When to Use

**Use when:**
- Tests are flaky
- Using setTimeout or sleep in tests
- "Works locally but fails in CI"
- Race conditions in async code

**Don't use for:**
- Synchronous operations
- Intentional delays (debounce testing)

## Core Pattern

**Before (flaky):**
```typescript
test('updates user', async () => {
  updateUser({ name: 'Alice' });
  await sleep(100); // Hope it's done
  expect(getUser().name).toBe('Alice');
});

test('updates user', async () => {
  updateUser({ name: 'Alice' });
  await waitFor(() => getUser().name === 'Alice');
  expect(getUser().name).toBe('Alice');
});

await sleep(5000); // Longer = more flaky

await waitFor(() => condition, { timeout: 5000 });

​

Real-World Skills to Study

​

Skill Creation Checklist

• Create pressure scenarios (3+ combined pressures for discipline skills)
• Run scenarios WITHOUT skill - document baseline behavior verbatim
• Identify patterns in rationalizations/failures

• Name uses only letters, numbers, hyphens (no parentheses/special chars)
• YAML frontmatter with only name and description (max 1024 chars)
• Description starts with “Use when…” and includes specific triggers/symptoms
• Description written in third person
• Keywords throughout for search (errors, symptoms, tools)
• Clear overview with core principle
• Address specific baseline failures identified in RED
• Code inline OR link to separate file
• One excellent example (not multi-language)
• Run scenarios WITH skill - verify agents now comply

• Identify NEW rationalizations from testing
• Add explicit counters (if discipline skill)
• Build rationalization table from all test iterations
• Create red flags list
• Re-test until bulletproof

• Small flowchart only if decision non-obvious
• Quick reference table
• Common mistakes section
• No narrative storytelling
• Supporting files only for tools or heavy reference

• Commit skill to git and push to your fork (if configured)
• Consider contributing back via PR (if broadly useful)

​

Anti-Patterns to Avoid

step1 [label="import fs"];
step2 [label="read file"];

​

Next Steps

1. Test it thoroughly - See Testing Skills
2. Contribute it back - See Contributing
3. Iterate based on feedback - Skills are living documentation

​

Additional Resources

• Full skill creation guide: skills/writing-skills/SKILL.md in the source repository
• Anthropic’s official best practices: anthropic-best-practices.md
• Testing methodology: Testing Skills