Skills: your company's unwritten rules, written down for an agent

Most of what makes a company run is not written anywhere. It is the colleague who knows the rate card changed in March, the one who knows which of the three spreadsheets is the real one, and the one who knows a quote goes past the account lead before it goes to the customer. A model has read an enormous amount. It has not read your rate card, and nobody is going to publish it.

Give an agent a job at your company and you meet this on day one. It writes a plausible quote, a clean summary, a reasonable memo. Plausible is not the standard. The standard is the way the job is done here, and that standard lives in people.

A skill is how the standard gets written down in a form an agent reads and follows. What follows is what we tell the teams we embed with: the anatomy of a skill, what belongs in one and what does not, how the first few get written, and the part most rollouts skip: keeping them true after the company moves on.

The shape of a skill

On disk, a skill is nothing more than a folder of plain files. At its centre is one instruction file in ordinary language, with a short header: a name, and a line on when to use it. Around it sit the materials the job needs: a template, a rate table, a finished example, sometimes a script for a step that is pure arithmetic.

An agent with forty skills installed is not carrying forty procedures around in its head. What it holds at the start of a conversation is the index: the name of every skill and that one line, nothing else. The procedure is loaded only when a request fits the line, and the attached files are opened by the tools that need them rather than read into the conversation. Until something matches, a skill costs the agent the two lines of its header.

Think of the description as the label on a drawer in the workshop. The drawer stays shut until the job calls for what is inside.

For a construction company that handles a lot of change orders, the folder might look like this:

change-order-memo/
  SKILL.md              the instructions: steps, rules, hand-offs
  templates/
    co-memo.docx        the memo as the client receives it
  reference/
    rates-2026.csv      the current schedule of rates
    example-good.md     a finished memo the PM signed off
    example-bad.md      a memo that was sent back, with notes on why

And the instruction file itself, shortened:

---
name: change-order-memo
description: Draft a change-order memo for an active job from the
  superintendent's site notes, the original scope and the rate
  schedule. Use when someone asks for a change order, a CO, or a
  scope-change write-up.
---

# Change-order memo

## Inputs
- Site notes from the superintendent. If they are missing, ask.
  Do not reconstruct them from the schedule.
- The original scope document for the job.
- reference/rates-2026.csv for every priced line.

## Steps
1. List only the work that falls outside the original scope.
2. Price each line from the rate schedule. Never estimate a rate.
3. State schedule impact as "to be confirmed" until the
   superintendent has signed off on it.
4. Fill templates/co-memo.docx. Keep the summary under 120 words.

## Rules
- Residential jobs: the client signs before any work starts.
- Commercial jobs: the memo goes to the project manager first,
  then to the client.
- Do not cite earlier change orders on the same job unless asked.

No developer touched that file, and none needs to. The project manager who runs change orders wrote it, the way they would brief a new estimator: what to gather, what to do with it, the two rules that trip people up. The agent opens it when a change order comes in and works from it. The knowledge stays with the person who has it; the file is how the agent borrows it.

Access and judgement are different things

Teams often reach for a connector when they need a skill, or the reverse, so it is worth being precise about what each one adds.

A prompt is an instruction for this conversation. Right for work that happens once, wrong for anything that repeats, because it leaves with the chat.
A connector (an MCP server, an API integration) lets the agent reach a system: look up a customer, raise a ticket, fetch last month’s invoices. It grants access. It says nothing about what a finished piece of work should look like.
A skill supplies the judgement: what the output must contain, in what order, who sees it first, and which exceptions apply. It loads only when the job comes up.

An agent that is any use in production usually has both of the last two. The connector gets the agent into the order system; the skill tells it that back-orders are reported separately and that anything over the credit limit is flagged, not fulfilled. Fine-tuning a model is a fourth option, and for company procedure it is almost never the right one. Procedures change. A tuned model does not change with them.

What belongs in the file

The happy path is the least valuable part of a skill. The agent can usually work out the obvious sequence on its own. What it cannot work out is the part nobody wrote down because everyone who matters already knows it, usually from the time it went wrong.

Put these in:

The definition of done. What the finished piece looks like, with a real example attached. One good example is worth a page of description.
The exceptions. The customers on legacy pricing. The month-end cut-off. The one product line quoted in a different unit. Each is a sentence; together they are the job.
The hand-offs. Who reviews, in what order, and what the agent must never send on its own.
Where the truth lives. Which file, table or system wins when two disagree.
When to stop and ask. The conditions under which a person decides, and the question the agent should ask.

