Agent Skills and Procedural Capabilities: Prompts, Scripts, Assets, and Progressive Disclosure

Every agent builder hits the same wall. The first working agent is small: a system prompt, a few tools, a loop. Then someone needs release notes. Someone else needs log triage. A third person needs the deploy checklist. Each procedure gets pasted into the system prompt because that is the only place the model reliably looks. Six weeks later the prompt is four thousand tokens of accumulated tribal knowledge, latency has crept up, and the model has started ignoring the rule about not force-pushing to main.

The weak model behind that failure is simple and almost universal: more instructions in context equals more capability. It is wrong for the same reason that putting every book in the library on your desk does not make you well-read. It makes you buried. Capability should be discoverable, not resident.

That is the whole argument for agent skills as procedural capabilities. A skill is a directory with a cheap, always-visible index and an expensive, lazily-loaded payload. The entire design problem reduces to one question: what belongs in the index?

Why Monolithic Prompts Stop Scaling

The symptom is easy to recognize once you know what to look for. Prompt bloat raises token cost and latency on every turn, not just the turns that need the buried procedure. Instruction dilution sets in as the model's attention spreads across competing rules. And rules get silently dropped — not because the model is broken, but because a rule in the middle of a long prompt competes with everything around it.

Before going further, it is worth drawing a clean boundary between skills and the concepts you already use.

A tool is a callable interface with a schema. The model invokes it, gets a result, and moves on. A skill is packaged procedural knowledge: applicability conditions, execution policy, termination criteria, and often the tools that carry it out. Skills orchestrate tools rather than replace them. A skill might say "when triaging a production incident, first check the deploy log, then the error rate, then the rollback path" — and the tools are the things that actually check.

The neighboring concepts matter too:

• Persistent context files (the always-on background document) are resident by design. They are for facts the agent should never forget.
• Sub-agents get their own context and control loop. They are for isolation, not for on-demand expertise.
• Skills are on-demand expertise inside the same loop. The agent stays in control; it just pulls in a procedure when the task calls for it.

The design tension is permanent. Discoverability wants rich descriptions in context. Context economy wants them terse. Everything downstream is a negotiation with that tension, and the negotiation happens in the index.

The Three-Tier Loading Model

Progressive disclosure is the mechanism that resolves the tension. It is not a vague principle; it is a concrete loading sequence with observable consequences at each tier.

Tier 1 — Discovery. Only metadata sits in the system prompt at startup: a name and a description. This is the entire budget the agent spends on a skill it never uses. If you install fifty skills and the agent uses two, you paid for fifty descriptions on every turn and two bodies.

Tier 2 — Activation. The model decides relevance from the description and reads the full SKILL.md body into context. This is the first real cost, and it is paid only when the skill is judged relevant.

Tier 3 — Execution. Supporting files, references, and scripts become available only once the skill is active. Critically, scripts can run without their source ever entering context. The agent invokes the script; the script's output comes back; the source stays on disk.

That third tier is why bundled content can be effectively unbounded in principle. The practical ceiling is filesystem size, access policy, retrieval behavior, and operational maintenance — not the context window. An agent with a filesystem and code execution does not need to read the entirety of a skill to use it.

The cost model is the whole economic argument:

Tier	What loads	When it is paid
Discovery	Name + description	Every turn, for every installed skill
Activation	Full SKILL.md body	Only when the model judges the skill relevant
Execution	Scripts, references, assets	Only when the active skill reaches for them

Tier 1 is a standing tax. Tiers 2 and 3 are usage fees. The asymmetry is the reason a large skill library can be cheaper than a large prompt: you pay rent on the index, not on the whole library.

Where the Package Ends and the Runtime Begins

This three-tier sequence is a common implementation pattern, not a universal protocol. In practice, discovery, activation, file access, tool registration, permissions, and execution may be separate operations performed by different parts of the harness. The distinction matters because it determines what a skill package can guarantee and what only the runtime can enforce.

