agent-skills

Use when creating a new skill under .agents/skills/, editing an existing one, or deciding whether a technique deserves to become a skill at all - covers SKILL.md structure, the description field, and

SKILL.md

GitHub

Agent Skills — Writing and Maintaining Skills

A skill is a reusable reference: a technique, pattern, or tool that a future agent session should be able to find and apply without re-deriving it from scratch. This skill is about authoring other skills in .agents/skills/.

When to Create a Skill

Create one when:

  • The technique wasn't obvious and took real effort to work out
  • It will plausibly be needed again, in this repo or elsewhere
  • It applies broadly, not to one specific file or one-off situation
  • Other contributors (human or agent) would benefit from finding it

Don't create one for:

  • A one-off fix specific to a single bug
  • Something already well documented upstream (framework docs, official guides)
  • A project convention that's mechanically enforceable — put that in ESLint config or a CI check, not prose
  • A narrative about how a problem was solved once — skills are reusable guides, not incident reports

Anatomy

.agents/skills/
  skill-name/
    SKILL.md              # required — the whole skill, if it fits
    reference.md           # optional — only for heavy reference material
    scripts/                # optional — only for reusable executable tooling

Flat, searchable namespace. Most skills in this repo need only SKILL.md — reach for a separate file only when something genuinely doesn't belong inline (a 300-line API reference, a script meant to be run rather than read).

SKILL.md Structure

Frontmatter — exactly two required fields:

---
name: skill-name-with-hyphens
description: Use when <specific triggering conditions>.
---
  • name: letters, numbers, hyphens only
  • description: third person, states only when to use it — not what it does or how. This is what an agent scans to decide whether to open the file at all.

Why "when," never "how," in the description: if the description summarizes the workflow, an agent can act on the summary and skip reading the actual skill — including the parts of the process the summary left out. Keep the description to triggering conditions; put the process in the body where it will actually get read before being followed.

# Bad — summarizes the process, invites skipping the body
description: Use for code review - dispatch a reviewer, read findings, fix critical issues

# Good — only the trigger
description: Use when completing a task or before merging, to catch issues before they ship

Body, roughly in this shape:

# Skill Name

## Overview
What is this, in 1-2 sentences. The core principle.

## When to Use
Concrete symptoms/situations that signal this applies (and, if non-obvious, when NOT to).

## Core Pattern / Process
The actual technique. Inline code for short patterns; a linked file for heavy reference.

## Common Mistakes
What goes wrong and the fix, ideally as a table.

Discovery: Make It Findable

A skill nobody finds isn't a skill, it's dead prose.

  • Keywords matter. Use the words an agent would actually search for: real error messages, symptom names, tool/command names — not just abstract category words.
  • Name by what it does or its core insight, verb-first or gerund where natural: systematic-debugging, not debugging-techniques; writing-plans, not plan-creation.
  • Keep it lean. SKILL.md content loads into context whenever the skill is used — every unnecessary paragraph is a tax on every future invocation. Cut narrative, cut redundant examples, keep one excellent example instead of three mediocre ones.
  • Cross-reference by name, not by force-loading. Point at another skill in this repo by its path/name ("see the verification-before-completion skill under superpowers/") rather than inlining its whole content — that keeps each skill focused and avoids drift when the referenced skill changes.

Writing Style

  • Imperative voice for instructions ("Run the test", not "You should run the test")
  • Explain why a rule exists, not just that it exists — a rule with a reason survives edge cases better than a bare "MUST"
  • One complete, realistic, copy-adaptable example beats three generic templates
  • Prefer tables for anything scannable (common mistakes, quick reference); prose for anything sequential

Before Calling a New Skill Done

  • name and description are both present and description states only when, not how
  • The body would make sense to someone who has never seen this repo before
  • No dangling references to files that don't actually exist in this skill's directory
  • It's short enough that loading it doesn't dominate the conversation it's used in
  • It was tried once for real, on a real task, before being trusted

Updating an Existing Skill

Same bar as writing a new one. If a skill turns out to have a gap (an agent following it still got something wrong), that's a signal to tighten the skill itself — add the missing case, don't just fix it in code and leave the skill stale for the next session.