The Right Primitive
Five primitives carry every behavior you add to a coding agent: hook, command, skill, tool, subagent. They line up by weight. Ask the questions lightest first and take the first yes. Name that primitive in one sentence before you build.
You maintain every primitive you add, for as long as the behavior exists. The weight you pick is the weight you carry.
Primitive model
When something is missing, the urge is to build the biggest thing, a whole new robot. That build is usually wasted.
Hanging a picture takes a nail. A crane lifts the same picture and costs far more to bring in. Most needs are small: a rule that fires at the right moment, a shortcut you type, a saved routine.
Reach for the lightest thing that does the job. The small one is easier to understand, cheaper to run, and far less likely to surprise you later.
Choosing the primitive sits on top of every idea in this guide so far. Inside a single task, the agent already spends the cheapest move first. The same rule decides which primitive you add.
The needs that arrive are ordinary. Block an edit to a protected file, or start a release from one typed shortcut. Reach a record the model cannot see.
Watch where each need lands.
01Five primitives, ordered by weight
Each primitive on this list adds a power the one before it does not have.
- A hook is the lightest. It is your code running at one fixed moment, and it can allow, block, change, or watch. It guards a power the agent already has. The permissions runtime showed a hook rewrite an action before it ran.
- A command is a shortcut you type. It packs a prompt or an action behind a slash. The first idea showed the router answer one without waking the model at all.
- A skill is a saved routine the model runs, a prompt with a little structure. It runs inline or inside a subagent.
- A tool is a new capability the model calls. It carries its own contract, as the tools idea showed. This is the rung that reaches outside the model, often through a connection to another system.
- A subagent is the heaviest. It is a whole job with its own context and workspace, as the subagents idea showed. Take it when the work stands on its own.
02The decision is just "the first yes"
Walk the questions in the order the ladder sets. Each rung is one test. Stop at the first yes and build that primitive.
- It fires at one fixed moment to allow, block, or shape the work. Take the hook.
- You type it yourself as a shortcut. Take the command.
- The model runs it as a saved routine. Take the skill.
- It reaches outside the model for a capability the model lacks. Take the tool.
- It is a whole job that stands alone, run off to the side or all at once. Take the subagent.
The order does the work. Once a rung answers, you never price the ones above it.
03Why "the lowest that works" is the rule
A hook is a few lines of your code, read top to bottom. A subagent is a machine: a context to fill, permissions to set, a log to read, a bill to pay. The job that fills the machine earns it, and every other job pays for power it never calls. That is a crane hired to hang a picture.
Where it breaks
Take the smallest primitive that builds the need. Small things break in one place, and you find that place by reading them. Every part you add is one more place to search.
a whole subagent
Its own context to build, its own permissions, its own bill, its own ways to break. All of it to make one yes-or-no check.
a hook
A few lines of your code that run at the exact moment, say no, and get out of the way. Easy to read, cheap, hard to surprise you.
04The two ways to get it wrong
Going too big is the mistake I see most. You spin up a subagent for a check a hook closes in three lines. You build a tool for a routine a skill states in a prompt. The demo runs clean. Then you maintain a whole machine to hold one guardrail.
Going too small costs later. You press a new capability into a skill prompt because the tool felt like work. You fake a guardrail with a command that fires only when you remember to type it. Both hold until the odd case arrives. Then the break lands far from the cause, because the behavior lives on the wrong rung.
05The tell that you picked wrong
Count the joins in the sentence you write down. Say the need out loud: a command that calls a skill that needs a hook to be safe. That is three changes wearing one name, and you have not decided yet. A clean one names one primitive and one moment. "This is a hook that blocks edits to protected files." "This is a skill that runs our review checklist."
what you wrote down
The cost
The ladder is a guide with soft edges. A command is almost a skill, and a skill can carry a hook. Some needs take more than one primitive, and forcing those into one name is its own mistake. The price is honesty about the need, before you reach for the primitive that meets it.
Decision
Write the sentence before you build: one primitive, one moment it fires. An "and then" in that sentence means two changes. Split them and walk each half down the ladder. The next idea is the full menu of these primitives and the moments each one plugs into. Extensibility.