A skill package can guarantee that its instructions are coherent, its referenced paths resolve, and its scripts are self-contained. It cannot guarantee that the runtime will grant the permissions those scripts need, that the referenced files still exist at execution time, or that the output will be validated before it is acted upon. Those are harness responsibilities.

Capability invariant: An activated skill is usable only when its referenced assets resolve, its required tools and permissions are granted, and every execution produces an attributable result or failure. Routing correctly is necessary but not sufficient.

The trace below shows what happens at each boundary for the release-notes skill:

[Discovery]  System prompt contains:
             name: release-notes
             description: "Use when generating release notes from a git range..."

[Activation] Model judges relevance → reads SKILL.md body into context
             Body references: scripts/collect_commits.py
                              references/changelog-format.md
                              references/breaking-change-policy.md

[Execution]  Model requests: run scripts/collect_commits.py v1.2..HEAD
             Harness checks:  does the path exist? is execution permitted?
                              does the script have repo read access?
             Script runs → structured commit data returned as output
             Source code never enters context

[Verification] Harness or downstream check validates output against
               changelog-format.md before the notes are published

If the harness denies execution permission, the skill activated but cannot complete. If the script runs but the changelog format reference is stale, the output is wrong. If the model never activates the skill, none of this matters. Three different failure layers, three different fixes.

Anatomy of a Skill Directory

The smallest useful skill is a directory with a SKILL.md file. The file begins with YAML frontmatter carrying a name and description, followed by a Markdown body of procedural guidance.

release-notes/
├── SKILL.md
├── references/
│   ├── changelog-format.md
│   └── breaking-change-policy.md
└── scripts/
    └── collect_commits.py

---
name: release-notes
description: Use when generating release notes from a git range, especially before a tagged release or when a changelog entry is missing. Operates on the current repository.
---

# Release Notes

## When this applies
The task involves summarizing changes between two refs, or a release
is being cut and the changelog is stale.

## Procedure
1. Determine the git range. If unspecified, use the last tag to HEAD.
2. Run `scripts/collect_commits.py <range>` to get structured commit data.
   Do not read the script; run it.
3. Classify each change as feature, fix, or breaking. Use
   `references/breaking-change-policy.md` when a change touches a public
   interface.
4. Emit notes in the format defined by `references/changelog-format.md`.

## Termination
Stop when every commit in the range is classified and the output
validates against the changelog format.

Notice what is deliberately not in the body. The changelog format is a reference file, not inlined prose. The commit collection is a script, not a description of how to collect commits. The breaking-change policy is a separate document because it is long and only relevant to a subset of releases.

That is reference awareness: the body points at files the agent has not read, so the agent knows they exist and can pull them in when the task demands it. The body is a table of contents with judgment, not an appendix.

Now consider what happens when this skill fails at the capability invariant. The model activates the skill, reads the body, and requests collect_commits.py. The harness denies execution because the skill's trust tier does not include repo read access. The skill routed correctly, loaded correctly, and still cannot complete. The fix is not in the description or the body — it is in the permission grant. This is why activation bugs and capability bugs must be diagnosed separately.

Writing Descriptions the Model Can Route On

The description is the retrieval key, not a label. The model selects on it with no other signal, so a bad description means the skill either never loads or loads at the wrong time. This is the highest-leverage and most commonly botched part of skill design.

Three failure modes show up repeatedly.

Naming the domain but not the trigger. A description like "Helps with Kubernetes" stays dormant during the exact task it was built for, because the model does not connect "the pods are crashlooping" to a generic domain label. The skill exists and never fires.

Overlapping descriptions across skills. Two skills both described as "handles database issues" produce ambiguous or arbitrary selection. The model has no tiebreaker, so it picks one and hopes.

Descriptions so broad they activate on unrelated work. A skill described as "Use for any code change" will load constantly and burn tier-2 context for nothing.

The practical rules I use:

