Agent Skills: How a Folder of Markdown Changes the Way Claude Code Works

An Agent Skill is a folder with a SKILL.md file in it: a few lines of YAML frontmatter, then instructions in plain Markdown. Claude reads the descriptions of every installed skill at startup and pulls in the full instructions only when one becomes relevant.

That is the entire mechanism. No SDK, no plugin API, no build step. The interesting part is what people have built with it — and the fact that the most popular collections mostly exist to make the agent do less.

Key takeaways

• A skill is Markdown in a folder. The only recommended frontmatter field is description, and it is the field that decides whether the skill ever fires.
• Three-level progressive disclosure keeps them cheap: about a hundred tokens per installed skill until one triggers.
• Slash commands have been merged into skills — the same file gives you both.
• Skills change how the agent works; MCP servers change what it can reach. Different problems.
• Three of the five most-starred community collections are reduction tools. The 2026 complaint about coding agents is not that they do too little.
• Skills are instructions your agent will follow. Read them before you install them.

What problem do skills solve?

Repetition. You tell the agent the same five things every week. Do not invent a helper when one exists. Do not refactor files I did not ask about. Write the test first. Ask before you assume what I meant.

You can put all of that in a project instructions file, and you should. But an instructions file is always in context, so it is either short and generic, or long and expensive. There is no room for the twelve-step deployment procedure you follow four times a year.

Skills solve exactly that shape: knowledge that is valuable when relevant and pure cost when not.

What does a skill look like?

A directory whose name becomes the command, containing a Markdown file:

my-skill/
├── SKILL.md      (required — overview and navigation)
├── reference.md  (detailed docs — loaded only when needed)
├── examples.md   (usage examples — loaded only when needed)
└── scripts/
    └── helper.py (executed, not loaded)

And the file itself starts with frontmatter:

---
name: release-checklist
description: >
  Our release procedure. Use when cutting a release, tagging a version,
  or the user says "ship it", "cut a release", or "deploy to production".
  Do NOT use for ordinary commits or pull requests.
---

## Before you tag
1. Confirm CI is green on main.
...

Note how much work that description is doing. Because it is the only thing loaded until the skill fires, it has to carry positive triggers, literal phrases a user might type, and negative triggers telling the model when not to reach for it. Most skills that never fire have a vague description, not a bad body.

How does progressive disclosure work?

This is the design decision that makes a large skill library practical rather than ruinous.

That third row is the one people miss. A bundled script is executed, not read into context — so a skill can wrap an arbitrarily complex program and cost you only the answer it prints. Anthropic's guidance is to keep SKILL.md under 500 lines and push detail into files the skill points at.

Where do skills live?

• Personal — ~/.claude/skills/<name>/SKILL.md, available in every project. Your habits.
• Project — .claude/skills/<name>/SKILL.md, committed to the repository. Your team's conventions, versioned with the code they describe.
• Plugin — skills bundled inside an installed plugin, namespaced plugin-name:skill-name so they cannot collide with yours.

The project-level option is the one agencies undervalue. A repository that carries its own deployment procedure, its own review checklist and its own domain glossary is a repository that onboards a new developer — or a new agent — considerably faster.

Skills, commands, subagents and MCP

These four get confused constantly, so, briefly:

• Slash commands are skills now. They were merged. The same file produces both an invocable command and a model-triggered skill.
• Subagents are a delegation mechanism — a separate context doing a scoped job. A subagent can preload skills, and preloaded skills arrive as full content rather than descriptions.
• MCP servers are connectivity. They give the agent tools, databases and APIs it otherwise could not reach. We cover the protocol in our MCP guide.

The one-line distinction worth remembering: a skill grants no new capability, only better judgement about capabilities the agent already has. If your problem is "it cannot see our database", you need MCP. If it is "it keeps writing 200 lines where 50 would do", you need a skill.

Five collections worth looking at

The community output here is large and uneven. These five are the ones worth your time, with honest notes on each.

karpathy-guidelines is one small file, and the most valuable idea in it is reframing a prompt as success criteria rather than a procedure — models are good at looping until a goal is met. Caveat: the repository has had no commits for months, and it claims MIT in its README while shipping no licence file.

ponytail is the anti-over-engineering one, and its benchmark is unusually honest — it reports large gains where there is a real over-build trap and near-zero gains on already minimal code. Its description field is a masterclass worth reading purely as a writing example. Note the author is anonymous.

caveman makes a genuinely sharp technical observation: it refuses to abbreviate words, because tokenizers split abbreviations into roughly the same token count as the full word — so you lose clarity for no saving. It also suspends itself for security warnings and irreversible actions, which is the right instinct. Its licence is split MIT and BSL.

mattpocock/skills — from Matt Pocock of Total TypeScript — is the best implementation of progressive disclosure of the five, with SKILL.md files that link out to reference files rather than inlining them. It also treats "the agent got it wrong" as a requirements problem rather than a style problem, which is the correct diagnosis more often than not.

gstack — Garry Tan's published setup — is the largest and the most opinionated. Its most quietly useful pieces are the unglamorous ones: guardrails that warn before destructive commands, a flag that restricts edits to one directory, and a tool that audits what an installed skill tree costs in tokens. It also uses frontmatter fields that are not in the specification, so its skills are less portable.

The pattern nobody planned

Look at that list again. Three of the five most-starred skill collections exist to make the agent produce less: fewer lines, fewer tokens, fewer unrequested changes.

That is a real signal about where coding agents are in 2026. The capability problem is largely solved. The restraint problem is not. Given an ambiguous request, an agent will confidently build the general case, add configuration nobody asked for, and refactor two adjacent files while it is there.

If you write one skill this month, write the one that says what your team does not want done.

How to write a skill that actually fires

1. Spend most of your effort on the description. It is the only thing the model sees until the skill triggers. Include the literal phrases people say.
2. Include negative triggers. "Do not use for..." prevents a skill firing on everything, which is worse than it never firing.
3. Keep the body under 500 lines and move detail into reference files.
4. Put procedures in scripts. A deterministic step should be a script the skill runs, not prose the model reinterprets each time.
5. Commit team skills to the repository. .claude/skills/ is where your conventions belong, next to the code they govern.
6. Delete skills that never fire. Each one costs metadata tokens forever. Audit occasionally.

A word on trust

Anthropic's documentation is explicit: use skills only from trusted sources. A skill is instructions your agent will follow, and collections that also ship hooks or scripts are executing code on your machine.

Two of the five collections above are maintained by anonymous accounts. That is not an accusation — plenty of excellent software is written pseudonymously — but combined with what a laundered repository looks like, it argues for reading the Markdown before you install it. It is Markdown. Reading it takes five minutes.

Conclusion

Agent Skills are the rare extension mechanism with almost no learning curve. If you can write a good README you can write a good skill, and the three-level loading means a large library costs almost nothing until it is needed.

Start with two: one that encodes how your team actually works, and one that tells the agent what not to do. That pair will earn its keep in a week.

Want your team's conventions encoded rather than repeated?

DI Solutions sets up AI-assisted development that fits how your team already works — project skills, review gates and guardrails that make agent output reviewable instead of surprising. Talk to our engineering team.

Reference links

• Claude Code documentation — Skills
• mattpocock/skills
• garrytan/gstack
• ponytail
• caveman