AI Agent Skills: Teaching an AI Employee One Job Properly

An AI agent skill is a packaged, reusable capability (instructions plus optional scripts and reference files) that teaches an agent to do one specific job the way your company does it, repeatably. It is not a tool (a thing the agent can do, like call an API) and it is not a one-off prompt you retype each time. A skill is the knowledge and procedure for a task, written down once, versioned, and pulled into the agent's context only when a task actually needs it. That single move is what turns a clever prompt into a reliable, repeatable procedure an AI employee can run a hundred times the same way.

I run my own agency on this. We operate roughly nine AI agents across our own work, and the difference between an agent that quietly rots and one that stays dependable usually comes down to whether its jobs live in skills or are stuffed into one enormous prompt. Below is what a skill actually is, how it differs from tools and prompts, and a worked example from how we run reporting at Brixon.

What is an AI agent skill?

A skill is a self-contained package, typically a markdown file with small scripts and reference documents alongside it, that describes how to perform one specific job and that an agent loads on demand. Think of it the way you'd think about an SOP you hand a new hire: not "be smart," but "here is exactly how we produce the monthly client report, in this order, with these rules."

The key property is progressive disclosure. The agent doesn't hold every procedure in its head at once. It holds a short index ("here are the skills available") and only reads the full skill when a task calls for it. Ask for a forecast and the forecasting skill loads; ask for anything else and it stays on the shelf. Anthropic describes Agent Skills exactly this way: folders of instructions, scripts, and resources that an agent dynamically loads when relevant (Anthropic, Introducing Agent Skills, 2025).

This matters because context is not free. Everything you put permanently in front of the model competes for attention with everything else. A skill keeps rare-but-important knowledge out of the way until it earns its place.

How is a skill different from a tool or a prompt?

A skill, a tool, and a prompt solve different problems, and confusing them is how agents get bloated. Here is the distinction I use when I build.

• A tool is something the agent can do. An action in the world: read a file, run code, query a database, send an email through a connector. The agent's hands.
• A skill is something the agent can know, on demand. A policy, a method, a step-by-step procedure, pulled into context only when a task needs it. The agent's playbook for one job.
• A prompt is a single instruction in a single moment. It works once. It isn't versioned, it isn't reusable, and the next person who needs the same output has to reconstruct it from memory.

DimensionPromptToolSkillWhat it isOne instructionAn actionA procedure + knowledgeReusable?No, retyped each timeYesYes, saved as a fileVersioned?NoSometimesYesLoaded when?Every time, by handWhen the action is neededOn demand, when the task matches

Here's the engineer's way to see it. A prompt is an instruction shouted across the room. A tool is a machine on the bench. A skill is the written work instruction taped to that machine, so the job runs the same way whether you're there or on holiday, and whoever's at the machine produces the same part. On a factory floor, inputs have to lead to predictable outputs. A skill is how you get that discipline into an AI employee.

This is also the heart of how I think about the whole category. A chatbot waits for your prompt: you do the work, the AI answers. An AI employee takes a real task off your plate and does it. Skills are what make "does the task" repeatable instead of a one-time trick.

Why does a one-off prompt stop being enough?

A one-off prompt fails the moment the task needs to happen again, by someone else, the same way. The first time you coax an agent into writing a good client report, it's a win. The second time, you can't remember what you told it. The third time, a colleague reconstructs a worse version. Nothing was captured. The procedure lived in your head, and your head doesn't version-control well.

The deeper failure is what teams do to solve this: they stuff procedures into the system prompt instead. I've watched this arc many times. An agent starts lean, people ask for more, each new policy gets bolted into the prompt, and a few months later the prompt is four hundred lines with rules that quietly contradict each other. Then the agent does odd things. It gets a number wrong it used to get right, because two rules in that crowded prompt disagreed and it picked the wrong one.

That's not a model problem. It's a context problem. The fix is to take each procedure out of the always-on prompt and put it in a skill that loads only when relevant. In Anthropic's own teaching example, an inventory agent called Stock Pilot, moving the business logic out of a ~400-line prompt and into discrete skills shrank the prompt to roughly 15 lines and made an entire class of contradiction failures disappear ([VERIFY] figures attributed to an Anthropic "Code with Claude" workshop on agent decomposition). The prompt should hold only what's true regardless of the task: who the agent is, how it behaves. Everything needed only sometimes belongs in a skill.

What does a real skill look like? A reporting example

Here's a concrete one: the monthly client reporting skill we run at Brixon. The job is unglamorous and perfect for an AI employee. It's frequent, rule-shaped, the same shape every month. Without a skill, it's a person re-explaining the format every time. With a skill, it's a saved procedure.