• Lead with the situation, not the capability. "Use when generating release notes from a git range" beats "Generates release notes."
• Include the observable signal that should trigger the skill. What does the task look like when this skill is the right answer?
• Name the artifact or system it operates on. "Operates on the current repository" tells the model where the skill applies.
• Keep sibling descriptions mutually distinguishable. If two skills could plausibly match the same task, rewrite one.

The diagnostic is straightforward: log which skills activate per task and inspect the misses. A skill that never activates is a description bug before it is a capability bug. Fix the routing before you rewrite the body.

Instructions, Scripts, or Assets: Choosing the Right Carrier

Once a skill is active, you have three carriers for its content, and the choice between them is the core packaging judgment. The decision axis is simple: does this step need judgment, determinism, or volume?

Prose for judgment. Branching, ambiguity, context-dependent choices, anything the model must reason about rather than execute. "If the change touches a public interface, consult the breaking-change policy" is prose because the model has to decide whether the condition holds.

Code for determinism. Parsing, sorting, format conversion, anything where token-by-token generation is both more expensive and less reliable than running a program. Sorting a list via token generation is absurd when a three-line script does it exactly. The script is deterministic; the model's narration of the sort is not.

Assets for volume. Large reference material, schemas, and templates that should be read selectively rather than inlined. A changelog format spec belongs in a reference file because it is long and only sometimes needed.

Scripts occupy a useful middle position: they are both executable and documentation. The agent can run a script without reading it, but the script's existence and purpose still need a one-line description in the body. "Run collect_commits.py; do not read it" is a complete instruction.

And sometimes the right answer is no skill at all. One-off tasks do not need a directory. Capabilities that belong in a tool schema should stay a tool. Procedures so short that a description plus a tool call is already the whole thing are not skills — they are tools wearing a costume.

The carrier test: if the step needs judgment, write prose. If it needs determinism, write code. If it needs volume, write a file and reference it. If it needs none of the three, it probably is not a skill.

One clarification on determinism: a deterministic script produces the same output for the same input, but that says nothing about whether the output is safe or the side effects are acceptable. A script that deletes a production table is perfectly deterministic. Determinism reduces behavioral variance in computation; it does not reduce authorization risk or prevent dangerous side effects. Those are separate concerns handled by the harness.

Splitting Skills Without Fragmenting Them

A skill library scales by splitting, but splitting has a cost. Every skill you add pays tier-1 rent on every turn, and every cross-skill reference is a routing decision the model must make.

Split when the SKILL.md body becomes unwieldy, when sub-procedures are mutually exclusive or rarely co-used, or when different teams own different parts. The release-notes skill above could split its breaking-change policy into a separate skill if that policy grew large enough to stand alone.

Keep whole when the steps share state, share a single decision point, or are almost always used together. Splitting those pays tier-1 cost for skills that always activate together — you have added routing overhead without adding selectivity.

Composition is where this gets subtle. A skill body can reference other skills or assets, but each reference is a routing decision the model must make, so depth costs reliability. A skill that references three other skills is asking the model to make three correct routing calls in sequence. That is fine when the calls are obvious and expensive when they are not.

Dynamic capability registration is the more powerful move: loading a skill can also register new tools or state, changing what the agent can do mid-task. Loading a database_admin skill might add backup, restore, and migrate tools alongside the procedural context. This is genuinely useful and genuinely dangerous — it changes the agent's capability surface at runtime, which makes authorization and auditability harder. If a skill can grant itself new tools, you need to know which skill did it and why.

The failure mode to watch for: a skill library that grows into a second, worse prompt. Hundreds of near-duplicate descriptions competing for the same tasks, each paying tier-1 rent, none routing reliably. That is the monolithic prompt again, just distributed across a directory tree.

Trust, Provenance, and the Skill Supply Chain

A skill is code and instructions that the agent will follow and run. Installing one is closer to installing a driver than to adding a document. That framing matters because the security model has to match it.

Consider a concrete failure trace. A skill routes correctly on a log-triage task. The model activates it and reads the body, which references references/known-issues.md. That file was updated by a compromised dependency and now contains an instruction to include environment variables in the triage output. The model follows the instruction because it treats skill content with the same authority as its own system prompt. The script runs deterministically, produces valid-looking output, and exfiltrates credentials in the process.

