compose:new-skill

Writing Skills

Overview

A skill is a reusable reference guide — techniques, patterns, or tools — that helps agents find and apply effective approaches.

Skills are: Reusable techniques, patterns, tools, reference guides

Skills are NOT: Narratives about how you solved a problem once

When to Create a Skill

Create when:

• Technique wasn't intuitively obvious
• You'd reference this again across projects
• Pattern applies broadly (not project-specific)
• Others would benefit from this knowledge

Don't create for:

• One-off solutions
• Standard practices well-documented elsewhere
• Project-specific conventions (put in project config like CLAUDE.md)
• Mechanical constraints enforceable with regex/validation (automate it instead)

Skill Types

Type	Purpose	Examples
Technique	Concrete method with steps	condition-based-waiting, root-cause-tracing
Pattern	Way of thinking about problems	flatten-with-flags, test-invariants
Reference	API docs, syntax guides	tool documentation, library guides

SKILL.md Format

---
name: skill-name
description: Use when [specific triggering conditions]
---

# Skill Name

## Overview
Core principle in 1-2 sentences.

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

## Core Pattern
Before/after code comparison or step-by-step process.

## Quick Reference
Table or bullets for scanning common operations.

## Common Mistakes
What goes wrong + fixes.

Frontmatter Rules

• name: letters, numbers, hyphens only (max 64 chars)
• description: third-person, starts with "Use when...", max 1024 chars
• Description should ONLY describe triggering conditions — never summarize the skill's workflow

Description: Why This Matters

Testing revealed that when a description summarizes the skill's workflow, agents may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused the agent to do ONE review, even though the skill's flowchart clearly showed TWO reviews.