Home/Methods

AI · Agent skills

How we turn repeated work into AI agent skills

An agent skill is a folder with a SKILL.md file that tells an AI coding agent when and how to do one recurring job, plus any script the job needs. We extend an existing skill before creating a new one, make every write a dry run by default, and keep the rules that must hold outside the prompt: in hooks, read-only database roles and a shared knowledge base.

Updated 2026-10-11

What an agent skill is

An AI agent skill is a folder containing a SKILL.md file: a short frontmatter block with a name and a description, followed by instructions that an AI coding agent such as Claude Code follows for one recurring job. If the job needs deterministic work, such as a database query or an API call, the folder also holds the script that does it. The agent reads the description to decide when the skill applies, so the description does the routing.

We keep a shared team catalogue of skills, so a skill written by one person is available to every agent on every machine. The catalogue grew to about 230 skills before a consolidation pass brought it down to about 216. That number is not a target. A skill catalogue is useful in proportion to how reliably the right skill is found, and every near-duplicate makes that harder.

Our trigger for writing a skill is repetition. A pattern seen in three or more cases, or a fix we would otherwise redo by hand tomorrow, becomes a skill or a rule in code. A one-off case stays on a list for a person, with the decision that person has to make.

Step 1: extend before you create

The first step in making an agent skill is to check whether one already exists. We match the proposed name and description against the catalogue and look at the closest skills. When the data and the audience overlap, we add a mode or a subcommand to the existing skill instead of creating a new one. Four separate article generators, one per site, became one generator with a site parameter. Several advertising sub-skills became one suite.

The same rule applies inside the code. An audit of the catalogue found one small connection-string helper copied into about 40 files, each copy free to drift on its own. Skills now import one shared helper for database connections and secrets, and read precomputed tables instead of recomputing heavy aggregates on every run.

Step 2: write SKILL.md for the router

The SKILL.md frontmatter needs two fields, a name and a description, with an optional argument hint. The description says what the skill does, then when to use it, then the phrases a user would actually type. The body follows a fixed shape: when to use, the exact steps, and notes with edge cases, data sources and related skills.

We prefer a knowledge skill, meaning instructions only, unless the job must run code deterministically. Instructions are cheap to change. A script is a second thing to test, deploy and keep in step with the text.

Where the catalogue lives matters too. We used to list every skill, with its description, in the instructions that load on every turn. That file had reached 30.8 KB. Routing actually happens through a semantic search over the full descriptions, which stay in the database, so the always-loaded list was shortened to descriptions of at most 10 words: 17.4 KB, 44% smaller, for every agent on every turn.

Step 3: scripts that run anywhere and write nothing by default

A skill script declares its dependencies inline, in the format defined by PEP 723, and runs with uv run. No virtual environment is committed, so the same script runs on any machine that has uv. Secrets are read from the environment first and from a shared secret store second, and are never printed. Scripts that print to Windows consoles force UTF-8 output, because Romanian diacritics otherwise crash them.

Every write is a dry run by default. The script prints what it would change, with the matching SELECT and the row counts, and changes nothing until it is called again with --apply. When a skill is exposed as a runnable action, it comes as a pair: a preview action that is allowed and an apply action that asks for confirmation. Runnable actions accept only whitelisted parameters, never free SQL or a file path.

Step 4: put the hard rules outside the prompt

A rule an AI agent must not break belongs in a mechanism, not in a sentence. An agent's context is its prompt. We once told a person that an agent would not copy material from a published database, then wrote the agent's prompt without that prohibition. The agent did exactly that, efficiently. A rule stated anywhere other than the agent's instructions does not exist for the agent.

So the hard rules live in three places. Database access goes through MCP servers (Model Context Protocol, the interface through which the agent calls tools) that run every query inside a READ ONLY transaction. A PreToolUse hook, a script the agent runtime calls before each tool use, blocks catastrophic commands outright and asks for confirmation before destructive SQL or a git push; the team can add patterns that apply to everyone from the next session. A second pair of hooks logs skill and database usage to the shared knowledge base after every turn, so the activity record does not depend on anyone remembering.

A guard that matches command text is blunt. Ours refused a harmless search that merely contained the name of a database dump utility. We treat that as deliberate and read the schema from information_schema instead of arguing with the guard.

Step 5: memory the next agent can reason with

The shared knowledge base holds what every agent needs: secrets, which live nowhere else, the activity log, a register of files, reference links and the skill register. Personal memory is a folder of small Markdown files, one fact per file, each with a rule, a Why: line and a How to apply: line. The Why line lets a later agent judge an edge case instead of applying the rule blindly. An index lists one line per note, because the index is read with a size limit of about 17 KB.

