Agent Skills

2026-08-27T00:00:00+12:00

Agent skills let humans organize, distribute, discover, and compose an agent’s capabilities. A skill is typically a markdown file, with optional scripts, references, and evals bundled alongside it.

Think of an agent skill as programming in natural language, written in markdown. It can hold knowledge, workflow logic, guardrails, required tools — basically anything.

Some outstanding skills:

autoresearch instructs an agent to tirelessly tune models. It defines a workflow — really a loop — and states plainly what the agent can edit and what it can’t.
img2threejs turns an image into a 3D model. It defines a workflow with heavy guardrails at every stage.
superpowers defines a software development lifecycle. It has an opinionated, mandatory way to deliver software.

You probably already do some of this by hand. Just write it down, name the file SKILL.md, and let the agent pick it up. It’s that simple.

Life cycle

A skill moves through six stages: Discovered, Selected, Loaded, Executed, Unloaded, Self-Improved.

Discovered — the harness reads the skill’s name and description at startup.
Selected — the model decides a task matches the skill.
Loaded — the harness loads the full SKILL.md into context.
Executed — the model follows the instructions and calls whatever tools the skill needs.
Unloaded — the task is done, and the skill drops back out of context. This may not be implemented in all AI agents.
Self-improved — the agent rewrites its own skill from experience, instead of waiting for a human to update the file. This often shows up in auto-enhancing agents like Open Claw and Hermes.

Case study: Pi

Pi calls this progressive disclosure. At startup it scans every skill directory but only puts each skill’s name and description into the system prompt. If the model decides a skill is relevant, it uses the normal read tool to load that skill’s SKILL.md, then follows the instructions and invokes whatever existing tools or scripts are appropriate.

Pi’s own docs admit the model doesn’t always make that call on its own — sometimes you have to prompt it, or name the skill directly, to force the read.

Case study: Hermes

Hermes uses a similar progressive disclosure idea, but makes skill discovery more explicit. Instead of relying on the model to notice a skill description in the system prompt and then read its file, Hermes exposes skills through dedicated tools: skills_list() gives the agent a compact index of installed skills, skill_view(name) loads the full SKILL.md, and skill_view(name, path) can pull in individual reference files. The full procedure only enters context when the agent decides it needs it, keeping the initial prompt relatively small.

Hermes also gives the user a stronger escape hatch when automatic routing fails. Every installed skill becomes a slash command — /plan, /github-pr-workflow, and so on — which directly loads that skill instead of hoping the model selects it from natural language. You can still say “use the X skill” conversationally, but Hermes treats explicit skill invocation as a first-class interaction rather than a workaround.

Write practical skills

KISS. eli5 is a good example — ten lines, and it works.
Do one thing and do it well.
Write a worklog. Like in the superpowers skill, have the agent write an exec plan before doing any work.
Keep the loop simple. Don’t over-engineer the control flow — the LLM handles that quite well on its own. Just give it enough knowledge so it can get things done.
Ask for input. The skill can tell the agent to ask the user for clarification.
Be robust. The skill should describe how to deal with errors — if it can’t recover, should it stop, or escalate to a human?
Write a structured description. Name, capabilities, required tools, input/output schema.
Use Git for version control.
Explicitly state dependencies. Whether it’s a system tool, a library, an API key, an MCP server, or even another skill.
Come with an evals/evals.json. So you can tell whether a change to the skill made it better or worse.

Extra guides for scripts

Make the script standalone. If it has dependencies, run it through tools like uvx or npx, so skill users don’t need to set up an environment.
Provide options and arguments, and avoid interactive prompts.

Should I fine-tune or just write a SKILL.md?

A skill is instant. It doesn’t involve costly training, and you can swap it on the fly — you can even ask the agent to re-read the skill to pick up a change mid-run. Maintenance is cheap; there’s no “retrain” step.

It also has great flexibility. Same model, same agent loop, different skills loaded — and you get different results. That’s great for user customization.

The downside is context window. Skills consume it, and if you have a lot of large skills, they can overfill it.

Usually, when you need instruction following, tool call format, or RL reasoning baked in, fine-tuning is the better choice. A skill is a runtime add-on for executing tasks.

Ju Lin's AI Weblog: Fine-Tuning