A capability is bought once and paid for every turn.

Context is a budget and it is spent on every request. A rule you wrote crowds out a rule you need. A tool schema you never call crowds out both. This is the resource capabilities compete for, and it is the reason the four rungs exist as four rungs rather than as one file format.

0.1 · The ledger

Read the standing column first. It is the one that compounds.

0.2 · Where the invoked tokens land, which is the actual trade

The four rungs split cleanly in two, and the split is not about power. It is about which window pays. A command and a skill put their work in front of you. A sub-agent and an MCP server put their work somewhere else and hand back a result.

flowchart TD
  N["a need arises in this turn"] --> C{"which rung carries it"}
  C -->|"command"| A["the body lands in this window"]
  C -->|"skill"| B["the body lands in this window"]
  C -->|"sub-agent"| S["the reading happens in another window"]
  C -->|"MCP server"| T["the work happens in another process"]
  S --> SR["a summary lands in this window"]
  T --> TR["a result lands in this window"]
  A --> W["this window, now smaller"]
  B --> W
  SR --> W
  TR --> W
  class N dim
  class C dim
  class A warn
  class B warn
  class S pass
  class T pass
  class SR pass
  class TR pass
  class W block

So the sub-agent is the one rung that can hand context back. It spends a one-line description on every turn and saves you a thousand lines of reading when it fires. Nothing else on the ladder does that, and it is why a research task that would fill your window belongs there rather than in a skill.

0.3 · The arithmetic, which you can run today

Standing cost is not a file size. It is a file size multiplied by every turn of every session that has the capability in scope. Get the multiplier and the choice usually makes itself.

1. count the bill Run /context in a fresh session. It reports what is standing in the window before you have asked for anything: system prompt, memory files, tool schemas, and the descriptions of every command, skill and sub-agent in scope.
2. count the turns Take a normal working session and count assistant turns. Twenty is a small one. The standing bill is paid once per turn, so multiply.
3. count the fires Count how many times the capability actually fired in that session. Section 9 gets this from the transcript rather than from memory, because memory flatters the capabilities you were proud of.
4. divide Standing cost times turns, divided by fires, is what one invocation really cost. A capability that fires twice a month and stands in every turn is not cheap because its file is short.

I am not publishing a token table for the four rungs. The honest ranges are wide, and mine would be wrong for your repository within a week. What holds across setups is the shape: a description is tens of tokens, a skill body is hundreds to thousands, and a chatty MCP server can stand for more than every skill you own put together. Measure the last one first.

Watch the two failures side by side. A hook that should have blocked a migration and did not leaves a migration in the tree. A skill that should have been loaded and was not leaves a commit message in the wrong format, or a test written the way the model likes rather than the way your suite is written. The second one merges.

So a capability needs an instrument that a constraint does not. A constraint gets audited by its violations. A capability has to be audited by its invocations, and the invocation is the thing nobody is looking at. Between installing a capability and it doing any good, there are five gates, and every one of them fails quietly.

flowchart TD
  I["you install the capability"] --> G1{"is it in scope for this session"}
  G1 -->|"no"| D1["dead: wrong scope"]
  G1 -->|"yes"| G2{"did the description match the need"}
  G2 -->|"no"| D2["dead: never matched"]
  G2 -->|"yes"| G3{"did a sibling match harder"}
  G3 -->|"yes"| D3["dead: lost a collision"]
  G3 -->|"no"| G4{"did the body carry what it assumed"}
  G4 -->|"no"| D4["dead: broken on load"]
  G4 -->|"yes"| G5{"did the return get used"}
  G5 -->|"no"| D5["dead: result ignored"]
  G5 -->|"yes"| OK["the turn is better than it was"]
  class I dim
  class G1 dim
  class G2 dim
  class G3 dim
  class G4 dim
  class G5 dim
  class D1 block
  class D2 block
  class D3 block
  class D4 block
  class D5 block
  class OK pass

1.1 · The five deaths, and what each one looks like from the outside

1. wrong scope The capability exists in a personal directory and the work happens in a repository, or it lives in a plugin nobody enabled. From the outside the agent looks like it ignored a skill it never had. Tell: it works for the author and nobody else.
2. never matched The description says what the capability is, and the model needs to know when to use it. Helpers for database work matches nothing a user actually types. Tell: invoking it by name works perfectly, and it never fires on its own.
3. lost a collision Two capabilities overlap and the more general one keeps winning. Tell: the specific one fires only when the general one is disabled, which is how most people discover the collision.
4. broken on load The body assumes a path, a tool, a credential or a convention that is not there. The capability fires and then flounders, and the model works around it silently. Tell: transcripts show it loaded, then show the model doing the job by hand.
5. result ignored A sub-agent returned a summary that did not answer the question, or an MCP tool returned four pages of JSON where a field was needed. The parent re-derives the answer and pays twice. Tell: the same lookup happens after the tool call that the tool call was supposed to settle.

Four of those five are description and interface problems rather than implementation problems. The capability worked. Nobody found it, or nobody could use what came back. That ratio is why The Capability Ladder gives a whole section to one line of frontmatter, and another to what comes back.

