Most explainers of Anthropic's Agent Skills documentation are written by people who read the guide. I ship skills: a marketplace of 53 of them across 20 categories runs on my own site, and my daily Claude Code sessions lean on skills for code review, commits, and design work. So here is my decoded version of what the guide actually teaches, plus the parts I only learned by building at volume. The headline: a skill is not a saved prompt. It is packaged judgment with a loading strategy, and the loading strategy is the whole trick.
What a Claude Skill actually is
Mechanically, a skill is a folder containing a SKILL.md file: YAML frontmatter on top, markdown instructions below, optionally accompanied by scripts, templates, and reference files. Only two frontmatter fields are required, name and description, and everything else is optional. That minimalism is deliberate, and it fools people into thinking skills are trivial. The design is in how they load.
Skills use progressive disclosure in three stages:
- Discovery. At startup, the agent loads only each skill's name and description. Dozens of skills cost almost nothing in context.
- Activation. When a task matches a description, the agent reads the full SKILL.md into context.
- Execution. Instructions can reference bundled files and scripts, which load or run only when actually needed.
Compare that to pasting a mega-prompt: the mega-prompt charges you its full token cost on every message of every session, relevant or not. A skill charges a one-line description until the moment it earns its keep. That difference is why a skill library scales and a prompt library, kept raw, eventually cannot. I say that as someone who maintains both and watched the economics diverge.
The two lines that decide everything
Here is the insight the documentation states politely and experience states brutally: the description field determines whether your skill ever runs. Activation is a matching decision made against the description alone, at a moment when the model has not read your beautiful instructions and never will unless the description wins.
Across 53 skills, my failure pattern was consistent. Descriptions that describe what the skill is ("A comprehensive meeting productivity assistant") activate unreliably. Descriptions that describe when to reach for it ("Use when the user wants meeting notes summarized, action items extracted, or a follow-up email drafted") activate on cue. Write the description as a trigger condition, name the concrete task nouns a user would actually say, and if two of your skills could match the same request, rewrite both until they cannot. I had to differentiate four near-overlapping pairs in my own catalog after watching them shadow each other; overlapping descriptions do not split traffic politely, they make activation unpredictable.
Anatomy of a skill that holds up
The structure that survived contact with real users across my catalog:
- Persona and stance: not "you are helpful," but the actual judgment stance ("bias toward deleting code," "never invent a metric").
- Context intake: what the skill needs to ask for or gather before acting, with placeholders for the variables that change per run.
- Numbered deliverables: exactly what gets produced, in what order.
- Output spec: format, length, tone constraints. This is what separates repeatable output from output that drifts with the model's mood.
- Boundaries: what the skill must not do. The most valuable section in my experience, and the one beginners omit entirely.
Bundled files earn their place when instructions would otherwise bloat: a reference document the skill consults, a template it fills, a script it runs. Keep SKILL.md itself readable in one sitting; push the rest to stage three where it costs nothing until used.
The lesson I learned the expensive way: honesty is architecture
My skills marketplace taught me a lesson that no skills guide includes. At one point, the marketplace's detail pages were being removed from Google's index, and I assumed thin content. The actual cause was fabricated credibility: the pages emitted structured data with a hardcoded aggregate rating and invented review counts. I removed the fake schema, rewrote the catalog with truthful first-person field notes about when I actually reach for each skill, and the fabrication problem, not word count, turned out to be what mattered.
The transferable principle for skill builders: metadata is a promise, whether it is JSON-LD to a search engine or a description to a model. Inflate either one and the system built on trusting it will eventually route around you. Every skill in my catalog now carries an honest usage note instead of manufactured social proof, and both Google and my own conscience prefer it. My deeper collection of scars from authoring these is in lessons from building Claude Code skills.
Skills, slash commands, subagents: which one is this?
The ecosystem overlaps and the guide will not pick lanes for you, so here is how I divide my own tooling. Knowledge and judgment that should activate contextually goes in a skill. A workflow I invoke deliberately becomes a slash command; my daily set is in the slash commands I actually use. Work that needs its own context window becomes a subagent. The three compose: my code-review command loads review judgment that reads like a skill, and my batch pipelines spawn subagents whose instructions are effectively skills with assignments attached.
A rule of thumb that has served me: if you keep pasting the same instructions, you want a command; if you keep wishing Claude "just knew" something at the right moment, you want a skill. For the broader inventory of what is worth installing versus building, see my agent skills guide for Claude Code and the wider agent skills ecosystem overview.
How to build your first one this week
Pick the task you have explained to Claude more than three times. Write the description first, as a trigger condition, before any instructions exist. Then write the instruction body in the five-part anatomy above, deliberately including the boundaries section. Test activation by phrasing requests the way you naturally would, not the way the description does; if it fails to fire, fix the description, not the body. Then use it for two weeks before showing anyone, because the second draft written after real use is always the real skill. Domain-specific walkthroughs like my SEO content writer skill build show what the finished shape looks like in one vertical.
The catalog that all of these lessons come from is live: 53 skills across 20 categories, each with honest field notes on when I actually use it, at the Agent Skills Marketplace. Browse it before you build your own; stealing a working structure beats decoding documentation from scratch, and I have already made the mistakes for you.
