Minimal Skill Surface

The structural discipline for a lean skill: think of a skill as composed of two units — steps (the step-by-step procedure) and reference (supporting material the steps need) — and keep the main SKILL.md as small as possible, pushing everything that isn't always needed out behind context pointers. Every skill is description → SKILL.md → reference material; the description is itself a context pointer into SKILL.md, and SKILL.md can point further out. Smaller skills are easier to maintain and audit, and — because SKILL.md is loaded on invocation — every word shaved is a token shaved from every use.

The lever for shrinking it is branch analysis: identify the different ways a skill can be used. Reference material needed on every branch stays inline; reference needed on only one branch of a multi-branch skill is moved to a separate markdown file inside the skill folder and reached via a context pointer ("if you need the template, go to this file") — the source calls this an external reference. It's still bundled with the skill so the agent can pull it in easily, but it no longer costs context on the branches that don't use it. Worked examples: /to-prd has a single branch and always needs its "test seam" note and PRD template, so both stay inline; domain-modeling has two-or-three branches, so its ADR and context.md templates move out behind pointers. This is progressive disclosure applied inside a skill.

Claims

Model a skill as two units — steps (procedure) and reference (supporting material) — and authoring/refactoring gets much easier. best practice — context: writing or breaking down a skill; a skill can be all-steps, all-reference, or both, but naming the units clarifies what belongs where.
Keep SKILL.md as small as possible: smaller skills are easier to maintain and audit, and every word shaved is a token shaved from every invocation. best practice — context: skills that recur in the token budget; "small" is instrumentally best (maintenance + cost), not smallness for its own sake, so don't cut load-bearing steps or reference.
Reference material used on only one branch of a multi-branch skill should move out behind a context pointer ("external reference"); reference used on every branch stays inline. best practice — context: multi-branch skills; for a single-branch skill everything belongs inline, so the technique only pays when usage genuinely forks.
A skill's description and its external references are context pointers — the agent loads them only when it needs them — so progressive disclosure is the default mechanism for keeping the loaded surface minimal. principle — durable: deferring optional context behind a pointer, rather than inlining it, is how you hold the loaded surface down without losing the material.
Smallness is reachable by optimization, not only by taste — an automated optimizer gated on held-out score converges on a compact artifact (SkillOpt reports 300–2,000 tokens). observation — an independent route to the same place: Text-Space Optimization arrives at a small skill because bloat that doesn't improve the score gets deleted, where this page arrives there by branch analysis. Two routes converging is corroboration for the smallness thesis.
A skill can earn its place by naming a recurring step even when it is near-trivial — lean on the agent's priors and the harness rather than spelling out procedure. best practice — context: a second source's deliberately tiny /implement skill (implement the spec/ticket, TDD at pre-agreed seams, run checks, then call code-review) that the author "almost didn't make." Its value is legibility of the flow, not new instruction; contingent on the step being genuinely well-covered by priors — a novel or error-prone step still needs its steps written down.
Demote guidance that shouldn't drive to reference-material-only, so an AFK agent isn't walked through steps it should just execute. best practice — context: the same author's TDD skill, cut from a prescribed step sequence to red-green reference material (refactoring moved out to code-review). A skill that over-specifies procedure fights the agent when the procedure is already known; the fix is to state the order/principle and drop the walk-through. This is a Skill Pruning move motivated by loaded-surface, not just token cost.

Text-Space Optimization — smallness as an optimization outcome rather than an authoring discipline; the deployed artifact is small because unhelpful text was gated out.
Skill Artifact Transfer — a small artifact is one you can read, audit, and port by hand; smallness and portability reinforce each other.
Skill Invocation Trigger — the description is the outermost context pointer; the same progressive-disclosure mechanism governs invocation.
Context Routing — "point to where things live; don't load what you weren't pointed to" is routing at the store scale; external references are the same move inside a skill.
Concise Prompting — "cut the redundant procedure" at the prompt scale is the same minimalism as shaving SKILL.md.
Agentic Simplicity — the parent discipline: keep the surface only as large as the task demands.
Skill Pruning — the maintenance pass that keeps the surface minimal once bloat creeps in.
Skill Authoring Checklist — pillar 2 (Structure).
Distillate: Building Great Agent Skills: The Missing Manual
Distillate: microsoft/SkillOpt — training skills like weights, without touching weights — corroborates smallness from the optimization side: a 300–2,000-token best_skill.md is what survives a held-out gate.
Distillate: Skills v1.1: Wayfinder, the SDLC flow, and naming the artifact right — a deliberately tiny /implement skill that names the flow without adding instruction, and a TDD skill demoted to reference-material-only.
Context Smart Zone — what every shaved token is shaved from: the loaded surface is charged against the usable band, not the advertised window, so the budget it competes for is smaller than it looks.
Repo-Local Capability Binding — the environment-specific half pushed out of SKILL.md entirely: the skill names an abstract verb, a repo-local doc binds it. Keeps the skill both small and portable.
Distillate: The whole flow, end-to-end: the smart zone is the unit of work — the discipline measured on screen: a 9-skill library loading at 660 tokens because the descriptions are "quite short and precise."

Minimal Skill Surface

Claims

Related

Linked from