The five have one thing in common worth naming. Every one of them is a change in the relationship between a capability and its surroundings, rather than a change in the capability. The file is the same file. The repository, the catalog, the vocabulary and the model around it are not, and none of those movements sends you a notification.

Two of the five have a repair that removes the failure mode instead of detecting it. Variance goes away when a decidable question is decided by code, which is Part II. Bloat goes away when the catalog has a fixed budget, which is section 11. The other three you have to watch for, and Part III is how.

Measure it before you argue about it. Take a question a capability answers, run it five times on the same input, and count the distinct answers. One is determinism. Two is a coin flip wearing a procedure. The count takes ten minutes and it settles more arguments about agent reliability than any amount of prompt editing.

So the design question is never is the model good at this. It is is this decidable. If it is, code decides it, and the model's job becomes choosing when to run the code and fixing what it reports. That division survives model changes, which is the other thing determinism buys and the one that matters over a year.

Section 3 said the answer has to stop moving. This is how you make it stop, and the mechanism is a file in a directory plus one sentence telling the model to run it rather than think about it. No new rung, no schema, no process to keep alive.

4.1 · The sentence that carries it

Two phrasings matter and one of them is load-bearing. Naming the script is not enough, because a model that has already read the file will often answer from what it read. The instruction has to say the script is the authority: run it, do not reimplement it. That clause is what turns a suggestion into a procedure with one answer.

# in SKILL.md, the step that matters
3. Run scripts/check_reversible.py against the new file.
   Do not reimplement this check by reading the file yourself.
   Fix every line it prints, then run it again.

# the script's contract, written down where the caller can see it
exit 0  nothing to report
exit 1  findings on stdout, one per line:
        path:line · rule · what to change
exit 2  the script itself could not run. Say so, do not guess

The third exit code is the part people leave out and the one that keeps a script honest. A checker that cannot distinguish nothing wrong from I could not look will report clean on the day it breaks, and the model will believe it. That failure has an exact analogue on the constraint side, where Layers and Promotion found a pipeline reporting done over a tree with two violations in it.

4.2 · Where a script can live

1. in a skill Bundled beside the procedure, granted by allowed-tools, run by name. No standing cost, no schema, no process to manage. This is the default and it is where most determinism belongs.
2. in a command Injected with ! at expansion, so the prompt arrives holding facts rather than asking for them. Determinism at rung 0, and it cannot be forgotten because it is part of the text.
3. in a sub-agent The same trick behind a context wall. A child that runs the checker and returns its findings is cheaper than a child that reads the tree and forms an opinion.
4. in a hook or a gate The same script, mounted where the agent cannot decline it. Now it is a constraint, and the other page owns the design.

5.1 · The same job, three ways

Take one decidable check and carry it three ways. The variance column is what you are buying. The skippable column is what you are not.

The three rows are one script with three mounts, which is the property Constraint Engineering asks of a good constraint: one identity, one predicate, many mounts. Write the predicate once. Then decide separately whether the agent may skip it, because that decision is a constraint decision and it does not belong to this ladder at all.

6.1 · The word test for decidable

Try to write the failing condition down. If you can state it without a word that requires taste, it is decidable and a script should own it. If the sentence needs clear, reasonable, appropriate, idiomatic or meaningful, you are holding a judgment, and no amount of scripting turns it into a predicate.

6.2 · Most judgments have a decidable shadow, and it is worth finding

The useful move is not to pick a side. It is to split the question. Almost every judgment contains a smaller decidable claim, and the script takes that part while the model keeps the rest. You get one answer where one answer is possible and an opinion only where an opinion is unavoidable.

There is a trap in the last column and it is worth naming, because I fell into it. Layers and Promotion found that a gate enforcing the decidable shadow of a rule makes the judging rung look deletable. The counts go green, the shadow is covered, and the part that needed taste is quietly no longer being asked. Keep both, and keep them labeled.

6.3 · Judgment needs an eval, not a script

Those questions belong to a model, and a model's answers need the apparatus in The Eval Loop: a golden set, a distribution rather than one run, and a number that moves. The division of labor is the useful part. Code for verdicts, models for selection and repair. A capability that mixes them into one prose instruction gets the variance of the model on the question the script could have settled.

7.1 · The price ladder for a repeatable answer

Determinism has a price ladder of its own, and it runs in the opposite direction to the capability ladder in The Capability Ladder. The cheapest option sits at the bottom, so start there and climb only when a rung above buys something the rung below cannot.

The last row is the one to be strict about. Reaching for a server to get repeatable answers is paying a schema on every turn for something a fifty-line script does for nothing. The five reasons that do justify it are in the first half of this pair, and repeatability is deliberately absent from the list.

9.1 · Counting the fires

Session transcripts are line-delimited JSON under the project directory in ~/.claude/projects/. Their shape is not a published contract, so look at one record before trusting a query. Then count tool calls by name.

# every tool call, by name, most used first
jq -r 'select(.type=="assistant")
       | .message.content[]?
       | select(.type=="tool_use")
       | .name' ~/.claude/projects/<project>/*.jsonl \
  | sort | uniq -c | sort -rn

