Skills

A Skill is the cleanest way to package a “way of working” so Claude finds and follows it without you re-prompting every time.

A Skill is just a directory: a frontmattered .md, optional scripts, optional supporting .md files. Discoverable by description, loaded on demand. Skills are how you compound expertise into the system.

Why make skills

AGENTS.md handles durable project facts, always in context. Skills handle load-on-demand expertise: present in the catalog, only loaded into the window when they apply.

The practical difference:

• AGENTS.md: read on every turn. Use for facts and rules you always want applied. Every line costs tokens every turn.
• Skills: indexed by their frontmatter description. Only read when a matching task appears. Can be arbitrarily large; only the triggered one gets loaded.

This lets you codify a lot of expertise without bloating the default context. Your AGENTS.md stays tight; your Skills library can grow indefinitely.

Practically, Skills are what you build when you find yourself:

• Explaining the same workflow to Claude more than twice
• Copy-pasting the same template every time you start a similar task
• Wishing Claude would just know how to do X without being told
• Watching Claude produce something 80% right that you always have to correct the same way

The anatomy of a Skill

A Skill is a directory (typically under ~/.claude/skills/ for user-level, or .claude/skills/ in a repo for project-level). Inside:

my-skill/
  SKILL.md          # frontmatter + playbook
  scripts/          # optional: deterministic helpers
    helper.py
  references/       # optional: templates, examples, deeper docs
    template.md

Frontmatter: the discovery hook

The top of SKILL.md is YAML frontmatter:

---
name: invoice
description: Generate client invoices as PDFs from work-tracker data, using per-client billing models. Triggers when user asks to bill a client or generate an invoice.
---

Claude decides whether to load a Skill by reading the description against the current task. The description is the most important thing in the file. It needs to state, clearly and specifically, when this Skill applies. Vague descriptions don’t match; they just bloat the catalog.

Good description patterns:

• What the Skill does, in one sentence
• What triggers it: specific user intents, file types, or phrases
• What not to use it for, if there’s a close cousin

Main .md: the playbook

Below the frontmatter, write the actual instructions. Treat this like a good AGENTS.md for a narrow slice of work: tight, deliberate, specific. This is what Claude reads after deciding the Skill applies.

Include:

• The goal the Skill serves
• Step-by-step procedure or decision tree
• Inputs it expects, outputs it produces
• Things to watch out for

Scripts: deterministic helpers

Some tasks have deterministic pieces that don’t need LLM reasoning: file manipulation, API calls, calculations. Put those in scripts the Skill’s playbook invokes. This keeps the model doing what it’s good at (reasoning, synthesis, writing) and off the things it isn’t (computation, strict formatting).

Supporting .md files

Longer references, templates, or examples belong in separate .md files under references/ or similar. The main SKILL.md links to them; Claude reads them when relevant. Keeps the primary playbook short.

When to make a Skill

A rough decision tree:

• One-off task → just prompt. Skills are overhead.
• Pattern you’ll repeat across projects → user-level Skill in ~/.claude/skills/.
• Pattern specific to this project → project-level Skill in .claude/skills/.
• Knowledge that should always apply to this project → AGENTS.md instead; Skills are for load-on-demand.

How to make a Skill

The most efficient way is to let Claude make it for you. At the end of a session where you’ve taught Claude how to do something well (corrected it into a good shape through iteration), ask:

“Package what we just did as a Skill. Write the SKILL.md, propose a good description, and put any reusable scripts in place. Save it under ~/.claude/skills/<name>/.”

Review what it produces. Trim anything that’s obvious or transient. Sharpen the description. Commit.

A session that used to take a lot of prompting now loads a Skill and just works.

Skill examples

Real Skills you can see day-to-day, each a few files:

• planner: personal and professional planning; status readouts, idea capture, priority management.
• work-tracker: deterministic hour extraction from Claude Code session logs.
• invoice: generate client PDFs from work-tracker data, per-client billing models.
• reflections: capture concepts, decisions, and insights from sessions into persistent project memory.
• aeo-analysis: probe LLM answer engines to see how they recommend in your space.

Each one started as “I keep explaining this” and became a Skill after the second or third time.

Resources

• Anthropic: Skills documentation