# Instruction, skill or tool?

> Three ways to change what an agent does, the question to ask before choosing one, and what each costs in context and access.

Page: https://schubergphilis.github.io/ai-training/customizing-agents/skill-or-tool-or-instruction/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

A team of four adopts a coding agent. In the first month they notice
three things it keeps getting wrong. It commits with a message format the
team doesn't use. It writes release notes in a different order every time.
It can't tell whether a customer's account is on the old billing plan or
the new one, because that lives in an internal service. Someone on the
team has heard of skills, so they write a skill for each. Two of the three
fail. This lesson is about why, and about the question to ask
before you write anything.

You don't run anything here. The examples are short file contents and
one worked decision, and the exercise is a sort you do on paper.

## Three mechanisms, side by side

In the agent loop from the concepts course, the model reads its context
and decides what to do next, and the software around it runs the tools it
asks for (Tools, giving agents hands: function calling, schema design, the N x M problem, Agent Engineer Course). Every way to customize an agent changes one of those
two parts. Either it puts different text in the context, or it gives the
software a different set of tools to run.

An **instruction** is standing text, loaded at the start of every session
and present on every turn. `AGENTS.md` from the lesson on project
instructions is one. It
suits a rule that always applies, the test command being the usual
example. The harness loads it every time. It is there
whether the task needs it or not (Claude Code 101, Claude Academy) (How Claude remembers your project, Claude Code documentation).

A **skill** is a procedure with a trigger. It is a directory with a
short description of when it applies, and the agent sees only that
description until a task matches it. Then it loads the full instructions
and follows them. In Claude Code the loaded text stays in the
conversation for the rest of the session, and compaction is what trims
it (Extend Claude with skills, Claude Code documentation). A skill suits work the agent could do on its
own but does inconsistently. A release checklist is the usual example
(Introduction to agent skills, Claude Academy).

A **tool** is a function the software runs when the model asks. It adds an
ability the model doesn't have. A database query and a call to an
internal service are two examples. The agent sees at least the tool's
name on every turn, and its full description and schema either on every
turn or when it looks the tool up, depending on the client
(Connect Claude Code to tools via MCP, Claude Code documentation). The function itself runs outside the model. A tool suits a need the agent can't meet with text alone.

The same fact, laid out:

| | Instruction | Skill | Tool |
| --- | --- | --- | --- |
| What it is | Standing text | A procedure with a trigger | A function the software runs |
| Loaded | On every turn of every session | When a task matches its description | Name every turn, and the definition up front or when looked up |
| Fixes | The agent doesn't know a rule | The agent knows how but does it differently each time | The agent can't do it at all |
| Example | "Test with `uv run pytest`" | "Prepare a release: bump, changelog, tag" | `billing_plan(account_id)` |

Back to the team. The commit format is a rule that applies to every
commit. Written as a skill, the agent loads it only when it decides a
task is about committing. A good part of the time it doesn't decide
that. The format belongs in an instruction. The release notes are a procedure the agent can already
write and keeps writing differently, so it belongs in a skill, and it is
the one of the three that worked. The billing plan is a fact the agent
has no way to reach, and no text can teach it, so it needs a tool.

#### Checkpoint: Where does the rule go?

The team wants every commit message to start with a ticket number, on
every task, in every session. Which mechanism fits?

- A skill, so the agent loads the rule when it commits.
- A tool that writes the commit for the agent.
- An instruction, in the project file the agent reads every session.

## The question to ask first

Before choosing among the three, ask whether the agent can already do the
task with what it has. A coding agent ships with a shell and an editor,
and the model behind it has read a great deal of documentation. Much of what a team reaches for a skill or a tool to do is
already within reach.

Take a concrete case. The team wants the agent to check a pull request's
CI status before it says the work is done. Someone starts a skill:

```markdown
---
name: check-ci
description: Check whether the CI run for the current pull request passed.
---

Run `gh pr checks` and read the status of each check. If any check
failed, run `gh run view --log-failed` for that run and summarize the
failure.
```

Now ask the question. The agent has a shell. The `gh` command is on the
machine. The model knows `gh pr checks` and `gh run view` already, because
their documentation is public and common. Asked to "check
whether CI passed", the agent runs those commands without help. The skill
adds a name to the skill list on every turn and teaches nothing the
agent didn't know.

What the team wanted was for the agent to check CI *before* claiming to
be done, every time. That is one line in
`AGENTS.md`: "Before you say a task is done, run `gh pr checks` and
report the result." The rule always applies, so it belongs in standing
text.

A skill earns its place when the procedure holds something the agent
would have to guess: the order your team does things in, the file a
result goes into, a check the agent wouldn't think to make, a script that
does a deterministic step the same way each time. A skill that repeats
what the model already knows is context spent for nothing.

#### Checkpoint: Can the agent already do it?

The team's tests run in three stages, each with its own command, and the
second stage is only valid after the first passed. The team wants the
order kept on every task that touches code, and the agent keeps running
the stages out of order. What do you do?

- Write a tool that returns the list of failing tests.
- Write a skill with the three test commands and the order in which to run them.
- Add the three commands and their order to the project instructions, and write nothing else.

## What each one costs

The three mechanisms differ in what they take from the agent on every
turn and in what they let it do. Put them on two axes.

