Guideline: name the foundational skill principle — "Know that; fetch how" (context engineering for agent performance)

[jlevy]

Summary

The cli-agent-skill-patterns guideline already gestures at one unifying idea in several places — "route, don't restate" (§6.5), "the skill points; the CLI documents," progressive disclosure (§3.1), and the §11 summary — but it never names the principle those rules all descend from. Naming it (and stating it as item zero) would give every other rule in the guideline a single thesis to hang from, and give authors one test to apply.

This issue proposes that principle, framed correctly as a performance principle (context engineering for better agent decisions), not a maintenance one.

The principle

It's the agent-era fusion of three known ideas — progressive disclosure (the loading mechanism), single source of truth / DRY (each fact in one place), and information hiding (the skill is the header; the tool's --help is the implementation). What's new is that the agent's working context is the scarce resource, which turns these design ideas into an attention-economics principle.

Crucially, the rationale is output quality, not byte cost or staleness:

• Cognitive-load / attention dilution — irrelevant detail in context competes for the same attention the agent needs for the task. More loaded ≠ more capable; often the reverse.
• "Lost in the middle" / context rot — models attend worse to information buried in a large context. Inlining a manual doesn't just waste budget — it makes the agent reason worse about everything.

Even with an infinite context window, dumping the full manual into a skill would still be wrong — because it lowers the signal-to-noise of the working context, and that's what the agent's reasoning runs on. (The maintenance/DRY benefit is a real but incidental byproduct — skills can be regenerated anytime.)

Statement

Maximize relevance density of the working context. At every step the agent's active context should be the smallest set that keeps it both aware (no blind spots) and undistracted (no irrelevant detail) — then deliver detail just-in-time, exactly when it becomes relevant to the current action.

Operational slogan

Know that; fetch how. Awareness is always-on because it's nearly free and prevents blind action. Detail is fetched at the moment of use because, loaded early, it dilutes attention and degrades reasoning.

(Maps to Ryle's knowing-that vs knowing-how; structurally identical to RAG — the description is the retrieval key, the body is retrieved on demand. Mnemonic: the skill is the index, not the book — a card catalog is tiny and always on the desk; you pull the book only when you need it.)

The author test (relevance + timing, not staleness)

For every line, ask: does the agent need this now, to act → route to it (so it arrives when relevant and doesn't dilute the rest); or only to know the capability exists → keep it (it's the awareness that prevents a blind spot).

The two failure modes (both are performance failures)

• Awareness debt — the agent doesn't know what it doesn't know; acts blind → wrong/incomplete results. (Under-documentation.)
• Context dilution — the inlined manual spreads the agent's attention thin; it loses the thread and reasons worse → degraded results. Not primarily a cost problem — a quality problem. (Over-documentation.)

The discipline is to drive both toward zero at once: complete awareness, near-zero resident detail, detail on tap. That's what "minimal context, maximal awareness" actually optimizes — the agent's decisions, not the repo's tidiness.

Concrete suggestion

Add a short §0.0 "The principle: Know that; fetch how" at the very top of cli-agent-skill-patterns (before the §0 simple baseline), containing:

1. The one-line statement + the slogan.
2. The "even with an infinite window…" rationale (cognitive load + lost-in-the-middle), explicitly noting the maintenance benefit is a byproduct.
3. The author test (now/act → route; aware-only → keep).
4. The two named failure modes (awareness debt, context dilution) so reviewers can cite them by name.

Then thread the vocabulary through the existing rules: relabel §6.5 "route, don't restate" and §3.1 progressive disclosure as consequences of §0.0, and add "awareness debt / context dilution" to the §11 summary and §12 checklist as the two things to check for.

Why now / evidence

This came out of reviewing three shipped vendor skill bundles (Clerk, Render, Convex) against the guideline. Both failure modes show up in the wild:

• Context dilution: clerk-cli/SKILL.md carries a ~25-row command/flag table despite its own "--help is the source of truth" disclaimer; render-cli keeps a command table in the body and re-transcribes it in references/command-cheatsheet.md.
• Awareness debt: thin descriptions that under-index for activation (e.g. Convex's router; several Render skills with single-line descriptions and no trigger terms), so the agent never learns the capability is relevant.

Naming the principle gives authors a single lens that catches both at review time.

I'm happy to open a PR with the §0.0 draft + the threaded edits if this direction looks right.