diff --git a/.agents/invocation.md b/.agents/invocation.md index be63af2..7f9016b 100644 --- a/.agents/invocation.md +++ b/.agents/invocation.md @@ -13,7 +13,7 @@ Bucket `README.md`s and the top-level `README.md` group entries into **User-invo ## Dependencies between them -Dependencies are expressed as an explicit instruction to **call the Skill tool** for the named skill ("Call the Skill tool for `grilling`"), not deep `../other-skill/FILE.md` cross-references, and not a bare `/skill`-style mention left for the model to interpret. Naming the tool is what gets it fired: most harnesses expose skill invocation as a tool the model calls, and spelling that out gets a higher hit rate than dropping a `/name` into prose and hoping it's read as a command. Dropping the leading `/` also keeps this harness-neutral rather than less — a skill name on its own carries no assumption about which harness's trigger syntax it belongs to. Shared reference docs live inside the skill that owns them; other skills reach that material by calling the Skill tool for it, not by linking across folders. +Dependencies are expressed as an explicit instruction to **call the Skill tool** with the named skill (`Call the Skill tool with "grilling"`), not deep `../other-skill/FILE.md` cross-references, and not a bare `/skill`-style mention left for the model to interpret. Naming the tool is what gets it fired: most harnesses expose skill invocation as a tool the model calls, and spelling that out gets a higher hit rate than dropping a `/name` into prose and hoping it's read as a command. Dropping the leading `/` also keeps this harness-neutral rather than less — a skill name on its own carries no assumption about which harness's trigger syntax it belongs to. Shared reference docs live inside the skill that owns them; other skills reach that material by calling the Skill tool with it, not by linking across folders. This is about **operative** instructions — a skill's own steps telling the agent to go run another skill right now. Router prose that just names skills for a human to pick from (`ask-matt`, bucket `README.md`s) isn't invoking anything, so it keeps `/skill`-style names as plain labels. diff --git a/skills/engineering/code-review/SKILL.md b/skills/engineering/code-review/SKILL.md index 6c6ab44..1d98b8a 100644 --- a/skills/engineering/code-review/SKILL.md +++ b/skills/engineering/code-review/SKILL.md @@ -10,7 +10,7 @@ Two-axis review of the diff between `HEAD` and a fixed point the user supplies: Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings. -The issue tracker should have been provided to you — call the Skill tool for `setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing. +The issue tracker should have been provided to you — call the Skill tool with "setup-matt-pocock-skills" if `docs/agents/issue-tracker.md` is missing. ## Process diff --git a/skills/engineering/diagnosing-bugs/SKILL.md b/skills/engineering/diagnosing-bugs/SKILL.md index 8b7ba88..c2e00af 100644 --- a/skills/engineering/diagnosing-bugs/SKILL.md +++ b/skills/engineering/diagnosing-bugs/SKILL.md @@ -137,4 +137,4 @@ Required before declaring done: - [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location) - [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns -**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off by calling the Skill tool for `improve-codebase-architecture` with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started. +**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off by calling the Skill tool with "improve-codebase-architecture" and the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started. diff --git a/skills/engineering/grill-with-docs/SKILL.md b/skills/engineering/grill-with-docs/SKILL.md index c225acf..184113e 100644 --- a/skills/engineering/grill-with-docs/SKILL.md +++ b/skills/engineering/grill-with-docs/SKILL.md @@ -4,4 +4,4 @@ description: A relentless interview to sharpen a plan or design, which also crea disable-model-invocation: true --- -Call the Skill tool for `grilling` and for `domain-modeling` together, running the interview with the domain-modeling discipline active throughout. +Call the Skill tool with "grilling" and "domain-modeling" together. diff --git a/skills/engineering/improve-codebase-architecture/SKILL.md b/skills/engineering/improve-codebase-architecture/SKILL.md index a01a6df..86c025b 100644 --- a/skills/engineering/improve-codebase-architecture/SKILL.md +++ b/skills/engineering/improve-codebase-architecture/SKILL.md @@ -10,7 +10,7 @@ Surface architectural friction and propose **deepening opportunities** — refac This command is _informed_ by the project's domain model and built on a shared design vocabulary: -- Call the Skill tool for `codebase-design` for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary." +- Call the Skill tool with "codebase-design" for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary." - The domain language in `CONTEXT.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate. ## Process @@ -61,11 +61,11 @@ Do NOT propose interfaces yet. After the file is written, ask the user: "Which o ### 3. Grilling loop -Once the user picks a candidate, call the Skill tool for `grilling` to walk the decision tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive. +Once the user picks a candidate, call the Skill tool with "grilling" to walk the decision tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive. -Side effects happen inline as decisions crystallize — call the Skill tool for `domain-modeling` to keep the domain model current as you go: +Side effects happen inline as decisions crystallize — call the Skill tool with "domain-modeling" to keep the domain model current as you go: - **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. Create the file lazily if it doesn't exist. - **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there. - **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. -- **Want to explore alternative interfaces for the deepened module?** Call the Skill tool for `codebase-design` and use its design-it-twice parallel sub-agent pattern. +- **Want to explore alternative interfaces for the deepened module?** Call the Skill tool with "codebase-design" and use its design-it-twice parallel sub-agent pattern. diff --git a/skills/engineering/tdd/SKILL.md b/skills/engineering/tdd/SKILL.md index 12529f6..d8a6466 100644 --- a/skills/engineering/tdd/SKILL.md +++ b/skills/engineering/tdd/SKILL.md @@ -23,7 +23,7 @@ A **seam** is the public boundary you test at: the interface where you observe b Ask: "What's the public interface, and which seams should we test?" -When the shape of that interface is itself in question — how deep the module is, where the seam belongs, what the interface should expose — call the Skill tool for `codebase-design` for the vocabulary. It is the shared source of the module, interface, depth, seam, adapter, leverage and locality terms, and it is a reference to consult, not a session to run. +When the shape of that interface is itself in question — how deep the module is, where the seam belongs, what the interface should expose — call the Skill tool with "codebase-design" for the vocabulary. It is the shared source of the module, interface, depth, seam, adapter, leverage and locality terms, and it is a reference to consult, not a session to run. ## Anti-patterns diff --git a/skills/engineering/to-spec/SKILL.md b/skills/engineering/to-spec/SKILL.md index 2ee2582..128a6c7 100644 --- a/skills/engineering/to-spec/SKILL.md +++ b/skills/engineering/to-spec/SKILL.md @@ -6,7 +6,7 @@ disable-model-invocation: true This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user — just synthesize what you already know. -The issue tracker and triage label vocabulary should have been provided to you — call the Skill tool for `setup-matt-pocock-skills` if not. +The issue tracker and triage label vocabulary should have been provided to you — call the Skill tool with "setup-matt-pocock-skills" if not. ## Process diff --git a/skills/engineering/to-tickets/SKILL.md b/skills/engineering/to-tickets/SKILL.md index 98a5b3e..d234f98 100644 --- a/skills/engineering/to-tickets/SKILL.md +++ b/skills/engineering/to-tickets/SKILL.md @@ -8,7 +8,7 @@ disable-model-invocation: true Break a plan, spec, or conversation into a set of **tickets** — tracer-bullet vertical slices, each declaring the tickets that **block** it. -The issue tracker and triage label vocabulary should have been provided to you — call the Skill tool for `setup-matt-pocock-skills` if not. +The issue tracker and triage label vocabulary should have been provided to you — call the Skill tool with "setup-matt-pocock-skills" if not. ## Process diff --git a/skills/engineering/triage/SKILL.md b/skills/engineering/triage/SKILL.md index 9ea33cb..87d98e2 100644 --- a/skills/engineering/triage/SKILL.md +++ b/skills/engineering/triage/SKILL.md @@ -40,7 +40,7 @@ For a PR, the same states read against the attached code: `ready-for-agent` mean Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else. -These are canonical role names — the actual label strings used in the issue tracker may differ. The mapping should have been provided to you - call the Skill tool for `setup-matt-pocock-skills` if not. +These are canonical role names — the actual label strings used in the issue tracker may differ. The mapping should have been provided to you - call the Skill tool with "setup-matt-pocock-skills" if not. State transitions: an unlabeled issue normally goes to `needs-triage` first; from there it moves to `needs-info`, `ready-for-agent`, `ready-for-human`, or `wontfix`. `needs-info` returns to `needs-triage` once the reporter replies. The maintainer can override at any time — flag transitions that look unusual and ask before proceeding. @@ -73,7 +73,7 @@ Show counts and a one-line summary per item. Let the maintainer pick. 3. **Verify the claim.** Before any grilling, check that the claim holds up. For a bug, reproduce it from the reporter's steps. For a PR, confirm the diff does what it claims — check it out, run the relevant tests or commands. Report what happened: confirmed (with code path), failed, or insufficient detail (a strong `needs-info` signal). A confirmed verification makes a much stronger agent brief. -4. **Grill (if needed).** If the request needs fleshing out, call the Skill tool for `grilling` and `domain-modeling` together — grill it into shape a round of questions at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land. +4. **Grill (if needed).** If the request needs fleshing out, call the Skill tool with "grilling" and "domain-modeling" together — grill it into shape a round of questions at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land. 5. **Apply the outcome:** - `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)). diff --git a/skills/engineering/wayfinder/SKILL.md b/skills/engineering/wayfinder/SKILL.md index 77073e4..0709d99 100644 --- a/skills/engineering/wayfinder/SKILL.md +++ b/skills/engineering/wayfinder/SKILL.md @@ -22,7 +22,7 @@ The map is a single issue on this repo's issue tracker, labelled `wayfinder:map` The map is an **index**, not a store. It lists the decisions made and points at the tickets that hold their detail; a decision lives in exactly one place — its ticket — so the map never restates it, only gists it and links. -**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you — call the Skill tool for `setup-matt-pocock-skills` if not. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker. +**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you — call the Skill tool with "setup-matt-pocock-skills" if not. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker. ### The map body @@ -74,9 +74,9 @@ The answer isn't part of the body — it's recorded on resolution (see [Work thr Every ticket is either **HITL** — human in the loop, worked _with_ a human who speaks for themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this). -- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a subagent that calls the Skill tool for `research`. Use when knowledge outside the current working directory is required. -- **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code, by calling the Skill tool for `prototype`. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question. -- **Grilling** (HITL): Conversation. The default case. Always call the Skill tool for `grilling` and `domain-modeling`. +- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a subagent that calls the Skill tool with "research". Use when knowledge outside the current working directory is required. +- **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code, by calling the Skill tool with "prototype". Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question. +- **Grilling** (HITL): Conversation. The default case. Always call the Skill tool with "grilling" and "domain-modeling". - **Task** (HITL or AFK): Manual work that must happen before a _decision_ can be made — nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that _does_ rather than decides — and it earns its place by unblocking a decision, not by delivering the destination. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on. ## Fog of war @@ -108,11 +108,11 @@ Two modes. Either way, **never resolve more than one ticket per session** — wi User invokes with a loose idea. -1. **Name the destination.** Call the Skill tool for `grilling` and `domain-modeling` to pin down what this map is finding its way to — the spec, decision, or change. The destination fixes the scope, so it's settled first. +1. **Name the destination.** Call the Skill tool with "grilling" and "domain-modeling" to pin down what this map is finding its way to — the spec, decision, or change. The destination fixes the scope, so it's settled first. 2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** — the way to the destination is already clear, the whole journey small enough for one session — you don't need a map. Stop and ask the user how they'd like to proceed. 3. **Create the map** (label `wayfinder:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**. 4. **Create the tickets you can specify now** as child issues of the map — then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog — the **Not yet specified** section. -5. **Fire the research subagents.** For each `research` ticket you just created, spin up a subagent that calls the Skill tool for `research` to resolve it in parallel, capturing its findings on a throwaway `research/` branch with a context pointer from the ticket. +5. **Fire the research subagents.** For each `research` ticket you just created, spin up a subagent that calls the Skill tool with "research" to resolve it in parallel, capturing its findings on a throwaway `research/` branch with a context pointer from the ticket. 6. Stop — charting is one session's work; it hand-resolves nothing. ### Work through the map @@ -121,7 +121,7 @@ User invokes with a map (URL or number). A ticket is **optional** — without on 1. Load the **map** — the low-res view, not every ticket body. 2. Choose the ticket. If the user named one, use it. Otherwise take the first frontier ticket in order. **Claim it**: assign it to yourself before any work. -3. Resolve it — **zoom as needed**: fetch the full body of any related or closed ticket on demand; call the Skill tool for whichever skills the `## Notes` block names. If in doubt, call the Skill tool for `grilling` and `domain-modeling`. +3. Resolve it — **zoom as needed**: fetch the full body of any related or closed ticket on demand; call the Skill tool for whichever skills the `## Notes` block names. If in doubt, call the Skill tool with "grilling" and "domain-modeling". 4. Record the resolution: post the answer as a **resolution comment**, **close** the issue, and **append a context pointer** to the map's Decisions-so-far. 5. Add newly-surfaced tickets (create-then-wire); graduate any fog the answer has made specifiable, clearing each graduated patch from **Not yet specified** so it lives only as its new ticket. If the answer reveals a ticket — this one or another — sits beyond the destination, **rule it out of scope** rather than resolving it on the route. If the decision invalidates other parts of the map, update or delete those tickets. diff --git a/skills/in-progress/setup-ts-deep-modules/SKILL.md b/skills/in-progress/setup-ts-deep-modules/SKILL.md index 834460c..bf7a6d1 100644 --- a/skills/in-progress/setup-ts-deep-modules/SKILL.md +++ b/skills/in-progress/setup-ts-deep-modules/SKILL.md @@ -8,7 +8,7 @@ disable-model-invocation: true Make every package in this repo a **deep module**: a lot of behaviour behind a small interface. A package's public surface is its **entry points** — the files at the package root — and everything in its subfolders is hidden. This skill installs [dependency-cruiser](https://github.com/sverweij/dependency-cruiser) and the rules that make the entry points the only way in, then proves the rules bite. -For the vocabulary (deep module, interface, seam, depth), call the Skill tool for `codebase-design` — use its language throughout. +For the vocabulary (deep module, interface, seam, depth), call the Skill tool with "codebase-design" — use its language throughout. ## The shape this enforces diff --git a/skills/productivity/grill-me/SKILL.md b/skills/productivity/grill-me/SKILL.md index 3d5892b..3947ff9 100644 --- a/skills/productivity/grill-me/SKILL.md +++ b/skills/productivity/grill-me/SKILL.md @@ -4,4 +4,4 @@ description: A relentless interview to sharpen a plan or design. disable-model-invocation: true --- -Call the Skill tool for `grilling`. +Call the Skill tool with "grilling".