The skill is a folder. Inside:

• Instructions (the markdown core): pull last month's metrics, compare against the prior period and the client's targets, flag anything that moved more than a set threshold, write the narrative in our house voice, never invent a number that isn't in the source data.
• Scripts: a small bit of code that fetches the metrics and does the arithmetic, so the agent computes over real data instead of "reading" a spreadsheet dumped into its context. Running code over data is faster, cheaper, and far less error-prone than asking the model to do mental math on raw rows.
• Resources: the report template, the list of which metrics matter for which client tier, the tone rules.

You don't write this from a blank page. I build a skill the way I'd train a person: have the agent do the task once, watch where it goes wrong, correct it, then save what worked as the skill. Now it's a file, not a habit in someone's head. It's reviewable, improvable, version-controlled, and handed to a colleague who gets the identical procedure.

The payoff is reliability you can measure. The same skill runs the same way in January and in July. When a client's targets change, you edit one file, not eleven prompts scattered across eleven people's chat histories. And because it's grounded in real data through a script rather than guesswork, the numbers are right.

When should a capability be a skill, and when not?

A capability should be a skill when it's information the agent needs only sometimes: a policy, a method, a multi-step procedure for one specific job. It should be a tool when it's an action the agent needs to take in the world. It should be a sub-agent when the work genuinely needs parallel effort or a fresh, independent context. Skills and sub-agents often work together inside a larger system, which is why I treat agent teams and sub-agents as the next layer up from skills. And sometimes the honest answer is to add nothing at all: a capable modern model can simply handle it in the main agent.

The discipline is to ask the question every single time you add a capability. Does this belong in a tool, a skill, a sub-agent, or nowhere new? Asked once, it sounds trivial. Asked on every new requirement, it's the difference between an agent that scales and one that rots. Default to less. "Add nothing" is frequently the best answer.

One more rule keeps skills honest: a skill is only as trustworthy as your ability to verify it still works. When you add a capability, add the check that protects it. Otherwise you won't notice the day a model update or a changed data source quietly breaks the procedure. That's the same argument I make for evals on AI agents: you can't keep a procedure reliable if you can't measure whether it's still doing its job.

Frequently asked questions

What is an AI agent skill?

An AI agent skill is a packaged, reusable capability (instructions plus optional scripts and reference files) that teaches an agent to perform one specific job the same way every time. The agent loads it on demand, only when a task matches, rather than carrying it in context permanently. It turns a one-off prompt into a versioned, repeatable procedure.

What is the difference between a skill and a tool?

A tool is something the agent can do: an action like calling an API, running code, or sending an email. A skill is something the agent can know: a procedure or policy it pulls into context when a task needs it. Tools are the hands; skills are the playbook that tells the hands what to do and in what order.

How is a skill different from just writing a good prompt?

A good prompt works once, in one moment, and isn't reusable or versioned. The next person retypes it from memory and gets a worse result. A skill captures the procedure as a saved file that can be reviewed, improved, version-controlled, and shared. It makes the output repeatable instead of dependent on whoever happened to write the prompt.

How do I create a skill for an AI agent?

Don't write it cold. Have the agent perform the task once, watch where it goes wrong, correct it, then save the corrected procedure as the skill: a markdown file with any scripts and reference documents the job needs. From then on it runs the same way every time and can be handed to anyone on the team.

Are AI agent skills the same as Claude skills?

"Claude skills" (Anthropic's Agent Skills) are one specific implementation of the broader idea: folders of instructions, scripts, and resources that an agent loads dynamically when relevant. The concept of packaging a reusable, on-demand procedure applies across platforms, whether you run Claude, Microsoft Copilot, or an n8n-based stack.

Why use skills instead of putting everything in the system prompt?

A long system prompt pollutes every request with information most tasks don't need, and as procedures pile up they start to contradict each other, which causes the agent to make mistakes it didn't used to make. Skills keep the prompt for what's always true and load the rest only when needed, which removes the contradiction failures and keeps the agent lean.

Sources and further reading

• Anthropic: Introducing Agent Skills (2025), skills as folders of instructions, scripts, and resources loaded dynamically.
• Anthropic: Agent Skills documentation, progressive disclosure and skill structure.
• Anthropic: "Code with Claude" workshop on agent decomposition (the Stock Pilot worked example; prompt-to-skills figures marked [VERIFY]).

I build AI employees this way because it's the only way that survives contact with a real business: capture each job as a skill, keep the prompt lean, and verify the procedure still works as the tools underneath it change. That discipline of packaged procedures over clever one-offs is exactly how I run managed AI employees for the companies I work with. If you want to see which of your recurring tasks could become a skill an AI employee runs for you, start a conversation.