Name and description.
Every session, for every installed skill. Tens of tokens each.
Agent skills.
How they work, and how to write one that fires.
What a skill actually is.
Agent skills are folders of instructions an AI agent loads only when a task calls for them. Each one is a SKILL.md file (YAML frontmatter naming the skill and describing when to use it, then plain Markdown telling the agent how), optionally sitting beside scripts and reference files. The agent reads only the descriptions at startup, and the body of a skill the moment it decides that skill applies.
---
name: cut-a-release
description: Cut a tagged release of this repo. Use when asked to ship a release, publish a version, or tag a build.
---
# Cut a release
1. Confirm CI is green on main. If it is not, stop and say why.
2. Run the build. Abort on any error. Never publish from a red build.
3. Bump the version in package.json and commit it as "chore: release vX.Y.Z".
4. Tag that commit and push the tag. The pipeline publishes from tags, not from main.
Never publish from a dirty working tree. Read reference/versioning.md before
choosing the version number.Anything the procedure sometimes needs sits beside it. A reference file is read only when the body points at it; a script is run, not read, so it never enters the context window.
cut-a-release/
SKILL.md # required: the only file that must exist
reference/
versioning.md # read only if SKILL.md points the agent at it
scripts/
verify-tag.sh # executed, not read into the context windowProgressive disclosure. Three tiers, loaded late.
The SKILL.md body.
When the agent judges the description matches the task in front of it. Hundreds to a few thousand tokens, once.
Bundled files and scripts.
When the body points at one, often never. Nothing until it is opened.
Context is a budget. An unused skill costs one sentence of description; the same knowledge in a system prompt is paid on every request, which is what context engineering is mostly about.
What agent skills are not. Four neighbouring ideas, and where an instruction should live.
A system prompt.
In context for every request, whether or not it is relevant. A skill instead is in context only for the requests it applies to.
An MCP server.
Gives the agent new tools: connections to systems it could not otherwise reach. A skill instead gives the agent procedure: how to use the tools it already has.
Fine-tuning.
Changes the model's weights; needs data, a training run, and an evaluation. A skill instead changes what is in front of the model; edit the file and the next run has it.
An agents file (AGENTS.md).
Always-on context about this repository: its commands, conventions, architecture. A skill instead is on-demand procedure for a kind of task, portable across repositories.
True of the whole repository? It belongs in an agents file. True of a kind of task? It belongs in a skill.
Seven rules for writing one that fires.
Skills fail silently: they sit installed and never load. Almost always the model never saw them.
- 01The description is the trigger, not the documentationIt is the only part the model reads before deciding. Write the conditions in the words a user would actually type (“when asked to ship a release, publish a version, or tag a build”), not a summary of the body. A perfect skill with a vague description never fires, and nothing tells you it didn't.
- 02One job per skillA skill that covers releases, migrations and incident response has a description that matches everything, which means it matches nothing usefully. Split it. Skills compose in one session, so several small ones beat one large one.
- 03Write procedure, not proseNumbered steps, explicit commands, named files. The body is read by something that will do exactly what it says, so “consider validating the input” is worse than useless: it is a step that will be skipped.
- 04Push reference material into separate filesAnything long, tabular, or rarely needed goes in its own file that the body points at by name. That is what keeps the loaded cost of a skill small even when the material behind it is large.
- 05Prefer a script for anything deterministicIf a step is the same every time, ship it as a script the skill runs. A model re-deriving fixed logic each run is slower, costlier, and occasionally creative about it.
- 06Say what to do when it fails“Stop and report why” is a real instruction and the most commonly missing one. Without it, an agent that hits a red build will improvise a way past it.
- 07Test the trigger, not just the contentAsk for the task in three different phrasings and check the skill loads for all three. Most skill bugs are matching bugs, and they are invisible from reading the file.
Where skills come from. Two scopes, separated by who the skill travels with.
Personal.
Your own machine. They follow you to every project, and no teammate sees them.
Project.
Committed to the repository. They arrive with a clone, are reviewed like code, and version with the thing they describe.
What changes when twenty agents run at once.
Triggering stops being good enough.
Across a dozen unattended runs, the skills that matter should be attached to the work up front, not matched by chance.
Precedence has to be written down.
In Fredrin the project's context and the ticket outrank skill instructions, and the agent is told so.
Distribution becomes an install problem.
Fredrin ships its skills as a session-scoped plugin and carries them to paired machines.
Fredrin is the agentic development environment for running them: a branch and worktree per ticket, and a board to review what comes back. In a software factory, skills are the tooling installed once instead of retyped for every unit: see the stations of a software factory.
Questions.
What is an agent skill?
A folder containing a SKILL.md file: YAML frontmatter with a name and a description of when to use it, then Markdown instructions for how. The agent keeps only the descriptions loaded and reads a skill's body when it decides that skill fits the task, so installed skills cost almost nothing until one is needed.
How are agent skills different from MCP servers?
MCP gives an agent new capabilities: a connection to your ticket tracker, your database, your cloud. A skill gives it procedure: which of the tools it already has to reach for, in what order, and what counts as done. They compose rather than compete, and a well-written skill often exists to tell an agent how to use an MCP tool properly.
Do I need to write code to create a skill?
No. The minimum viable skill is a folder with one Markdown file in it. Scripts are an optimisation for steps that are the same every time, not a requirement. Plenty of useful skills are twenty lines of numbered instructions and nothing else.
How many skills can I install before they eat the context window?
More than you will write. Only each skill's name and description are loaded up front (on the order of tens of tokens each), so dozens of installed skills cost a rounding error until one is triggered. Whole bodies are read on demand, one at a time.
Are agent skills safe to install from someone else?
Treat it exactly like adding a dependency, because that is what it is. A skill is instructions handed to an agent that holds shell access and write access to your repository, and no amount of reading the file guarantees the next version says the same thing. Install from authors you would take a package from, pin to a commit rather than a moving branch, and read the diff when it updates.
Do agent skills work outside Claude?
The file format is portable: a SKILL.md is plain Markdown with YAML frontmatter, with nothing vendor-specific in it, and Anthropic published it as an open format in October 2025. What varies is the runtime: whether a given agent discovers skill folders, preloads descriptions, and loads bodies on demand is that tool's implementation, so check before assuming a skill you wrote will fire elsewhere.
When should I not write a skill?
When you are doing the task once, say it in the prompt. When the instruction applies to everything in the repository, that belongs in an agents file. And when the task is not specified well enough for a person to review the result, a skill will only make the wrong outcome more consistent.