AI Skills

A folder my agent knows how to read

For a couple of years, teaching an AI assistant your workflow meant pasting the same paragraph of instructions into a different box for every tool you used. Rewrite it for the terminal agent, rewrite it again for the editor, watch both drift out of date. Agent Skills fix that by being boring: a folder, a Markdown file, and a spec that a couple of dozen tools have agreed to read.

I wrote about Claude Code skills a couple of months ago, back when they still looked like a Claude Code feature. They aren’t one any more. Anthropic published the format as an open standard, the rest of the industry picked it up faster than anyone expected, and there is now a registry layer sitting on top of it. That changes the calculation. A skill you write today is not a bet on one vendor’s roadmap.

This post is about the format itself: what the spec requires, what it merely suggests, how the loading model works, and where the sharp edges are.

What is actually in one

A skill is a directory with a SKILL.md in it. The file starts with YAML frontmatter and continues with plain instructions. That is the entire required surface.

---
name: changelog
description: Generate a changelog entry from staged git changes.
  Use when the user asks to write a changelog or a release note.
---

## Writing a changelog entry

1. Run `git diff --staged` to see what changed.
2. Group changes under Added, Changed, Fixed, Removed.
3. Write each entry in past tense, user-facing language.
4. Skip internal refactors that don't affect behaviour.
5. Prepend the entry to `CHANGELOG.md` under an `## [Unreleased]` heading.

That is a working skill. No SDK, no build step, nothing to register. The agent reads the description, decides the skill applies, loads the instructions and follows them.

A skill can carry more than the one file, and the spec suggests three conventional directories for it:

my-skill/
├── SKILL.md          # required: metadata and instructions
├── scripts/          # executable code the agent can run
├── references/       # documentation loaded on demand
└── assets/           # templates, schemas, images

None of those are mandatory, and the agent will happily read anything else you put in the folder. The convention exists so that a skill someone else wrote is legible at a glance. That bundling is the real difference between a skill and a saved prompt: a prompt is text, a skill is text plus the script that does the fiddly part and the reference file you would otherwise have to summarise badly.

The frontmatter, field by field

Two fields are required and four are optional. It is a short spec, which I appreciate.

The name rules trip people up more than they should. No uppercase, no leading or trailing hyphen, no consecutive hyphens, and it has to match the folder. pdf--processing is invalid and the error message you get depends entirely on which agent you are running.

The description is the field to spend time on, because it is the only part of your skill the agent sees until it decides to use it. “Helps with testing” tells it nothing. “Use when the user asks to write or fix a Vitest unit test, or when a test file is open and failing” gives it a trigger it can match against. Write it for a matching algorithm, not for a README.

Individual agents add their own fields on top. Claude Code has disable-model-invocation, argument-hint and a few others; those are not in the spec and other tools will ignore them. That is fine as long as you know which half of your frontmatter is portable.

Why fifty skills don’t cost fifty skills

Skills load in three stages, and this is the design decision that makes the whole thing viable.

1. Discovery. At startup the agent reads only name and description for every installed skill. Budget roughly a hundred tokens each.
2. Activation. When a task matches, the full SKILL.md body is read into context. The spec recommends staying under 5000 tokens, or about 500 lines.
3. Execution. Anything in scripts/, references/ or assets/ is pulled in only when the instructions point at it.

So a skill you never use costs you a sentence. That is why you can have several dozen installed without the context window turning to soup, and it is also why the “keep SKILL.md short, push detail into reference files” advice is about cost rather than tidiness. Every token sitting in an activated skill is a token not being spent on your actual code.

One practical rule from the spec that is easy to miss: keep file references one level deep from SKILL.md and use relative paths. Chains of references that point at further references are exactly as fun to debug as they sound.

Who reads them

The format came out of Anthropic and was released as an open standard at agentskills.io, with the specification and a reference validator developed in the open on GitHub. The spec document is not the interesting part. Adoption is.

The client showcase on agentskills.io runs to several dozen entries at this point, including some genuinely unexpected ones (Laravel Boost, Spring AI, Snowflake’s Cortex Code). Competitors who agree on very little agreed on this within about two days of the spec landing, which tells you how much everybody wanted the problem to go away.

