diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index a509de5..41c5e54 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -13,7 +13,6 @@ "./skills/engineering/prototype", "./skills/engineering/domain-modeling", "./skills/engineering/codebase-design", - "./skills/engineering/decision-mapping", "./skills/productivity/grill-me", "./skills/productivity/grilling", "./skills/productivity/handoff", diff --git a/README.md b/README.md index fb1fea1..0ba0078 100644 --- a/README.md +++ b/README.md @@ -164,7 +164,6 @@ Skills I use daily for code work. - **[tdd](./skills/engineering/tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. - **[domain-modeling](./skills/engineering/domain-modeling/SKILL.md)** — Actively build and sharpen a project's domain model — challenge terms against the glossary, stress-test with edge-case scenarios, and update `CONTEXT.md` and ADRs inline. - **[codebase-design](./skills/engineering/codebase-design/SKILL.md)** — Shared discipline and vocabulary for designing deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. -- **[decision-mapping](./skills/engineering/decision-mapping/SKILL.md)** — Turn a loose idea into a sequenced map of one-session investigation tickets, then drive them to resolution one at a time. ### Productivity diff --git a/skills/engineering/README.md b/skills/engineering/README.md index 21bace5..76d6416 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -23,4 +23,3 @@ Model- or user-reachable (rich trigger phrasing so the model can reach for them) - **[tdd](./tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. - **[domain-modeling](./domain-modeling/SKILL.md)** — Actively build and sharpen a project's domain model — challenge terms, stress-test with scenarios, update `CONTEXT.md` and ADRs inline. - **[codebase-design](./codebase-design/SKILL.md)** — Shared discipline and vocabulary for designing deep modules: small interfaces, clean seams, testable through the interface. -- **[decision-mapping](./decision-mapping/SKILL.md)** — Turn a loose idea into a sequenced map of one-session investigation tickets, then drive them to resolution one at a time. diff --git a/skills/engineering/codebase-design/SKILL.md b/skills/engineering/codebase-design/SKILL.md index db1f10a..16620c2 100644 --- a/skills/engineering/codebase-design/SKILL.md +++ b/skills/engineering/codebase-design/SKILL.md @@ -1,6 +1,6 @@ --- name: codebase-design -description: Shared discipline and vocabulary for designing deep modules — a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, choose between interface alternatives, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary. +description: Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary. --- # Codebase Design diff --git a/skills/engineering/diagnosing-bugs/SKILL.md b/skills/engineering/diagnosing-bugs/SKILL.md index 1ef97c2..f400de7 100644 --- a/skills/engineering/diagnosing-bugs/SKILL.md +++ b/skills/engineering/diagnosing-bugs/SKILL.md @@ -1,6 +1,6 @@ --- name: diagnosing-bugs -description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression. +description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow. --- # Diagnosing Bugs diff --git a/skills/engineering/domain-modeling/SKILL.md b/skills/engineering/domain-modeling/SKILL.md index 221af0d..d0f7e1a 100644 --- a/skills/engineering/domain-modeling/SKILL.md +++ b/skills/engineering/domain-modeling/SKILL.md @@ -1,6 +1,6 @@ --- name: domain-modeling -description: Actively build and sharpen a project's domain model while you design — challenge fuzzy or conflicting terms against the glossary, stress-test concepts with concrete edge-case scenarios, cross-check claims against the code, and update CONTEXT.md and ADRs inline as decisions crystallise. Use when the user wants to refine domain terminology, build a ubiquitous language, pin down what a term really means, record a hard-won architectural decision, or when another skill needs to actively maintain the domain model. +description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model. --- # Domain Modeling diff --git a/skills/engineering/tdd/SKILL.md b/skills/engineering/tdd/SKILL.md index 54f4862..1ce5d21 100644 --- a/skills/engineering/tdd/SKILL.md +++ b/skills/engineering/tdd/SKILL.md @@ -1,6 +1,6 @@ --- name: tdd -description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development. +description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests. --- # Test-Driven Development diff --git a/skills/in-progress/README.md b/skills/in-progress/README.md index eda3fe3..169809f 100644 --- a/skills/in-progress/README.md +++ b/skills/in-progress/README.md @@ -2,6 +2,7 @@ Skills that are still being developed. They're not ready to ship — expect rough edges, breaking changes, and abandoned experiments. They're excluded from the plugin and the top-level README until they graduate to a stable bucket. +- **[decision-mapping](./decision-mapping/SKILL.md)** — Turn a loose idea into a sequenced map of investigation tickets, then drive them to resolution one at a time. User-invoked. - **[review](./review/SKILL.md)** — Review changes since a fixed point along two parallel axes: **Standards** (does the diff follow the repo's coding standards?) and **Spec** (does the diff faithfully implement the originating issue/PRD?). - **[writing-beats](./writing-beats/SKILL.md)** — Shape an article as a journey of beats, choose-your-own-adventure style. Pick a starting beat, write only that beat, then pivot to the next, until the article reaches a natural end. - **[writing-fragments](./writing-fragments/SKILL.md)** — Grilling session that mines you for fragments — heterogeneous nuggets of writing — and appends them to a single document as raw material for a future article. diff --git a/skills/engineering/decision-mapping/SKILL.md b/skills/in-progress/decision-mapping/SKILL.md similarity index 94% rename from skills/engineering/decision-mapping/SKILL.md rename to skills/in-progress/decision-mapping/SKILL.md index 50a63c0..0c42714 100644 --- a/skills/engineering/decision-mapping/SKILL.md +++ b/skills/in-progress/decision-mapping/SKILL.md @@ -1,6 +1,7 @@ --- name: decision-mapping -description: Turn a loose idea into a sequenced map of investigation tickets, then drive them to resolution one at a time. Use when the user's idea is too loose to plan in one sitting, they want to plan prototyping sessions, or resume work on an existing decision map. +description: Turn a loose idea into a sequenced map of investigation tickets, then drive them to resolution one at a time. +disable-model-invocation: true --- This skill is invoked when a loose idea requires more than one agent session to turn into a plan. It creates a stateful decision map in a markdown file, and drives the user through a sequence of tickets to resolve the open questions - which may require either prototyping, research or discussion. diff --git a/skills/productivity/writing-great-skills/SKILL.md b/skills/productivity/writing-great-skills/SKILL.md index beae64e..61abad4 100644 --- a/skills/productivity/writing-great-skills/SKILL.md +++ b/skills/productivity/writing-great-skills/SKILL.md @@ -19,6 +19,14 @@ Pick model-invocation only when the agent must reach the skill on its own, or an When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a **router skill**: one user-invoked skill that names the others and when to reach for each. +## Writing the description + +A model-invoked **description** does two jobs — state what the skill is, and list the **branches** that should trigger it. Every word increases **context load**, so a description earns even harder pruning than the body: + +- **Front-load the skill's leading word** — the description is where it does its invocation work. +- **One trigger per branch.** Synonyms that rename a single branch are **duplication** — "build features using TDD … asks for test-first development" is one branch written twice. Collapse them; keep only genuinely distinct branches. +- **Cut identity that's already in the body.** Keep the description to triggers, plus any "when another skill needs…" reach clause. + ## Information hierarchy A skill is built from two content types — **steps** and **reference** — that mix freely: a skill can be all steps, all reference, or both. The core decision is which to use and where each sits on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material: