Add design-skill skill

skills/design-skill/GLOSSARY.md

@@ -0,0 +1,303 @@
+# Glossary — Structural Predictability
+
+The domain model for what makes an Agent Skill structurally predictable.
+A skill exists to wrangle determinism out of a stochastic system.
+The root virtue is **Predictability**, and every term below is a lever on it.
+This is the disclosed reference for [`design-skill`](SKILL.md).
+
+The terms are grouped by axis: **Invocation** (how a skill is reached), **Information Hierarchy** (how its content is arranged), **Steering** (how the agent's runtime behaviour is shaped), and **Pruning** (how it is kept lean).
+Each **failure mode** lives beside the lever that cures it, tagged _failure mode_.
+
+**Bold terms** in any definition are themselves defined in this glossary.
+Find them by their heading.
+
+## Predictability
+
+The degree to which a skill makes the agent behave the same _way_ on every run — the same process, not the same output.
+A brainstorming skill should _predictably_ diverge because its tokens vary while its behaviour does not.
+The root virtue every other term serves — cost and maintainability are symptoms of it, not rivals.
+
+_Avoid_: consistency, reliability, robustness, output-determinism
+
+## Invocation
+
+How a skill is reached — and the two loads you pay for the choice.
+
+### Model-Invoked
+
+A skill exposed to the model's available-skills index so the agent can discover and load it autonomously.
+The human can still invoke it directly, so model-invocation always includes user reach.
+It pays permanent **context load** in exchange for discoverability.
+A model-invoked skill whose content is all **reference** can provide shared reference to other discoverable skills.
+Pick model-invocation only when the agent must reach the skill on its own.
+
+_Avoid_: ability, tool, capability
+
+### User-Invoked
+
+A skill hidden from autonomous model discovery and reached deliberately by the human through the target harness's invocation mechanism.
+It trades agent discoverability for zero **context load**.
+Agent Skills still require a **description**, so use a documented harness control such as `disable-model-invocation` rather than deleting required metadata.
+If the target harness cannot hide a skill from model discovery, report that user-only invocation is unsupported rather than inventing a mechanism.
+
+_Avoid_: procedure, workflow, command
+
+### Description
+
+Required Agent Skills metadata stating what the skill does and when it applies.
+For a **model-invoked** skill, it is the top-level **context pointer** kept in the model's available-skills index and the source of that skill's **context load**.
+For a **user-invoked** skill, it remains valid metadata but the harness keeps it out of the model's index.
+
+_Avoid_: frontmatter, summary
+
+### Context Pointer
+
+A reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it.
+The **description** is the top-level context pointer from the context window to the skill.
+Pointers to disclosed files are the same object one level down.
+Its wording, not the target, decides _when_ the agent reaches — and _how reliably_.
+A must-have target behind a weakly worded pointer is a variance bug: fix the wording first, and inline the material only if sharpening fails.
+
+_Avoid_: link, reference, import
+
+### Context Load
+
+The cost a **model-invoked** skill imposes on the agent's context window through its indexed **description**, spending both tokens and attention.
+A **user-invoked** skill escapes this load because the harness does not expose its description to the model.
+Context load is the brake on splitting behavior into more model-invoked skills.
+
+_Avoid_: token cost, context bloat
+
+### Cognitive Load
+
+The cost a **user-invoked** skill imposes on the human — what they must hold in their head: which skills exist and when to reach for each (the human is the index).
+What **model-invocation** removes by being agent-discoverable, and the brake on splitting into more user-invoked skills.
+It is not a cost to minimise.
+It is the price of human agency and the reason some skills stay user-invoked.
+Spend it where human judgement matters.
+Remove it where it does not.
+
+_Avoid_: human index, burden, overhead
+
+### Router Skill
+
+A **user-invoked** skill whose job is to name other user-invoked skills and explain when the human should reach for each one.
+It gives the human one entry point to remember instead of many.
+It can only direct the human toward skills hidden from model discovery, not make those skills autonomously discoverable.
+It is the cure for **cognitive load** when user-invoked skills multiply.
+
+_Avoid_: dispatcher, menu, registry, index, router procedure
+
+### Granularity
+
+How finely you divide skills.
+Finer division spends one of the two loads.
+More **model-invoked** skills spend **context load** as more descriptions crowd the window and compete for attention.
+More **user-invoked** skills spend **cognitive load** by giving the human more to remember and reach for.
+Two cuts guide the division.
+By **invocation**, split off a model-invoked skill where you have a distinct **leading word** to trigger it — a trigger word you actually use in your prompts.
+By **sequence**, split a run of **steps** where a step's **post-completion steps** need hiding, since isolating it in its own context clears what follows.
+Beware the reverse: merging sequences exposes each step's post-completion steps to what follows, inviting premature completion.
+
+_Avoid_: chunking, modularity
+
+## Information Hierarchy
+
+How a skill's content is arranged, and how far down the ladder each piece sits.
+
+### Information Hierarchy
+
+A skill's content ranked by how immediately the agent needs it — a single ladder, produced by two cuts: in-file or behind a pointer, and step or reference.
+The rungs:
+
+- **Steps** — in-file, primary
+- **Reference**, in-file — secondary
+- **Reference**, disclosed — behind a **context pointer**
+
+A skill with no **steps** uses just the bottom two rungs — often a legitimately flat peer-set (e.g. every rule of a review on one rung), which is a fine arrangement, not a smell.
+The hierarchy is independent of invocation: a skill can be model- or user-invoked whether it is all steps, all reference, or both.
+When a skill has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip — a variance lever, not just a legibility one.
+Keep the top of the ladder legible.
+Push down it whatever you can.
+
+_Avoid_: structure, organization, layout
+
+### Steps
+
+The ordered actions the agent performs — when a skill has them, the primary tier of its content, and the part that earns its place in SKILL.md.
+Not every skill has steps: a skill can be all steps (`test-driven-development`), all **reference** (a review), or both, independent of invocation.
+Every step ends on a **completion criterion**, clear or vague.
+
+_Avoid_: workflow, instructions, choreography
+
+### Reference
+
+Material the agent refers to on demand — definitions, facts, parameters, examples, conditional instructions.
+When a skill has **steps**, reference is secondary to them.
+When a skill has none, reference is the entire content.
+Reference can also live outside any skill entirely under **External Reference**.
+Reached via **context pointers**, and the prime candidate for **progressive disclosure**.
+
+_Avoid_: supporting material, docs, background
+
+### External Reference
+
+**Reference** that lives outside the skill system as a plain, non-invocable file with no **description** or **steps**.
+Any skill can point at it.
+It is the home for shared reference that need not fire on its own and can be used by skills hidden from one another's discovery surface.
+
+_Avoid_: doc, resource, knowledge base
+
+### Progressive Disclosure
+
+Moving **reference** down the ladder — out of SKILL.md and behind a **context pointer** — so the top stays legible.
+It is not primarily a token optimisation.
+It is how the **information hierarchy** is protected.
+Licensed by **branching**: disclose what only some branches need, inline what every path needs, and if a pointer fires unreliably on must-have material, sharpen its wording, and pull it back inline only if that fails.
+
+_Avoid_: lazy loading, chunking
+
+### Co-location
+
+Keeping the material an agent needs at once in one place — a concept's definition, rules, and caveats under a single heading, not scattered across the file — so reading one part brings its neighbours with it.
+The within-file companion to the **Information Hierarchy**.
+The hierarchy ranks _how far down_ a piece sits, while co-location decides _what sits beside it_ once there.
+There is no formula for the right format of a body of **reference**.
+The test is that a skill should read like documentation written for the agent, and grouped material reads that way where scattered material does not.
+Distinct from **Duplication**: that repeats one meaning in two places, where scattering fragments a single meaning across many.
+
+_Avoid_: grouping, clustering, cohesion
+
+### Sprawl
+
+_Failure mode._ A skill that is simply too long — too many lines in SKILL.md — independent of whether they are stale or repeated.
+Even an all-live, all-unique skill can sprawl.
+It costs readability (the agent wades through more before it can act, and attention thins across the excess), maintainability (every extra line is one more to keep **relevant**), and tokens.
+The cure is the **information hierarchy**: push **reference** down behind **context pointers**, and split by **branch** or sequence so each path carries only what it needs.
+Distinct from **sediment** (length from stale accumulation) and **duplication** (length from repeated meaning) — sprawl is length itself, whatever its cause.
+
+_Avoid_: bloat, length, size, verbosity
+
+## Steering
+
+The levers that shape the agent's runtime behaviour toward **Predictability**.
+
+### Branch
+
+A distinct way a skill can be invoked — a case the skill handles — so different runs take different paths through it.
+A skill with many steps may carry many branches.
+A linear one has none.
+
+_Avoid_: path, case, fork
+
+### Leading Word
+
+A compact concept — also called a _Leitwort_ — already living in the model's pretraining, that the agent thinks with while running the skill.
+It encodes a behavioural principle in the fewest possible tokens by invoking priors the model already holds, such as _lesson_, _proximal zone of development_, _fog of war_, or _tracer bullets_.
+Repeated as a token, never as a sentence, it accumulates a distributed definition across the skill and anchors a whole region of behaviour.
+Coining your own works if you define it clearly, but a made-up word recruits no priors — you pay in definition tokens what a pretrained word gives free.
+Reach for an existing word first.
+
+A leading word serves **predictability** twice.
+In the body it anchors **execution** — the agent reaches for the same behaviour every time the concept appears, and inside flat reference it focuses attention on a class of thing to look for, recruiting the right checks each run.
+In the **description** it anchors **invocation** — and not only within the skill: when the same word lives in your prompts, your docs, and your codebase, the agent links that shared language to the skill and fires it more reliably.
+Word a description with the leading words you actually use when you want the skill.
+
+_Avoid_: keyword, term, motif
+
+### Completion Criterion
+
+The condition that tells the agent a unit of work is done — the target it judges against.
+Two properties make it a lever, not just a quality.
+Its **clarity** asks whether the agent can tell done from not done.
+Clarity resists **premature completion** because a vague bound such as "understanding reached" lets the agent declare done and slip to the next step.
+This axis needs _steps_ to bite because premature completion is a between-steps failure.
+Its **demand** (how much it requires) sets **legwork** — "every modified model accounted for" forces thorough work where "produce a change list" does not — and this axis is _not_ step-bound: it can bind a body of flat reference too, which is how a skill with no steps still carries an exhaustiveness bar ("every rule applied").
+The strongest criteria are both checkable and exhaustive.
+
+_Avoid_: done condition, exit condition, stopping rule
+
+### Legwork
+
+The work an agent does behind the scenes within a single step — reading files, exploring the codebase, making changes, digging up what it needs rather than offloading to the user.
+It lives below the step structure: never written as its own step, latent in the wording, controlled by the agent rather than the skill.
+The within-step counterpart to **post-completion steps**' across-step pull.
+Raised by a **leading word** (_comprehensive_, _thorough_) or a **completion criterion** that demands the work be exhaustive — including the demand axis applied to flat reference, which is what drives a skill of flat reference to cover all its rungs.
+Goes thin either when that demand is missing or when **premature completion** cuts the step short.
+
+_Avoid_: scope, effort, diligence, coverage
+
+### Post-Completion Steps
+
+The **steps** that follow the current step.
+Visible post-completion steps pull the agent forward into **premature completion**.
+The more it sees, the stronger the tug.
+The defence is to hide them by splitting the sequence of steps into two.
+
+_Avoid_: horizon, fog of war, lookahead
+
+### Premature Completion
+
+_Failure mode._ Ending the current step before it is genuinely done, because the agent's attention slips to being done rather than to the work.
+A between-steps failure: it needs **steps** to occur — a skill with no steps that quits early isn't premature completion but thin **legwork** under an unmet demand.
+It is a tug-of-war between visible **post-completion steps**, which pull forward, and the **completion criterion**'s clarity, which resists that pull.
+A sharp, checkable bar holds while a vague one gives way.
+Fuzziness is the necessary condition: a sharp bound resists the pull no matter how many later steps are visible, so a step that never rushes needs no defending.
+Two levers hold a step that does, but reach for them in order: **sharpen the bound first** — it is local and cheap.
+Only when the criterion is irreducibly fuzzy _and_ you actually observe the rush do you **hide the later steps**.
+Hiding works only across a real context boundary such as a user-invoked hand-off or a subagent dispatch.
+An inline model-invoked call leaves the later steps in context and clears nothing.
+One cause of thin legwork, but distinct from it: legwork can be thin even when a step runs to full completion.
+
+_Avoid_: premature closure, the rush, rushing, shortcutting
+
+## Pruning
+
+Keeping a skill lean — each remedy paired with the failure it cures.
+
+### Single Source of Truth
+
+The desired state where each meaning lives in exactly one authoritative place, so a change to the skill's behaviour is a change in one place.
+**Duplication** is its violation.
+
+_Avoid_: home, canonical location
+
+### Duplication
+
+_Failure mode._ The same meaning given more than one **single source of truth**.
+It costs maintenance (change one place, you must change the others), costs tokens, and inflates prominence — repeating a meaning weights it on the ladder past its real rank.
+The accidental inverse of a **leading word**, which raises attention on purpose by repeating a token, never the meaning.
+
+_Avoid_: repetition, redundancy
+
+### Relevance
+
+Whether a line still bears on what the skill does — the lens for what to keep.
+A line loses relevance either by never bearing on the task (mere exposition, or a **branch** that should be disclosed) or by going stale: drifting out of date as the behaviour or world it describes changes.
+Shorter skills are easier to keep relevant, because each line is cheaper to check.
+Distinct from **no-op**: relevance asks whether a line bears on the task, not whether it changes behaviour.
+
+_Avoid_: load-bearing, staleness, freshness
+
+### Sediment
+
+_Failure mode._ Layers of old content that settle in a skill and are never cleared, because adding feels safe and removing feels risky — so stale and irrelevant lines accumulate and you must core down through them to find what is still live.
+This is the default fate of any skill without a pruning discipline.
+It is the slow erosion of **relevance**, as opposed to **duplication**'s repeated meaning.
+
+_Avoid_: accretion, bloat, cruft, rot
+
+### No-Op
+
+_Failure mode._ An instruction that changes nothing because the model already does it by default — you pay load to tell the agent what it would do anyway.
+The test: does a line change behaviour versus the default?
+A line can be perfectly **relevant** and still be a no-op.
+The same priors that make a **leading word** free make a no-op worthless.
+
+A leading word is a _technique_, while No-Op is a _verdict_ on a line.
+The two concepts cross.
+A leading word too weak to beat the default is a no-op (_be thorough_ when the agent is already thorough-ish), and the fix is a stronger word that passes the verdict (_relentless_), not a different technique.
+So the No-Op test — does it change behaviour versus the default? — is also how you grade whether a leading word is earning its repetitions.
+This is model-relative, not reader-relative: two people disagreeing over whether a line is a no-op disagree about the default, and settle it by running the skill, not by debate.
+
+_Avoid_: redundant instruction, restating the obvious, belaboring

skills/design-skill/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: design-skill
+description: Draft a new Agent Skill, or audit and rewrite an existing one for structural predictability. Run deliberately as /skill:design-skill when designing or improving a skill, never automatically.
+disable-model-invocation: true
+---
+
+# design-skill
+
+Draft a new Agent Skill or audit and rewrite an existing one against one bar: **predictability**, meaning that the agent follows the same process on every run.
+This skill judges structural predictability only.
+It does not judge general prose quality, safety, or technical correctness.
+
+**Bold terms** are defined in [`GLOSSARY.md`](GLOSSARY.md).
+Read the relevant definitions before applying them.
+
+## Select the branch
+
+Use **Draft a new skill** when the request describes a new capability or repeated process with no existing skill to modify.
+Use **Audit an existing skill** when the request names an existing skill to review, fix, or improve.
+
+Both branches end at **Verify**.
+
+## Draft a new skill
+
+### 1. Capture intent
+
+Extract every answer already settled by the conversation or target project before asking anything.
+Ask one question at a time only for missing decisions:
+
+- Is the skill a **procedure**, **reference**, or both?
+- Should it be model-invoked or user-invoked?
+  Walk the **context load** and **cognitive load** trade-off rather than defaulting.
+- What distinct **branches** take genuinely different paths?
+- Does project documentation already own any required material?
+  Point to that **external reference** instead of duplicating it.
+- What checkable **completion criterion** ends each step?
+- Does the project already use a **leading word** for the behavior?
+
+Done when every item is settled or the user explicitly asks for a draft to iterate on.
+
+### 2. Resolve the canonical source
+
+Read the target project's instructions and inspect its repository structure before choosing a destination.
+Prefer an existing Agent Skills source convention.
+For a project-specific skill, use the project's canonical project-local skill source.
+For a general skill, use the personal collection named by the user or project instructions.
+
+Do not edit generated, installed, vendored, or compatibility surfaces as source.
+When the discovered skill is a link or generated placement, trace it to its canonical source.
+If multiple plausible sources remain, ask which one owns the skill.
+
+Done when the destination is writable, authoritative, and inside the intended project or collection.
+
+### 3. Write the skill
+
+Use the Agent Skills standard as the baseline:
+
+- Put the skill in a directory containing `SKILL.md`.
+- Give the frontmatter a valid `name` and a specific `description`.
+- Use documented harness extensions only when the target environment supports them.
+- Keep paths relative to the skill directory.
+
+Follow the **information hierarchy**.
+Keep ordered **steps** in `SKILL.md`, keep reference needed by every branch nearby, and disclose branch-specific or extensive reference through precise pointers.
+Reuse authoritative project documentation rather than restating it.
+Every branch must have a complete path, every step must have a checkable completion criterion, and every sentence must pass the **no-op** test.
+
+Done when the skill conforms to the target project's conventions and every captured decision has one authoritative expression.
+
+## Audit an existing skill
+
+### 1. Locate and read it
+
+Read the target project's instructions, locate the named skill, and trace generated or linked placements to their canonical source.
+Ask only when multiple plausible canonical sources remain.
+Read `SKILL.md`, every file it discloses, and any project documentation it treats as authoritative.
+
+Done when the full design and its source-of-truth boundaries are visible.
+
+### 2. Apply the predictability checklist
+
+Check every relevant definition in `GLOSSARY.md` and quote the exact offending passage for each finding:
+
+- **Premature completion**: does each step end on a checkable criterion demanding all required work?
+- **Duplication**: does any meaning have more than one source of truth?
+- **Sediment**: does any sentence no longer bear on the skill's behavior?
+- **Sprawl**: should reference be disclosed or a genuine branch be separated?
+- **No-op**: does each sentence change model behavior from the default?
+- **Invocation**: does the chosen invocation mode fit actual use and target-harness support?
+- **Leading word**: can repeated explanation collapse into established vocabulary?
+
+Judge sentence by sentence rather than line by line.
+A line may contain both a load-bearing sentence and a no-op sentence.
+Do not expand the audit into general writing, safety, or technical review.
+
+Done when every glossary failure mode has been checked and every finding has quoted evidence.
+
+### 3. Rewrite it
+
+Rewrite the canonical source to address every finding.
+Preserve intentional behavior that passed the checklist.
+Follow target-project instructions for any change outside the skill directory.
+
+Done when every finding is fixed or explicitly retained with a structural reason.
+
+## Verify
+
+### 1. Run deterministic checks
+
+Run the target project's required checks and any available Agent Skills validator.
+At minimum, verify frontmatter, naming, relative references, disclosed-file existence, and invocation compatibility with the target harness.
+Do not claim a check ran when its tooling is unavailable.
+
+Done when every available deterministic check passes or a concrete limitation is reported.
+
+### 2. Smoke-test behavior
+
+Derive one realistic prompt from the request and the skill's intended trigger phrasing.
+When the harness supports isolated subagents or equivalent clean runs, run the prompt once with the skill and inspect whether the agent followed the intended branch, hesitated, misread an instruction, or behaved unexpectedly.
+A smoke test does not require advance approval.
+If no isolated execution mechanism exists, report that limitation rather than treating self-review as behavioral evidence.
+
+Done when the smoke test succeeds without structural confusion or its unavailable mechanism is reported.
+
+### 3. Offer stronger verification when available
+
+Detect whether the target project has an established behavioral test or benchmark convention for skills.
+Use existing persistent tests when present.
+Create a persistent test only when project instructions require one.
+
+Before running a stochastic, repeated, paid, or otherwise substantial benchmark, show the user the proposed scenario and obtain approval.
+If approval is declined, retain the smoke-test result as the weaker evidence level.
+
+Done when an approved benchmark passes, the user declines it, or no established benchmark exists.
+
+### 4. Re-audit and finish
+
+Re-read the final skill against every applicable `GLOSSARY.md` failure mode in light of verification.
+Fix every new finding and repeat affected checks after a substantial fix.
+Follow explicit user or project instructions for staging or other version-control actions.
+Otherwise leave changes unstaged and report every changed path.
+Never commit unless explicitly instructed.
+
+Done when no structural finding remains, required checks pass, behavioral confidence is stated accurately, and changed paths are reported.