Lesson9 min

Skills: procedures an agent loads on demand

What always applies is in the rules file. What is needed only sometimes belongs in a skill: a set of instructions the agent loads only when the task fits. How to write one – and why you read other people's before using them.

Boaz Lichtenstein

Part of the path Running agentsstation 2 of 7level 3 Expert

The path Knowledge & context contained the rule: the rules file stays short because every line is read in every session. But where do you put the refund procedure that takes forty lines and comes up in only one task out of twenty?

In a skill.

What a skill is

A skill is a folder with instructions – a file called SKILL.md is the usual form – and, where needed, further files: templates, examples, small scripts.

refund/
  SKILL.md           instructions with name and short description
  reply-template.md
  check-receipt.py

The trick is in the loading. On start the agent reads just two lines of each skill: name and short description. Only when a task fits does it load the full instructions. Twenty skills thus cost hardly any context – twenty procedures in the rules file would burst it.

Where?	What?	Loaded
Rules file	what always applies	every session
Skill	procedures for particular tasks	on demand
Knowledge notes	facts, statuses, decisions	when asked

A good skill has four parts

1. The short description – as a trigger. It answers: for which tasks should the agent load this skill?

name: refund
description: Use when a customer wants money back, reports a
  return or asks about the status of a refund.

“Helps with customer matters” would be too vague ever to be triggered.

2. The steps. Numbered, in order of execution, with a reason where a step is not obvious.

3. The check. How does the agent recognise that it is done – and that it has to stop and ask?

4. Scripts for everything that has to be exact. Calculating, checking formats, converting files: a script does that more reliably than a model. The skill tells the agent when to call it.

When an explanation becomes a skill

The rule of thumb: when you explain the same procedure for the third time. The first time you do not yet know whether it will recur. The second time you suspect it. The third time you write it down – ideally straight after a successful run: “Record how we just did that, as a skill.”

Some agents create skills themselves this way. That is useful and needs the same control as everything else an agent writes: read the skill before it is used the next time.

Third-party skills are third-party code

Skills can be shared and installed from directories. That is convenient – and a supply chain. A skill can:

have commands run, through bundled scripts
contain instructions your agent follows because it takes them for its own
send data outside, for instance through an innocently named step “upload result”

Before installing, therefore:

Read everything – the instructions and every script.
Check the origin. Who wrote it, who maintains it?
Test first in an environment with no access to real data.
Pin the version. A skill that updates silently is a different one tomorrow from the one you read.

You know the attack pattern behind this from Prompt injection – except that here you install the foreign instructions yourself.

Skills belong under version control

A skill is a piece of operational knowledge. Put it in the repository, route changes through pull requests – and measure them. The test set from the previous station tells you whether a skill improves the results: once with, once without, the same cases.

Not every skill passes that test. Some merely make the agent slower because it reads instructions it did not need. Those go again.