Skip to content
Fredrin
Download

Agent skills

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.

What a skill actually is

One folder, one required file. The frontmatter is the part the agent sees before it has decided anything; the body is the part it reads once it has. Nothing here is a framework — it is a Markdown file on disk, which is the whole reason the format travels.

---
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 needs but does not always need sits beside it in the same folder, and the body names it. A reference file is read only if the agent is pointed at it; a script is run rather than read, so its contents never enter the context window at all.

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 window

Progressive disclosure: three tiers, loaded late

A model's context window is a budget, and everything in it competes with the code the agent is supposed to be reading. Skills exist to keep specialised procedure out of that budget until the moment it earns its place. Three tiers load at three different times:

Name and description
Tens of tokens each
Every session, for every installed skill
The SKILL.md body
Hundreds to a few thousand tokens, once
When the agent judges the description matches the task in front of it
Bundled files and scripts
Nothing until it is opened
When the body points at one — often never

That is why the honest answer to “how many can I install” is “more than you will write”. The cost of an unused skill is one sentence of description. The cost of the same knowledge pasted into a system prompt is paid on every request, forever, including the thousand requests it has nothing to do with — the difference context engineering is mostly about.

What agent skills are not

Four neighbouring ideas get used interchangeably, and the differences are practical rather than academic — they decide where a given instruction should live.

A system prompt

In context for every request, whether or not it is relevant

SkillIn context only for the requests it applies to

An MCP server

Gives the agent new tools — connections to systems it could not otherwise reach

SkillGives 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

SkillChanges 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

SkillOn-demand procedure for a kind of task, portable across repositories

The last row is the one that trips teams up in practice. If the instruction is true of the whole repository, it belongs in an agents file that every session reads. If it is true of a kind of task, it belongs in a skill. Putting task procedure in the agents file is how that file grows to four hundred lines nobody reads.

Seven rules for writing one that fires

Skills fail in a specific way: they sit installed and never load, and because nothing errors, the author concludes the model ignored them. Almost always it never saw them.

  1. 01

    The description is the trigger, not the documentation

    It 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.

  2. 02

    One job per skill

    A 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.

  3. 03

    Write procedure, not prose

    Numbered 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.

  4. 04

    Push reference material into separate files

    Anything 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.

  5. 05

    Prefer a script for anything deterministic

    If 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.

  6. 06

    Say 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.

  7. 07

    Test the trigger, not just the content

    Ask 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

Three scopes, and the only question that separates them is who the skill travels with.

Personal
Your own machine
Skills you wrote for how you work. They follow you to every project and no teammate sees them — which is fine until the procedure is one the team is supposed to share.
Project
Committed to the repository
Skills that describe this codebase's procedures — how it deploys, how it writes migrations, what a review must check. They arrive with a clone, are reviewed like code, and version with the thing they describe.
Packs
A git repo of skill folders, installed once
Maintained sets — a team's house rules, or a published pack — installed in one step and available in every session. This is the shape that makes a skill a dependency, with everything that implies.

The third scope is the one that deserves a policy. An installed pack is instructions handed to something holding a shell and write access to your repository, and it can change under you between one session and the next. Pin to a commit rather than a branch, read the diff when it moves, and treat the author — not the file — as the unit of trust. There is no filtering that makes an arbitrary instruction safe.

What changes when twenty agents run at once

Everything above assumes one agent, one session, one person watching. Run a board of them in parallel and three of these choices change shape.

Triggering stops being good enough. A skill that loads because the model recognised the moment is fine when you are reading every turn. Across a dozen unattended runs you want the ones that matter to be selected, not matched — attached to the work up front, so it is a decision rather than a coin flip.

Precedence has to be written down. When an installed pack and the repository's own conventions disagree, something must win by rule. In Fredrin the project's context and the ticket outrank skill instructions, and the agent is told so in the same breath it is handed the skills.

Distribution becomes an install problem. Skills that live in one machine's home directory do not exist for the agent running on another. Fredrin ships its own as a session-scoped plugin and carries them to paired machines inside the agent bundle, so what a Worker can do does not depend on which box picked up the ticket.

None of that makes a skill a substitute for a well-specified task. If the work is not defined well enough for a human to review the result, a skill only makes the wrong outcome arrive more consistently — and for something you will do once, a sentence in the prompt beats a folder. Fredrin is the agentic development environment for the case where that is not the problem: a backlog, a branch and worktree per ticket, and a board to review what comes back.

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.

Or put the skills you just wrote in front of a whole board of agents.

Request inviteRead the docs