Skills and plugins

description and when_to_use go into the prompt of every agent that is offered this skill, whether or not the skill is ever used. content costs nothing until the fragment is expanded. Two columns rather than one is what makes offering a thousand skills affordable, and it is the same progressive disclosure the standard describes — a skill's body "loads only when it's used, so long reference material costs almost nothing until you need it."

Because the listing is a budget, the table enforces one: description plus when_to_use is capped at 1,536 characters, which is the standard's own listing cap transcribed rather than invented. A cap enforced by the table is the only kind that holds — the alternative is truncation at render time, which is invisible, and a skill whose trigger sentence was cut in half is a skill the model quietly stops choosing.

when_to_use is separate from description because it answers a different question and because it is the sentence a semantic match should hit: a user's request rarely resembles a capability statement, and usually does resemble the situation the fragment is for.

requires_tools is the useful half of the standard's allowed-tools. That field is a permission grant against an interactive approval flow, and there is no such flow here — what survives is the dependency it implies, which the database checks the moment an agent tries to carry the fragment.

Related the Agent Skills standard · frontmatter and progressive disclosure · the agent whose prompt this joins

Write out what a prompt costs under each model and the difference is structural rather than a matter of degree.

If attaching carried the body, the prompt is agent + Σ(all attached bodies). Every term grows with the size of the surface. Attaching a twelfth fragment costs its whole body on every turn forever, including the turns it has nothing to do with — so there is a point, and it arrives quickly, where you stop attaching things because you cannot afford them. That is the same pressure that makes people write one enormous system prompt and then stop editing it.

With lazy attachment, the prompt is agent + Σ(always bodies) + (at most top_k bodies, capped by max_chars) + N listings. Only the last term grows with the surface, and it grows in units of a listing rather than a body. The bodies that arrive are chosen per turn and bounded by a budget you set, not by how many fragments exist.

In the fixture above a listing averages 218 characters against a body's 400, so the surface term grows about 1.8× more slowly. That ratio is the whole game, and 1.8 is a floor rather than a typical figure — these fragments are deliberately terse. A real procedure runs to two or five thousand characters against the same ~220-character listing, which is 10× to 25×. The saving is proportional to how much you have to say.

The one thing you pay unconditionally is the index: N listing lines, every turn. That is the honest cost of this shape, and it is why the index is a decision rather than a freebie — what the numbers say is where that decision is argued, and where the listing turns out to be doing most of the work.

Related the tool surface this mirrors · what arrives on demand, and who decides

Without this, adding one fragment means reading agents.skills, appending, and sending the whole array back. Two clients doing that at once both read the same array and the second write silently discards the first — no error, no conflict, and an agent missing an instruction somebody watched themselves add.

read-modify-write (the array, through upsert_agent)  ->  1 of 2 landed
attach_skill                                         ->  2 of 2 landed

attach_skill appends inside a select … for update, so concurrent attaches to one agent serialize instead of clobbering. It does not write the agent row itself: it computes the new array and hands it to upsert_agent, so the checks that refuse an unknown fragment, or one whose requires_tools name a server this agent does not bind, run from one copy rather than two. Attaching a skill written against the query server to an agent that binds no query server is refused with the same message as authoring it that way.

Attaching what is already attached is a no-op rather than an error, and a new fragment appends at the end because composed fragments are concatenated in listed order. Two things are refused rather than resolved: an agent that does not exist, because the underlying upsert would cheerfully create one with an empty prompt that resolves by name and can do nothing; and a name given both as an argument and inside the spec, disagreeing, because whichever one the function picked, the other is what somebody believed they had written.

Related the agent write path these checks live in

always is the unconditional subset of the attached surface: read from the database at invocation and concatenated into the prompt. It is a policy key rather than the meaning of attachment, and that is the distinction the section above turns on — if attaching were eager there would be no cheap way to give an agent a large surface at all. Expect two or three names here out of a surface of dozens.

Matched is the runtime's answer: it embeds the turn's request, ranks it against the listings of the attached surface, and expands what clears min_score under the max_chars budget. scope widens that ranking beyond what the agent attached, which is discovery rather than capability — a different claim, so a different key. No round trip and no tool call — the model never has to know skills exist. When the budget is reached the remaining matches fall back to their index lines and the run records which ones, because a silent truncation is the failure the listing cap exists to prevent one level up.

The third way in is fetched, where the model asks. It is two surfaces, split by how large the population is:

load_skill(name) is one tool covering the attached surface. The index has already named those fragments, so the model does not need to search for them — it needs a way to ask, and one tool with one argument is that. Keeping it to one is deliberate: every tool an agent is offered costs its name, description and schema in every prompt, and a design that answers "how do we expose this?" with "another tool" has usually not asked the question yet.

Beyond the attached surface, an agent can be permitted to reach fragments it could never list — a thousand rows will not fit in a prompt as a thousand listing lines. Those become deferred tools: one per fragment, hidden from the model entirely, surfaced by a search when a request calls for one. The reference implementation builds this with pydantic-ai's defer_loading(), used as-is, and it is the same trade this page has been making all along — a listing is cheap, a body is not — in the framework's own vocabulary. An agent that permits no discovery carries none of it.

Expansion uses no framework's lazy loading, and it does not need to. The fetched path above leans on pydantic-ai; the two paths that put a body in the prompt before the model is called do not. The laziness there is a SQL projection. The query behind the index asks for the name, the description and the trigger, and never for the body, so a body is not read until it is named. That holds under any framework or none. It is also the half that is easy to get wrong, because the prompt looks lazy either way: a query that selects the whole row and uses three columns of it has already pulled every attached body out of the database.