Leave these out:

Anything that changes often. Put the rate card in a referenced file, or behind a connector, and point the skill at it. A number typed into the instruction text will be wrong by spring.
Credentials and keys. Those belong to the runtime, never to a folder that gets shared.
General knowledge. The model knows what a change order is. It does not know yours.
Policy prose nobody enforces. If the people who do the job ignore a rule, an agent that follows it will not match their output.

Write steps as decisions, not narration. “Check the credit limit; if it is exceeded, stop and flag” is an instruction. “We place great emphasis on credit control” is not.

Writing the first few

When we embed with a company, the first skills it needs are rarely the ambitious ones. They are the jobs that come round every week, have an output everyone agrees is right, and cost little when they go wrong: the weekly inventory note, the intake summary, the quote, the status update to a client. Start there.

Choose by frequency and by the cost of a mistake. Something that happens every Friday beats something that happens every December. A draft a person reviews beats a message that goes straight out.
Shadow the job once, start to finish. Managers describe the process; the person doing it knows the exceptions. Note what they check, what they skip, and what they look up. The look-ups become your reference files; the checks become your rules.
Write the description the way the request arrives. The agent matches on that one line and nothing else. If the site team says “CO” and “scope-change write-up”, those words go in; “variation documentation workflow” does not.
Write the procedure for a capable stranger. Short numbered steps, each rule stated as a rule, every exception from step two. If it cannot be followed without a diagram, it is two skills.
Put the real documents in the folder. The memo template itself, this year’s rate table, one memo that went out. An agent working from a summary of the template produces a summary of a memo.
Replay the last month. Take the real cases from the last few weeks, give the agent the same inputs they started from, and set its output beside what actually went out. Each difference is a rule the file is missing, or a rule the person who does the job has not said out loud. Fix the file. Correcting the output by hand and moving on teaches the agent nothing.
Give it an owner and a review date. A skill nobody owns is a document nobody updates.

A simple job takes a day, shadowing included; one with many exceptions takes a week. Each skill after the first goes faster, because the people writing them learn what an agent needs to be told.

Keeping skills true

This is the part the product demos leave out. A skill describes how the company works today. Companies change: the rate schedule is reissued, a sign-off is added, a product is renamed, the person who wrote the skill moves on. If the file does not change with the company, the agent keeps doing last year’s job, confidently.

A procedures binder and a skill go wrong in different ways. The binder drifts quietly, and nobody notices until an audit, or until a new hire asks why. A skill is executed every week, so when it is wrong, something wrong gets produced this week, in front of a customer if nobody sits in between. That is a real advantage, but only if someone is looking at the output with the file in mind. So build the looking in.

Keep skills in version control and review changes like code. Every edit is a diff with a name on it. When the process changes, the skill change goes in the same ticket as the process change, not in a follow-up that never arrives.
Keep a small set of reference cases. Three to five real inputs and the output the job’s owner accepted. Re-run them after every edit to the skill and after every model upgrade; a skill tuned to the last model may need a sentence for the next.
Log every trigger. Which skill fired, on what request, and what came out. A monthly skim of that log is the cheapest audit you will run, and it shows which skills nobody uses. Retire those; dead skills make the live ones harder to trigger.
Put a review date in the header and honour it. Quarterly is enough for most; a reissued rate card, form or regulation is a reason to review early.
Watch for overlap. Two skills with similar descriptions compete, and the agent will pick between them inconsistently. Merge them, or sharpen the descriptions until they do not.
Treat anything from outside as a dependency. The same folder that carries instructions can carry executable scripts, and the agent runs what it is given. Before a skill from outside the company goes anywhere near production, somebody reads it end to end, scripts included, and pins the version they read. It is plain text, so that is a ten-minute job, and it is the same gate a package from a registry already goes through. Keep the ones that passed in a library of your own and install from there.

The file format is an open specification rather than one vendor’s feature, and that matters over years rather than weeks: a library written against it does not need rewriting when you change models or tools, and it lives as plain files in a repository you control. The procedures stay yours.

A fair test before you ship one

Read the instruction file as if it were the handover note for a colleague covering the job while its owner is away. Would they produce the right thing? Would they know when to stop and ask? If not, the agent will not either.

None of this is new knowledge. The company already has all of it, spread across a few heads, a few inboxes and the spreadsheet that is really the real one. A skill is where that knowledge goes so that the company owns it, and not only the person. Keeping the file honest is the job that comes after.

← Back to articles