creating-skills

Creating Skills

Overview

A skill is a unit of transferable understanding, not a documentation page. It teaches an AI assistant a pattern well enough that it applies the pattern correctly without being reminded — including knowing when not to apply it.

Every skill has two layers. The generic layer stands alone: someone who has never seen your codebase reads it and understands the pattern. The source layer grounds it: real code from a real file proves the pattern is battle-tested, not invented.

If a skill only has the source layer, it's internal documentation. If it only has the generic layer, it's a blog post. Both layers together make it a skill.

---

Structure

Every skill follows this order:

---
name: skill-name
description: Use when [specific triggering conditions — NOT a summary of what the skill does]
---

# Skill Name

## The pattern          ← generic, no codebase knowledge required
## Why this matters  ← domain connection: what breaks for users without this
## How to apply it      ← concrete steps
## In the source  ← real source code with // Source: file/path.ext
## Apply it to your code  ← before/after with // WHY: comments on every change
## Signals that you need this pattern
## Signals that you're over-applying it
## Works with           ← related skills

---

The real-code requirement

The pattern section must contain code extracted from the actual source — not code written to illustrate the concept.

How to tell the difference:

• Invented code looks clean, minimal, and perfectly illustrative
• Real code has imports, handles edge cases, and sometimes does things that seem unrelated to the pattern

Real code earns trust. Invented code loses it the moment a reader opens the actual file and finds something different.

Every code block in section 4 must have a // Source: path/to/actual/file.ext comment. If you can't point to a file, the code doesn't belong in the pattern section.

---

The two-layer rule

The generic section ("The pattern") must pass the stranger test: someone who has never heard of the source codebase reads it and can apply the pattern to their own project.