sticky is why instructions do not churn. Matching per turn against the latest message, on its own, means a fragment expanded on turn three is gone on turn four when the subject moves — so a model told to cite its sources quietly stops being told, and nothing reports it. With stickiness the set is a union within a branch: later matches are added, never swapped in, so instructions are monotonic and the accumulation is bounded by max_chars rather than by the size of the fleet.

Related the rest of `context_policy` · pydantic-ai's toolsets, which expansion does not use

The second call in that trace is the one to look at. extraction-cost-cascade was never attached to the agent, never appeared in its index, and was never in its prompt. It was found by search and followed, which is what deferred loading is for.

The limit is that the model has to decide to look. Asked how to get structured data out of 200 documents without it costing a fortune, the same agent with the same population answered from its own general knowledge and never searched at all — and answered reasonably, which is worse, because nothing signals that a house procedure went unread. The moment the request was shaped like a request to look, the right fragment arrived.

That is the argument for the runtime deciding rather than the model, and it is why matching is the primary path and fetching is the addition. A fragment the runtime expands is in front of the model whether or not the model would have thought to ask.

Related the two paths that do not require the model to ask

agentic.skills needed no adaptation to become searchable: the semantic path joins its embedding space back to the source table on id, which is the whole contract. It is registered as both a semantic and a lexical source, so an agent's matching policy degrades to full-text where no embedding provider is configured rather than degrading to nothing.

Only the listing is embedded, never the body. A body is hundreds of imperative lines that dilute the one sentence describing what the fragment is for, and that claim was measured rather than assumed: embedding the listing beats embedding the body by 22 points of hit@1 and 0.118 of MRR over 31 labelled requests. The body arm finds the right fragment somewhere in the top three four points more often — expansion takes the top k under a threshold, so rank is what decides, but the recall result is real and is written down rather than rounded away.

The text that gets embedded is a generated column, so the text a matcher indexes and the text a reader sees cannot drift apart. That turned out to have a consequence worth knowing: a generated column may not reference another generated column, so the full-text vector is generated from the base columns directly rather than from the generated listing.

Related the query modes this reuses · how a corpus gets its vectors

Applying is one transaction in one order — servers, then skills, then agents — because an agent's composed fragments must exist before they can be validated, and a fragment's requires_tools name servers the agent must already bind.

The half that matters is the prune. Without it, an agent dropped from the document stays installed, still resolvable by name, still runnable, and nothing on disk describes it any more. So a row carrying this plugin's name and absent from this manifest is removed, and the removals come back in the result rather than happening quietly. That makes an absent section loud on purpose: {"name": "harbour"} declares no agents and therefore removes every agent harbour installed, which is what makes uninstall expressible without a second function.

Three things it refuses to remove, and none of them is caught by a foreign key, because agents.skills is a list of names and agents.tools holds server names in JSONB — which is exactly what lets one fragment serve many agents. An agent with runs against it is not deleted, because that would delete conversation history. A skill another agent still carries is not deleted; nor is a server another agent still binds. Uncaught, that third case is the quietest failure in the schema: the other agent keeps working and loses a third of its instructions.

Related the plugin manifest this mirrors · tool servers as rows

Two of twenty to eighteen of twenty is the whole design justified in one column: a fragment in the prompt changes what the model does, reliably, on requests where the agent without it does the wrong thing every time.

The surprise is the middle row. A single 223-character listing line — the model is told only that the fragment exists — produces sixteen of the eighteen behaviour changes that the full body produces. What the body actually buys is not behaviour but specificity: told only that a fragment about destructive SQL existed, the model proposed the statement and declined to run it, which is correct, and never asked for the primary-key predicate the body requires.

Per character, the index is the most efficient instruction-carrier in the design, which is what sets the defaults: index is bound and top_k is 2 rather than 3. Index everything, expand few.

The index is also the one cost that grows with the surface — one line per attached fragment, every turn — and it is worth knowing where that turns. Listing the unexpanded fragments beats expanding all of them exactly when a body is longer than its own listing. A fragment terser than its own description should be always-on rather than lazy: cheaper to have than to advertise.

A rule about authoring follows, and it is measured rather than stylistic: write the description as an instruction, because that is what the model acts on. "When a LOOKUP returns nothing, use FUZZY LOOKUP instead of guessing another spelling" is a complete instruction in 96 characters and scored 5 out of 5 with no body at all. A description written as a label — "about name resolution" — would have scored none of that.

Related what these numbers do and do not settle

Access control is the same access control. A skill is shared configuration under a policy, on the same row-level security every other table in this system uses. A directory's answer is filesystem permissions on the machine running the agent, which is not an answer at all once the agent is a service.

One write path can refuse a bad skill. upsert_skill bumps a version when the text changes and not when a tag does; upsert_agent refuses a fragment that does not exist, or one whose declared tool dependency the agent does not bind. A file tree has no moment at which to check either, so both become review comments.

Retrieval was already built. Finding the right fragment among a thousand is the same problem as finding the right chunk among a million, and it is the same SEMANTIC and TEXT machinery, over a corpus registered the same way. Nothing was added to search skills.

Provenance is a column. The version that was expanded is recorded on the run that used it, so a run whose answer rests on a procedure since rewritten is reconstructable. Without it nothing downstream can even detect it is looking at the wrong text.

Installing and uninstalling are transactions. A plugin applies as one statement and prunes what it no longer declares, with referential checks that a directory has no place to put.

The general point is the one this whole system keeps making. Because agents, tools, workflows and identity are all already rows, a new idea usually does not need new machinery — it needs a table and the machinery that is already there. Skills are a good test of that claim, because the standard they come from was designed for a filesystem and lost nothing on the way in.

Related what "Postgres is the system" buys and costs · agents as rows