Reusable lessons move from personal memory to the team store, after a search for an existing version. A fact that changes is marked stale, not deleted. Links between notes go through a gate: in our test, linking on embedding similarity alone scored 24.9% F1 against 23.9% for random links, and 31.6% with a gate that approves only specific relations.

Consolidation audits: contradictions first

A skill consolidation audit fans out read-only agents, one per cluster of skills, and asks each for overlaps and, explicitly, for contradictions. Contradictions are fixed first, because they produce wrong numbers. We found breakeven ROAS defined as 1 / margin in one skill and 1 / (margin × delivery rate) in another for cash-on-delivery stores, a creative-fatigue threshold of 10% in one place and 20% in another, and four definitions of cost of goods.

Pure duplicates are deleted after their references are repointed. Several script-backed skills are merged into one skill with a thin dispatcher, without rewriting the tested scripts, and each mode is tested on real data before the originals go. A skill with a unique script is never deleted. A deletion has to reach three stores: the repository, the catalogue database and the skill server. The skill server has no delete, so the old name is republished as a tombstone pointing to its replacement.

Where we were wrong

The hooks were off. On one machine a settings flag disabled all hooks, so the guardrail and the logging our instructions described as guaranteed never ran. We re-enabled them after checking the guard: a harmless echo passed and a recursive delete of the root was denied. The documentation also says a PreToolUse deny is ignored in bypass-permissions mode. We have not verified that ourselves, so for unattended agents the defence is at the operating-system level.

The errors were not broken skills. Of 182 recorded skill errors, 91 came from one lookup that reported a 404 as a failure, when not found was the answer. The most common cause of an apparent outage was an optional secret declared as required: 57 such cases in 32 skills, with 31 removed from 15 manifests. The server also returned a bare 500 for calling mistakes; it now returns 400, 403 or 503 with the reason, verified on 5 paths. A static manifest audit found 104 mismatches in 37 skills, some of them false positives, because the audit does not understand subcommands.

Fixes that never ran. Code that never executes looks identical to code that runs and finds nothing. Before changing a rule we now ask for two numbers: how many times it ran, and on how many cases it produced a result. One address rule resolved 0 of 2,258 rejected orders before a one-character fix and 47 after.

Limits and checklist

None of this makes an agent correct. Skills make good practice repeatable, and they make mistakes repeatable too. A dry run shows what would change, not whether it should. Hooks protect only the machines where they run, and only in the modes that honour them.

Checklist. Search the catalogue and extend where you can. Write a description with real trigger phrases. Declare dependencies inline and run with uv. Dry run by default, apply on request. Read-only database access. Hard rules in hooks, not in prose. A Why line on every memory note. After publishing, compare the scripts SKILL.md mentions with the files actually committed. Audit for contradictions before duplicates.

Questions and answers

What is a SKILL.md file in Claude Code?

A SKILL.md file is the core of an agent skill. It starts with frontmatter containing a name and a description, followed by instructions for one recurring job. The agent reads the description to decide when the skill applies, so the description should state what the skill does, when to use it and the phrases a user would actually type. Scripts the job needs sit in the same folder.

When should I create a new agent skill instead of extending one?

Create a new agent skill only when no existing skill covers the same data and the same audience. Search the catalogue by name and description first. If a close match exists, add a mode or subcommand to it. We write a skill when a pattern repeats in three or more cases; a one-off case stays on a list for a person.

How do I stop an AI agent from running destructive commands?

Put the rule in a mechanism rather than the prompt. A PreToolUse hook can block catastrophic commands and ask for confirmation before destructive SQL or a git push. Database tools can run every query in a read-only transaction. Check that hooks are actually enabled on each machine, and do not rely on them for unattended agents in bypass mode.

How should AI agent skill scripts handle dependencies?

Declare dependencies inline using the PEP 723 format and run the script with uv run, so no virtual environment needs to be committed and the script runs on any machine with uv. Read secrets from the environment, never print them, and force UTF-8 output if the script may run in a Windows console.

What is a skill consolidation audit?

A skill consolidation audit reviews a skill catalogue for overlaps and contradictions, usually with one read-only agent per cluster of skills. Contradictions are fixed first, because two skills that define the same metric differently produce wrong numbers. Then pure duplicates are deleted and related script-backed skills are merged behind a thin dispatcher, testing every mode on real data before removing the originals.

All methods