**Context.** An instruction file is read in full on every turn of every
session, whether or not the task needs it. A skill puts one line, its
description, in the context on every turn, and the full body from the
turn it is invoked on. With many skills installed, Claude Code keeps
every skill's name in the skill list but can drop the descriptions of the
skills used least, to stay within a character budget sized to the
context window (Extend Claude with skills, Claude Code documentation).
In an agent that loads every tool up front, a
tool puts its name, description and parameter schema in the context on
every turn, and a server that exposes thirty tools puts thirty of them
there (Tools, giving agents hands: function calling, schema design, the N x M problem, Agent Engineer Course). Claude Code defers MCP tool definitions by default and
loads only the tool names and the server's instructions at the start of
a session, so the cost per tool is smaller there, and it is still a cost
on every turn (Connect Claude Code to tools via MCP, Claude Code documentation). The warning about long instruction
files in the lesson on project instructions is the same warning as the one about connecting too
many tool servers. Both spend the same budget.

**Permission.** An instruction and a skill change what the agent does
with the abilities it already has. Neither one lets it reach anything
new. A tool does. It is a new ability, with whatever access its
credentials carry, and each one the agent gains is one more thing to
think about when you size what a mistake can reach.

Those two axes leave a gap between a command the agent can already run
and a tool server that wraps a system. Take an internal service with a
command-line client the team already uses. The agent has a shell, so it
can run the client as it is, and often that is enough. When the client's
flags are unusual, or the team's use of it has a fixed order of steps,
a skill that wraps the client fills the gap. It loads only when a task
calls for the service, it costs one description line until then, and it
adds no new ability, because the shell and the client were already
there. Anthropic's own guidance points at this middle way: reach
for a skill around a command before you write or connect a tool server
for it (Claude Code 101, Claude Academy). Claude Code's guide to costs makes
a related point about context: a command-line client adds no tool
listing, so it costs less context than a tool server (Manage costs effectively, Claude Code documentation).
A tool server is right when there is
no client to wrap, when the ability is new to the agent, or when you
need the schema and the access control that a tool gives you and a shell
command doesn't.

#### Checkpoint: Which mechanism?

Buckets:

- Instruction
- Skill
- Tool
- Already possible

Items:

- Use the repository's task runner for every command, never the underlying tool
- Draft a customer-facing incident report in the team's five-section format
- Look up which feature flags are on for a customer in an internal service that has no command-line client
- Rename a function across a codebase
- Never edit files under the generated directory
- Onboard a new service into the monitoring stack, in the order the platform team requires

#### Pitfall: The rule that never fired

A team writes a skill called `no-secrets` whose body says "never commit
a file that contains an API key". Its description reads "Prevent secrets
from being committed". Two weeks later the agent commits a `.env` file.
Nobody asked it to prevent anything, so no task ever matched the
description, and the skill was never loaded. A skill is loaded when the
agent decides a task matches it. A rule that has to hold on every task
belongs in the instruction file, and a rule that must never be broken
belongs in a hook that blocks the action, as the lesson on project
instructions said.

## Exercise

Write down eight recurring needs a team you know has of a coding agent,
or use the ones from the checkpoints above if you have no team in mind.
Sort each into instruction, skill, tool or "the agent can already do
it", and write the one-line reason next to it. Use the four questions in
order: can it already do this, does the rule apply to every task, does
the agent know how but do it inconsistently, does it lack the ability?

A good result names a reason for each item that a teammate would accept
without seeing your sort, and puts no more than two items in the tool
bucket. Most of what a team wants is a rule or a procedure, and the
agent already has the hands. Which item took you longest to place, and
what was the question that settled it?

Stretch: For each need you sorted as a skill, write the one line of its description, the sentence the agent reads to decide whether the skill applies. Then check that none of your instruction-bucket needs could be described that way.

## Recap

1. An instruction is standing text on every turn, a skill is a procedure
   loaded when a task matches its description, and a tool is a function
   for an ability the agent lacks (Agent skills: skills versus tools, the spec, progressive disclosure, Agent Engineer Course).
2. Before writing any of them, ask whether the agent can already do the
   task with a shell and what the model knows. A skill that repeats public
   documentation adds a line to every turn and teaches nothing.
3. Choose by whether the rule always applies (instruction), whether the
   agent knows how but is inconsistent (skill), or whether it lacks the
   ability (tool).
4. Instructions and skills spend context and add no new access. A tool
   spends context on every turn and adds an ability with whatever access
   its credentials carry.
5. A skill that wraps a command the agent can already run is the middle
   way between using the command bare and connecting a tool server
   (Claude Code 101, Claude Academy).

## References

- Tools, giving agents hands: function calling, schema design, the N x M problem, Agent Engineer Course, https://lsimons.github.io/agent-engineer-course/03-tools-giving-agents-hands/
- Claude Code 101, Claude Academy, https://academy.claude.com/courses/claude-code-101
- How Claude remembers your project, Claude Code documentation, https://code.claude.com/docs/en/memory
- Extend Claude with skills, Claude Code documentation, https://code.claude.com/docs/en/skills
- Introduction to agent skills, Claude Academy, https://academy.claude.com/courses/introduction-to-agent-skills
- Connect Claude Code to tools via MCP, Claude Code documentation, https://code.claude.com/docs/en/mcp
- Manage costs effectively, Claude Code documentation, https://code.claude.com/docs/en/costs
- Agent skills: skills versus tools, the spec, progressive disclosure, Agent Engineer Course, https://lsimons.github.io/agent-engineer-course/17-agent-skills/