Skills
A skill is a folder of instructions the agent loads only when it's relevant — capability on demand, paid for only when used.
What a skill is
A skill is a SKILL.md file with YAML frontmatter — a
name and description — plus the actual
instructions, optionally bundling scripts and reference files alongside it. It's
model-invoked: Claude always sees the short description, and pulls in the
full body only when the task matches. Nothing loads that isn't needed.
The format is a portable folder — the same skill runs in Claude Code, Codex, Cursor and around 35 other tools via the open standard at agentskills.io. Two things worth distinguishing: slash commands have been absorbed into skills (they're the same mechanism now); subagents are separate context windows, whereas a skill is injected directly into the current one.
Progressive disclosure
The key design insight is three tiers of context cost, each loaded only when justified. The gate between level one and two is the model's own judgment about relevance.
You pay ~100 tokens to know about a skill. You pay for the body only when you use it.
What's in the folder
The directory layout is intentionally minimal. A single required file, optional extras:
pdf-skill/
SKILL.md # required — frontmatter + instructions
REFERENCE.md # optional reference doc (loaded on demand)
scripts/
fill_form.py # optional — runs via bash, output enters context---
name: fill-pdf-form
description: Fill and export PDF forms using the bundled script.
---
# instructions follow here...- ↳
Required fields
name(≤ 64 chars) anddescription(≤ 1024 chars) — this is the entire discovery surface. Write the description as if it's the only thing the model will read, because sometimes it is. - ↳
Where they live
~/.claude/skills/for user-level skills,.claude/skills/inside a project for project-scoped ones, or packaged as plugin skills distributed via npm. - ↳
Live edits
Changes take effect immediately — no restart needed. Edit the
SKILL.md, save, and the next invocation picks up the new version.
Where to get them
The ecosystem is young but already has a useful spread from official to community-curated:
- 1
anthropics/skills — official
Anthropic's own library: PDF fill, PowerPoint generation, Excel manipulation, and the skill-creator template for bootstrapping new ones. The canonical starting point.
- 2
obra/superpowers — Jesse Vincent's methodology set
A whole development philosophy shipped as skills: test-driven-development, systematic-debugging, brainstorming, writing-plans. Opinionated and worth reading even if you don't adopt it wholesale.
- 3
ComposioHQ/awesome-claude-skills & hesreallyhim/awesome-claude-code
The two big curated indexes. Between them they cover most community contributions — good for browsing what exists before writing your own.
- 4
agentskills.io — the open standard
The spec that ties all of the above together and makes skills portable across ~35 tools. Read it once so you understand what's actually guaranteed vs. tool-specific.
How I actually use it
My take
I treat skills as the agent's muscle memory. Any procedure I'd otherwise paste into the conversation every single time — a review checklist, a planning ritual, a build-fix loop — becomes a skill that loads itself at the right moment, costing nothing until then. The cognitive shift is from "what do I need to tell it right now?" to "what would I want it to always know how to do?" Build that library once and every future session inherits it.
Sources
- primary Anthropic — Agent Skills The announcement: SKILL.md folders, model-invoked, progressive disclosure.
- primary Claude Code — Skills docs Frontmatter fields, storage locations, slash-command merge.
- reading agentskills.io — the open standard One SKILL.md format, ~35 tools adopting it (Codex, Gemini, Cursor…).
- repo obra/superpowers Jesse Vincent's methodology-as-skills: TDD, debugging, brainstorming.
- repo anthropics/skills Official examples: PDF, PowerPoint, Excel, the skill-creator template.