Skills, Agents and Plugins

011. Skills

What a skill is

Part 3 drew a line between what an agent should always know and what it needs sometimes. The instruction file holds the first. Skills hold the second.

The format is an open one. Anthropic published it as Agent Skills in December 2025, it is maintained at agentskills.io, and dozens of agents and editors from other vendors now read it. A skill is a directory with one required file, SKILL.md. That file opens with a short header giving a name and a description, and the rest is Markdown instructions in whatever form helps.

---
name: cut-release
description: Prepares and tags a release of the billing service. Use when asked to release, ship, tag or publish a version, or to write release notes.
---

# Cutting a release

1. Run scripts/check-clean.sh. Stop if it reports uncommitted changes.
2. Read references/VERSIONING.md to choose the version number.
3. Update CHANGELOG.md from the merged pull requests since the last tag.
   Copy the layout of assets/changelog-entry.md.
4. Open a pull request titled "Release <version>". Do not tag until it is merged.

If the check script fails for any other reason, stop and report. Do not work around it.

Beside it the folder may hold scripts/ for code the agent can run, references/ for longer documents, and assets/ for templates and data.

Loaded in three stages

The design is called progressive disclosure, and it is what lets an agent have a hundred skills without drowning in them.

A script is the extreme case. The agent runs it and reads its output, and the code itself need never enter the context at all.

The description is a prompt

The agent chooses a skill by matching the task against the descriptions, in the same way that part 7 will show it choosing a tool. So the description decides whether the skill is ever used. The specification asks for it to say both what the skill does and when to use it, with the words a person would use when asking. “Helps with PDFs” will rarely be picked. “Extracts text and tables from PDF files, fills PDF forms and merges PDFs. Use when the user mentions PDFs, forms or document extraction” will.

Two failure modes follow. Vague descriptions mean a useful skill is ignored. Overlapping descriptions mean the wrong one is loaded. When a skill “does not work”, check first whether it was loaded at all.

What makes a good one

• One job per skill. A skill called “engineering practices” is an instruction file in the wrong place.
• Steps, examples of input and output, and the edge cases that have bitten before.
• A script for anything that must be done the same way every time. Instructions are interpreted. Code is executed.
• An explicit stopping rule: what to do when a step fails.
• Reference files one level below SKILL.md, each short. The agent loads whole files.

Some harnesses let a skill be marked so that only a person can invoke it, typically with a command such as /cut-release. Use that for anything with side effects, such as deploying or sending messages. The agent should not decide for itself that now is a good time to release.

Skill, instruction file or tool

022. Agent definitions

What the file declares

A definition is Markdown with a short header, kept beside the skills in the same folder the harness reads. It declares:

• A name, which is how it is addressed.
• A description of when to use it, which the main agent matches against the task exactly as it matches a skill’s description. The same warning applies: vague descriptions mean the helper is never chosen.
• A system prompt of its own, which is the whole of its briefing. It does not inherit the conversation.
• The tools it may use, optionally. This is the useful part: a reviewer can be given read-only tools, and a helper that reads untrusted web pages can be given nothing private to leak.
• The model it runs on, optionally. A cheap, fast model for searching, a strong one for deciding.
• Skills to preload, optionally, so it starts knowing a procedure.

Why write one

• Isolation. Work that produces a lot of output nobody will refer to again: searching a codebase, reading logs, surveying documentation.
• Narrower permissions, as above, which is one of the defences in part 9.
• A second opinion. A reviewer that has not read the author’s reasoning is not anchored by it.
• A procedure with a person attached. A definition plus its preloaded skills is a role, written down.

Skill or agent definition

The two are often confused, because both are a Markdown file with a name and a description. They solve opposite problems. A skill brings knowledge into the current context. An agent definition creates somewhere to send work so that it stays out of the current context. They combine: a definition can preload skills, and a skill can say its steps should run in a helper.

033. Plugins, and what you are installing

What is in the box

The details here are Claude Code’s, and other harnesses have equivalents. A plugin is a directory with a small manifest and any of the following:

• skills
• sub-agent definitions
• hooks, which are scripts the harness runs at fixed points such as before a tool call or after an edit
• configuration for MCP servers and language servers
• executables added to the agent’s path

A marketplace is a catalogue, usually a Git repository, listing plugins and where to fetch them. A team can host a private one, and a repository’s settings can name the plugins its contributors should have. A plugin’s skills are prefixed with its name, so two plugins can both have a review skill without colliding.

The test for whether you need one is simple. Start with loose files in one project. Make a plugin when a second repository needs the same setup.

Hooks are the enforcing part

Hooks deserve a note of their own because they are different in kind from everything else in this part. A skill is text the model interprets. A hook is code the harness runs, every time, whatever the model thinks. A hook that runs the formatter after every edit always runs. A hook that refuses any command touching the production configuration always refuses.

This is the mechanism part 3 pointed to when it said an instruction is a request and not a guarantee. If a rule must hold, put it in a hook.

A supply chain

Skills and plugins are distributed through open catalogues, mostly without mandatory review. Research through 2026 has been consistent about the risk.

• A skill’s text is operational, not passive. One study of a public skill registry found that wording in SKILL.md alone could push a malicious skill up the search results, get it chosen over an honest equivalent in about three-quarters of paired trials, and slip past the registry’s own screening in a third or more of attempts.
• Harm need not look like an instruction. Another study hid malicious steps inside the code examples and configuration templates in a skill’s documentation. Agents copied them during normal work. Attacks written as explicit instructions were blocked every time under strong defences, and the disguised ones got through in roughly one run in eight to one run in three, depending on the agent and model.
• A script in a skill, a hook, or an executable in a plugin is ordinary code running with your privileges. No model has to be fooled.

The response is the one used for any dependency, with one addition.

• Install from sources you would accept code from. Prefer a private marketplace with reviewed contents.
• Read what you install. A skill is short, and that is the point of the format.
• Pin versions, and review updates as changes to code.
• Assume a skill can do whatever the agent can do, and limit the agent accordingly. Part 9 covers how.
• The addition: read the prose as carefully as the scripts. In this supply chain, a paragraph is executable.

The whiteboard version

The model is the engine. The harness is the vehicle. Instruction files are what the driver always knows, skills are the manuals in the glovebox, sub-agents are colleagues sent on errands, and plugins are how a whole fleet gets the same kit. Hooks are the only part that works like a brake.