The practical upshot is mundane and useful. If your team encodes its deployment checklist as a skill, it works whether a given colleague lives in a terminal or an IDE, and it keeps working when half of them switch tools next quarter. Your ChatGPT custom instructions have never done that for you.

Getting them onto your machine

Agents scan conventional directories. Paths vary slightly, but the Claude Code layout is representative:

Personal skills are for habits that belong to you: how you like commit messages written, how you want code explained. Project skills belong in version control, which is the part I care about more. Commit them and every fresh checkout arrives with the team’s playbooks already attached. Nobody has to be told about the deployment procedure, because it is sitting in the repository.

Installing a skill by hand means dropping a folder in the right place. That works fine until you want to share one.

Running them

Two ways in.

The first is explicit: type the skill’s name as a command, /changelog, and the agent follows that playbook and no other. The second is automatic: the agent reads descriptions, decides yours matches what you just asked for, and loads it without being told. Most of the time the automatic path is the one you want, and it is also the one that makes a good description pay for itself.

For anything with side effects, turn the automatic path off. Deploying, deleting, sending a message to a customer: these should only ever happen because you typed the command. In Claude Code that is a frontmatter flag:

---
name: deploy
description: Deploys the app to production.
disable-model-invocation: true
---

Read-only skills can be automatic. Destructive ones should be explicit. I have not found a case where the reverse was defensible.

Writing one

The best first skill is the workflow you have explained to an agent more than twice. Open a folder, write the file, and keep it lean.

• Lead with a description that says what and when. It is a trigger, not a summary.
• Write imperative numbered steps. Agents follow a list more reliably than they follow a paragraph.
• Bundle the script or the template instead of describing it in prose.
• Validate before you publish. The reference library will check your frontmatter and naming for you: skills-ref validate ./my-skill.

The mental adjustment that helped me most: you are not prompt-engineering, you are writing onboarding documentation for a colleague who reads very quickly and remembers nothing between sessions.

The registry layer

Once skills became portable folders, somebody was always going to build npm for them. Vercel did, in January 2026, and skills.sh is the one you will run into first. It is a directory with leaderboards: all-time installs, what is trending today, which agents a given skill is compatible with. Installation is a one-liner.

npx skills add <owner/repo>

The directory itself is open source, and the compatibility tags cover a couple of dozen agents. Treating skills as packages rather than as folders you email around is what makes any of this scale to a team, let alone an ecosystem.

Now the caveat, because it matters more than the convenience. A registry is not a quality gate. These catalogues are open, anyone can publish, and a skill is instructions plus executable scripts your agent will run on your machine. That is a real trust surface and a fairly appealing one to attack. Before installing anything from a stranger, read the SKILL.md, open whatever is in scripts/, and treat the install count as weak evidence rather than an endorsement. It is the same caution you would apply to an npm package with a postinstall hook, and for the same reason.

Where a skill ends and a context file begins

The two mechanisms get muddled constantly, so: persistent project knowledge goes in an always-loaded context file, and on-demand procedures go in skills.

The CLAUDE.md in this site’s repository is a decent example of the first kind. It says which npm scripts exist, where blog posts live on disk, that webpack resolves src/ as a module root so imports look unusual, and which SCSS conventions the project follows. All of that is true in every session, so it should be loaded in every session.

A skill answers a narrower question. How do I scaffold a new post. How do I write a commit message here. What does our release checklist look like. Those are only relevant while you are doing that specific thing, and paying for them the rest of the time is waste.

If you find yourself unsure which bucket something belongs in, ask whether an agent would need it to answer “what is this project?“. If yes, context file. If it only helps once you have already decided what to do, skill.

What I’d write first

Pick the one thing you re-explain most often. Not the most impressive workflow, the most repeated one. Write it, use it for a week, and then go back and sharpen the description until the agent reaches for it at the right moments without prompting. That second pass is where most of the value is, and it is the step people skip.

After that, go and look at what other people have published before writing your own version of a changelog generator. The good ones are already there.

The bit I am still unconvinced by is discovery. Leaderboards rank by installs, installs reward whoever published first and tweeted loudest, and there is currently no way to tell a carefully maintained skill from one that was generated in bulk and never opened again. That will need solving, and a star count is not going to be the thing that solves it

‘Till next time!