Retrieval runs on the description, not on the body

PR #418 adds a single file, .claude/skills/db-helper/SKILL.md, and it is 300 lines long. The frontmatter declares name: db-helper and description: Helps with database work. The body opens with two paragraphs about why the team cares about migration safety — a paragraph on the March incident where a NOT NULL backfill, a bulk update that writes a value into every existing row of a table, locked the orders table for the length of the write, and a paragraph on the review culture the team has built since. After that come eleven sections of genuinely good procedure: how to write a reversible migration, when to use CONCURRENTLY, the shape of the team's rollback plan.

That file is a skill: a markdown document that hands the agent a procedure it does not otherwise know — a team convention, a runbook, the steps of a review — together with a short statement of when it applies. The two parts of the file are read at different moments. The frontmatter at the top, the name: and description: lines fenced off by ---, is the part that stays resident, sitting in the model's context on every single request as one entry in a list of everything this agent could do. The body underneath is fetched only once the model has picked that entry out of the list, and it is what the agent then follows. Skills exist because the alternative is a standing prompt carrying every procedure the agent might ever need, which is paid for on requests that have nothing to do with migrations and which dilutes its own instructions as it grows; topic 12.3 worked through the tiers that arrangement produces. In practice you meet a skill as a directory checked into the repository and scanned by the agent at startup — here .claude/skills/db-helper/, holding a SKILL.md and whatever files it refers to — which is why one arrives as a pull request with a reviewer attached, and why the reviewer has to decide what a good one looks like.

The reviewer's eye goes straight to the 300 lines. That is the visible defect, it is the one that shows up in the diff stat, and it is the one that maps onto an instinct every engineer already has about files that are too long. The comment writes itself: this is documentation, not a skill, please cut it down. The description gets a nod, because six words is not where the problem is when three hundred lines are sitting right there.

That reading has the ranking backwards, and the same author's previous skill shows why. Last quarter they shipped pg-index-advisor, described as "Helps with query performance", with a tight 40-line body that three people reviewed and liked. Over the following six weeks the agent handled 63 requests that the skill was written for — slow endpoint investigations, EXPLAIN output pasted into chat, "why is this query taking 4 seconds now" — and the skill was selected on four of them. The body was excellent on all four. On the other 59 the agent answered from its own general knowledge, produced advice that was reasonable and generic, and nobody filed a bug, because a mediocre answer does not look like a failure.

The two defects are not the same kind of thing#

A skill has two failure surfaces and they compose multiplicatively rather than additively. The description determines whether the skill enters the running at all, which is a probability between zero and one. The body determines what happens once it has been selected, which is a quality and a token cost. The value the skill delivers is the first multiplied by the second, so a description that never matches drives the product to zero no matter how good the body is, while a bloated body degrades a positive number without zeroing it.

It helps to be exact about what the description is doing, because "the model decides whether the skill is relevant" hides the mechanism. The name and description of every installed skill sit in context as a list, phrased roughly as an inventory of capabilities available for this turn. When a request arrives, the model is choosing among those entries and the option of using none of them, on the evidence of the entries alone. Nothing about the body is available to that decision, and nothing about how carefully the body was written can influence it. The description is a document in a retrieval system and the user's message is the query, with the twist that the query was written by somebody who has never seen the document and does not know it exists.

The fire rates are the ones observed on pg-index-advisor before and after its description was rewritten in week seven; the token figures are the body measured with tiktoken at roughly 13 tokens per line of prose-and-code. The rows that matter are the second and third. Row two is the current PR: a skill that costs almost nothing because it almost never loads, and delivers almost nothing for the same reason. Row three is the PR with only the description fixed: expensive on every invocation, and useful on 85% of the requests it was written for. Fixing the six-word line moves you from row two to row three. Fixing the 300 lines while leaving the description moves you from row two to row one, which is a smaller bill for the same absence of value.

There is a second reason the ordering matters, which is that the two fixes have very different failure feedback. If you cut the body badly — remove a step that mattered, defer a schema the agent needed — the skill fires, produces a wrong answer, and somebody notices, because a bad answer on a task you asked for is visible in a way a missing skill is not. A description that never matches produces silence, and silence is not a signal anyone triages. Teams therefore accumulate skills that never fire far more easily than they accumulate skills that fire and misbehave, and a review process that spends its attention on body length reinforces exactly that asymmetry.

What the six words are actually competing against#

"Helps with database work" is not being read by a human deciding whether to click something. It is one entry in a list of every skill's name and description, held in context on every request, against which the model matches whatever the user actually typed. The requests it has to win are sentences like "the checkout migration has been running for 20 minutes on staging, is it safe to kill it" and "add a currency column to invoices, default USD". Neither of those contains the word "database", and neither of them is phrased as a request for help.