# which skills actually loaded
jq -r 'select(.type=="assistant")
       | .message.content[]?
       | select(.type=="tool_use" and .name=="Skill")
       | .input.skill' ~/.claude/projects/<project>/*.jsonl \
  | sort | uniq -c | sort -rn

# MCP tools carry their server in the name: mcp__server__tool
# A server with one busy tool and nineteen silent ones shows up here
# as one row, and it is billing you for twenty.

Join that count to the standing bill from /context and you have the cost ratio from section 0, per capability, from your own work rather than from a table on a web page. Every capability with a standing line and a zero in the count column is a decision waiting to be made.

9.2 · The week with it turned off

The fourth number resists transcripts, because a capability that never fired left no trace of what it would have improved. Two ways to get at it, and the second is cheaper.

1. the ablation Disable one capability for a week and read the work it should have touched. Slow, noisy, and the only method that measures the real thing rather than the trigger.
2. the golden set Six requests per capability: three that should fire it, three near misses that should not. Run them in fresh sessions after every description edit. This measures the trigger rather than the benefit, and the trigger is where four of the twelve anti-patterns live.

10.1 · Move on an observation, and record which one

The signals below are the ones I trust, and each row is an observation rather than a feeling. Record the observation next to the change. The argument two quarters later is always about whether the move was ever justified, and the answer is either in a commit message or it is gone.

11.1 · Deletion day, for capabilities

Anatomy of a Charter holds the constraint side to a fixed budget, because growth is the default. Capabilities need the same discipline and get it less often, because a skill nobody uses feels harmless. It is not harmless. It stands in every turn and it competes for selection with the capability you needed.

So: a fixed number of standing lines, decided in advance. Adding one means removing one or making the case that the budget should rise. On deletion day, the invocation count decides, and the argument that it might be useful later does not, because a bundled file or a command can hold it at no standing cost until later arrives.

11.2 · The trade, as five rules of thumb

These are the shortcuts I actually use, offered as opinion. They are the ledger applied, and each one is a way of not paying standing cost for something that could be paid for on demand.

1. Pay standing cost for triggers, never for knowledge. A description is a trigger. A reference table is knowledge and belongs behind one. §0
2. When two rungs both work, take the one with the smaller standing cost. When the standing costs match, take the one whose failure is louder. §1
3. A capability that fires less than weekly does not earn a line in every turn. Fold it into a neighbor as a bundled file, or let a human invoke it by name. ladder §7
4. Reach for a sub-agent when the byproduct is the cost, not when the task feels big. Volume of reading is the signal. Importance is not. ladder §3
5. Reach for a process wall only for several clients, an interactive sign-in, a broad surface worth typing, a vendor implementation, or a contract other teams build against. Repeatability is a script. Five reasons, and tidiness is not among them. ladder §5

12.1 · The rules

1. Every capability names its four attributes: trigger, rung, grant, return.ladder §0
2. Run the family test before choosing a rung. A component whose removal lets the agent do more is a constraint, whatever file it lives in.ladder §0
3. Pay standing cost for triggers and never for knowledge.§0
4. Know the standing bill. Run /context in a fresh session and be able to say what stands there and why.§0 · §9
5. Every description states what, when, and when not. The negative trigger is not optional where a sibling exists.ladder §9
6. Every pair of capabilities in scope has a one-sentence distinction. If you cannot say it, the model cannot infer it.ladder §9
7. Every capability has a golden set of six requests: three that fire it, three near misses.§9
8. Re-run the golden set after any description edit, including one that arrived in a plugin update. A trigger change is a behavior change.§2 · §9
9. Every sub-agent declares its grant and its return shape. An omitted grant is the widest one.ladder §10
10. Skills keep procedure in the body and reference in bundled files. A body that loads a manual is a defect.ladder §2
11. Anything decidable is decided by code. Measure variance on any answer a gate trusts, and move it to a script when the count is above one.§3 · §6
12. Buy determinism from the cheap end: a script, then a CLI, then a hook, then a server. Repeatability is not one of the five reasons for a process wall.§7
13. Tools are shaped like the task, not like the upstream API, and they return the answer rather than the payload.ladder §4
14. Anything crossing a process wall from outside is data, not instruction, and the constraint that enforces that lives in your harness.ladder §4
15. Count invocations per capability per week from the transcript. Zero with a standing line is a decision, not a neutral state.§8
16. Hold a fixed standing budget and a deletion day. Adding a line means removing one or arguing for the budget.§11

12.2 · Three levels, and a cadence for each

The cadence column matters more than the rule list. Every rule here that has ever slipped for me slipped because it had no date attached, and a maintenance standard without a date is a preference. Put the monthly count and the quarterly deletion day in the same calendar the rest of your engineering rituals live in.

12.3 · Where I fail it

I am at level 2 and not level 3. The rule I miss is the last one: I have the invocation counts and I have never held a deletion day for capabilities, so my own catalog has grown for months while the constraint side of the same charter stayed inside a fixed budget. That asymmetry is the thing that made me write this page, and it is exactly the bias the page describes. Removing a rule feels like accepting risk, so it gets argued. Removing a skill feels like losing something for nothing, so it never gets raised.