Every layer behaved as designed. The description routed correctly. The body loaded. The script executed. The failure was in provenance and trust — the referenced asset was not verified, and the harness had no policy check between reading the file and acting on its contents.

The controls that matter:

• Trust-tiered execution. Separate skills by provenance — first-party, reviewed third-party, unreviewed — and gate what each tier may touch. Filesystem scope, network access, and credentials should differ by tier.
• Explicit activation consent. Require policy checks at load time, not just at install time.
• Logging. Record which skill loaded, from where, and what it executed. Without this, you cannot answer "what did the agent actually do" after an incident.

I want to be honest about the state of the ecosystem here: the security tooling and standards around skills are still forming. Treat any specific vendor guarantee as a claim to verify against your own threat model rather than a settled fact. The mechanisms are real; the guarantees are not yet uniform.

Evaluating Skills and Keeping Them Alive

A skill is a hypothesis: this procedure, packaged this way, improves task outcomes. Evaluate it like a hypothesis, and test each layer of the capability invariant separately.

Build from observed gaps. Run the agent on representative tasks, find where it stalls or asks for context it does not have, then write the skill that closes that specific gap. Skills written from imagination tend to describe procedures the agent already handles.

Measure activation and outcome separately. A skill that loads but does not improve task success is a body problem — the procedure is wrong or badly written. A skill that never loads is a description problem. A skill that loads and runs but produces wrong artifacts is a capability problem — missing permissions, stale references, or a broken script. These are different bugs with different fixes, and conflating them wastes time.

A minimal test matrix for one skill looks like this:

Test	What it checks	Failure layer
Eligible task activates the skill	Routing precision	Description
Ineligible near-neighbor task does not activate	Routing precision	Description
Artifact matches expected format and content	Execution correctness	Body + script
Script runs within granted permissions	Capability invariant	Harness policy
Permission violation is blocked and logged	Safety boundary	Harness policy
Failed execution surfaces an error the agent can recover from	Recovery path	Body + harness
Token and latency cost per task	Economic viability	Tier 1 + Tier 2

Distinguish curated from self-generated. Curated skills and auto-distilled procedures are not equivalent in effect. Research on procedural memory shows that curated skills can substantially improve agent success rates while self-generated skills may degrade them. Treat auto-distilled procedures as candidates that must earn their place through evaluation, not as automatic wins.

Assert on artifacts, not narration. The model will happily report success. Check the file contents, the command output, the schema validity. Deterministic checks on the produced artifact are worth more than any amount of the model's self-assessment.

Maintain the library. Version skills, re-review on dependency change, and prune skills whose tasks no longer occur. An unused skill still charges tier-1 context on every turn. The lifecycle to plan for is discovery, practice, distillation, storage, composition, evaluation, update — and the update step is the one most teams skip.

The Rule and the First Move

Put in the index only what the model needs to decide relevance. Put everything else behind a path.

That single rule resolves most skill-design questions. The description earns its place in the index because it drives routing. The body, the scripts, and the assets do not, because they are only needed once routing has already happened.

The first move is concrete. Take one procedure currently pasted into your system prompt — the release checklist, the log-triage steps, the deploy runbook — and extract it into a skill directory. Write a trigger-shaped description that leads with the situation. Reference the scripts and assets by path instead of inlining them. Then instrument three things: whether the skill activates on the tasks it should, whether the task outcome actually improves, and whether every execution either produces a verifiable artifact or a surfaced failure. If activation is zero, fix the description. If activation is high but outcomes do not move, fix the body. If the body is right but execution fails, check permissions, paths, and harness policy.

The adjacent problem, once skills are running, is enforcement. When a skill's scripts actually execute, the harness has to decide what they are allowed to touch, what happens when they fail, and how the agent recovers. That is where authorization, sandboxing, and recovery policy stop being theoretical and start being the difference between a useful capability and an incident.