The rewrite has to put the triggering situations into the text, in the words the requests use, and mark off the neighbouring territory the skill does not cover.

---
name: db-helper
description: >-
  Use when writing, reviewing, or troubleshooting a Postgres schema migration:
  adding or altering a column, adding an index, backfilling data, or deciding
  whether a running migration is safe to cancel. Covers lock behaviour,
  reversibility, and the team's two-phase deploy rule. Not for query
  performance tuning or connection-pool configuration.
---

Four things went in that were not in the original. There are the concrete operations the skill is about — adding a column, adding an index, backfilling, cancelling — which are the nouns and verbs a request will contain. There is the technology, Postgres, which discriminates against the skill firing on a Mongo question. There is the situation rather than the topic: "troubleshooting" and "deciding whether a running migration is safe to cancel" describe a state the user is in, and users describe their state. And there is an explicit exclusion, which is the part authors leave out most often; naming query tuning as out of scope is what stops this skill from competing with pg-index-advisor on the 63 requests that belong to it.

Working from a request log rather than from imagination is what produces that list, and the difference is visible in the exclusion clause. Nobody writing a description from scratch thinks to write "not for query performance tuning", because the skill's author is thinking about what their skill does. It appears only once you have sat with twenty real requests and noticed that six of them are about slow queries and would be actively harmed by a migration procedure loading instead of the index advisor. The exclusions are the part of a description that comes from evidence rather than intent.

That expanded description costs about 70 tokens against the original's six. Topic 12.3 priced resting metadata precisely, so the arithmetic is familiar: across a 40-skill library, spending an extra 60 tokens on every description raises the resting cost by 2,400 tokens per request. That is a real bill and it is the correct trade, because the alternative is 40 skills that rest cheaply and route badly.

The argument that the opening paragraphs help#

The author's defence of the two paragraphs about the March incident is that they help the model understand the context — that a model which knows why the team cares about migration safety will apply the rules with better judgement than one following steps blind. It is a sincere argument and it has a real intuition underneath it, since context genuinely does change how a model handles an ambiguous case.

It fails here for a reason that has nothing to do with whether background is ever useful. Those paragraphs live in the body, and the body is fetched after selection has already happened. Whatever they contribute, they contribute to execution, and they contribute nothing at all to the decision that is currently failing. Offering them as a defence of the skill's design is answering a question about retrieval with a claim about generation.

There is a version of the author's argument that survives, and it is worth conceding so the disagreement stays about the right thing. If the two paragraphs were in the description — compressed to a clause like "the team's rule exists because unqualified backfills have locked production tables" — they would be doing retrieval work, since a request that mentions a locked table would match them. Background is not disqualified by being background; it is disqualified by sitting in a tier where the decision it might have influenced has already been made.

The second half of the answer is narrower and it is a claim about those specific paragraphs. "The team believes migration safety is important, following the March incident" does not change what the agent does on any request, because every action it might have licensed is already written as a step further down. A background fact earns its place when its removal measurably changes the plan the agent produces, and the March narrative does not clear that bar — the rule it justifies is stated four sections later as an instruction. That distinction between rationale that decorates and background that changes the plan is doing a lot of work, and it needs a test rather than an opinion, which is what the fifth chapter builds.

Where this ranking stops applying#

The claim here is about the order in which you fix two defects, not about body length being harmless. A 3,900-token body that fires on 85% of a busy team's requests is a serious ongoing cost, and it is worse than the token figure suggests once several skills load in the same session. Once the description works, the body is the next thing to cut, and most of this topic is about how.

The ranking also assumes both defects are present in the same skill, which is the case in front of the reviewer. If a skill's description is already precise, none of this tells you anything; you are in row three and the only remaining question is the body. And if the skill is genuinely never going to be needed — a procedure for a service being decommissioned in a month — then the correct fix is to delete it, and arguing about which line to repair first is effort spent on a capability nobody will invoke.

The sharpest limitation is that a good description is not the same as a description that wins. You can name the operations, the technology and the exclusions exactly as above and still lose every request to a broader skill sitting next to it in the library, or fall below the model's threshold for selecting anything. Precision in the author's vocabulary is not the same property as matching the vocabulary of the person with the problem, and those two can come apart completely — a description can be a model of technical accuracy and match nothing anybody types.

That is the failure the next chapter takes apart: a description that is correct in every particular, reviewed and approved by the people who own the procedure, and which fires zero times in forty days.