From d28dfdc39beadc3142a33359b5cfa4765dcbd0bc Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 15 Aug 2026 20:42:06 +0000 Subject: [PATCH 1/5] Standardize cross-skill invocation on explicit "call the Skill tool" phrasing Bare `/skill`-style prose ("run the `/grilling` skill") relies on the model reading a slash-prefixed name as a command to fire. Naming the tool directly gets a higher hit rate, and it's actually more harness-neutral than the old convention since it drops the Claude-Code-specific `/` trigger syntax entirely rather than assuming it. Updates the documented convention in .agents/invocation.md and every operative cross-skill invocation site in skills/**/SKILL.md to match. Co-Authored-By: Claude --- .agents/invocation.md | 4 +++- skills/engineering/code-review/SKILL.md | 2 +- skills/engineering/diagnosing-bugs/SKILL.md | 2 +- skills/engineering/grill-with-docs/SKILL.md | 2 +- .../improve-codebase-architecture/SKILL.md | 8 ++++---- skills/engineering/tdd/SKILL.md | 2 +- skills/engineering/to-spec/SKILL.md | 2 +- skills/engineering/to-tickets/SKILL.md | 2 +- skills/engineering/triage/SKILL.md | 4 ++-- skills/engineering/wayfinder/SKILL.md | 14 +++++++------- skills/in-progress/claude-handoff/SKILL.md | 2 +- skills/in-progress/setup-ts-deep-modules/SKILL.md | 2 +- skills/productivity/grill-me/SKILL.md | 2 +- skills/productivity/handoff/SKILL.md | 2 +- 14 files changed, 26 insertions(+), 24 deletions(-) diff --git a/.agents/invocation.md b/.agents/invocation.md index 4ed7701..be63af2 100644 --- a/.agents/invocation.md +++ b/.agents/invocation.md @@ -13,7 +13,9 @@ Bucket `README.md`s and the top-level `README.md` group entries into **User-invo ## Dependencies between them -Dependencies are expressed as **`/skill`-style prose invocation** ("Run the `/grilling` skill"), not deep `../other-skill/FILE.md` cross-references. Shared reference docs live inside the skill that owns them; other skills reach that material by invoking the skill, not by linking across folders. +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. + +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. ## Passive vs active domain work diff --git a/skills/engineering/code-review/SKILL.md b/skills/engineering/code-review/SKILL.md index 2d276fe..6c6ab44 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 — run `/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 for `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 7f8acf7..8b7ba88 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 to the `/improve-codebase-architecture` skill 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 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. diff --git a/skills/engineering/grill-with-docs/SKILL.md b/skills/engineering/grill-with-docs/SKILL.md index bed05d2..c225acf 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 --- -Run a `/grilling` session, using the `/domain-modeling` skill. +Call the Skill tool for `grilling` and for `domain-modeling` together, running the interview with the domain-modeling discipline active throughout. diff --git a/skills/engineering/improve-codebase-architecture/SKILL.md b/skills/engineering/improve-codebase-architecture/SKILL.md index 529761a..a01a6df 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: -- Run the `/codebase-design` skill 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 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." - 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, run the `/grilling` skill 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 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. -Side effects happen inline as decisions crystallize — run the `/domain-modeling` skill to keep the domain model current as you go: +Side effects happen inline as decisions crystallize — call the Skill tool for `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?** Run the `/codebase-design` skill and use its design-it-twice parallel sub-agent pattern. +- **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. diff --git a/skills/engineering/tdd/SKILL.md b/skills/engineering/tdd/SKILL.md index ead7781..12529f6 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 — use the `/codebase-design` skill 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 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. ## Anti-patterns diff --git a/skills/engineering/to-spec/SKILL.md b/skills/engineering/to-spec/SKILL.md index 3fd6495..2ee2582 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 — run `/setup-matt-pocock-skills` if not. +The issue tracker and triage label vocabulary should have been provided to you — call the Skill tool for `setup-matt-pocock-skills` if not. ## Process diff --git a/skills/engineering/to-tickets/SKILL.md b/skills/engineering/to-tickets/SKILL.md index 96deac5..98a5b3e 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 — run `/setup-matt-pocock-skills` if not. +The issue tracker and triage label vocabulary should have been provided to you — call the Skill tool for `setup-matt-pocock-skills` if not. ## Process diff --git a/skills/engineering/triage/SKILL.md b/skills/engineering/triage/SKILL.md index e67b7bb..9ea33cb 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 - run `/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 for `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, run the `/grilling` and `/domain-modeling` skills 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 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. 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 e4984ed..77073e4 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 — run `/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 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. ### 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 `/research` **subagent**. 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 via the /prototype skill. 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 invoke the /grilling and /domain-modeling skills. +- **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`. - **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.** Run a `/grilling` and `/domain-modeling` session 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 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. 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 `/research` subagent 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 for `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; invoke the skills the `## Notes` block names. If in doubt, use `/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 for `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/claude-handoff/SKILL.md b/skills/in-progress/claude-handoff/SKILL.md index 69b26bc..b374514 100644 --- a/skills/in-progress/claude-handoff/SKILL.md +++ b/skills/in-progress/claude-handoff/SKILL.md @@ -9,7 +9,7 @@ Write a handoff summary of the current conversation so a fresh agent can continu Always pass `-n`/`--name` with a descriptive name (e.g. `--name "Fix login bug"`) — it sets the display name shown in the job list, session picker, and terminal title. -Include a "suggested skills" section in the summary, which suggests skills that the agent should invoke. +Include a "suggested skills" section in the summary, naming which skills the next agent should call the Skill tool for. Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead. diff --git a/skills/in-progress/setup-ts-deep-modules/SKILL.md b/skills/in-progress/setup-ts-deep-modules/SKILL.md index 5963b8a..834460c 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), run the `/codebase-design` skill — use its language throughout. +For the vocabulary (deep module, interface, seam, depth), call the Skill tool for `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 9470cfc..3d5892b 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 --- -Run a `/grilling` session. +Call the Skill tool for `grilling`. diff --git a/skills/productivity/handoff/SKILL.md b/skills/productivity/handoff/SKILL.md index 043d9e1..2eb98a5 100644 --- a/skills/productivity/handoff/SKILL.md +++ b/skills/productivity/handoff/SKILL.md @@ -7,7 +7,7 @@ disable-model-invocation: true Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace. -Include a "suggested skills" section in the document, which suggests skills that the agent should invoke. +Include a "suggested skills" section in the document, naming which skills the next agent should call the Skill tool for. Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead. From fcf0071560d32913c9d4f820e0d7ca467c881619 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 15 Aug 2026 20:46:38 +0000 Subject: [PATCH 2/5] Switch Skill tool phrasing to `with "name"`, revert grill-with-docs rewording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Matt's preferred form is `Call the Skill tool with "codebase-design"` — quoted string, "with" not "for" — applied consistently everywhere a literal skill name follows. Also reverts an unwanted rewording of grill-with-docs's SKILL.md back to a direct terminology swap of the original sentence, rather than restating what it does. Co-Authored-By: Claude --- .agents/invocation.md | 2 +- skills/engineering/code-review/SKILL.md | 2 +- skills/engineering/diagnosing-bugs/SKILL.md | 2 +- skills/engineering/grill-with-docs/SKILL.md | 2 +- .../improve-codebase-architecture/SKILL.md | 8 ++++---- skills/engineering/tdd/SKILL.md | 2 +- skills/engineering/to-spec/SKILL.md | 2 +- skills/engineering/to-tickets/SKILL.md | 2 +- skills/engineering/triage/SKILL.md | 4 ++-- skills/engineering/wayfinder/SKILL.md | 14 +++++++------- skills/in-progress/setup-ts-deep-modules/SKILL.md | 2 +- skills/productivity/grill-me/SKILL.md | 2 +- 12 files changed, 22 insertions(+), 22 deletions(-) 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". From 447ca70872026d5b79d6073a546dac082117fed7 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 15 Aug 2026 20:48:40 +0000 Subject: [PATCH 3/5] Clarify multi-skill steps as multiple Skill tool calls, not one call with two names "Call the Skill tool with X and Y" reads as a single call taking two arguments, but the tool takes one skill per call. Reworded every two-skill site (grill-with-docs, triage, wayfinder x3) to "Call the Skill tool twice, for X and Y," and added a line to .agents/invocation.md documenting the convention for future skills. Co-Authored-By: Claude --- .agents/invocation.md | 2 ++ skills/engineering/grill-with-docs/SKILL.md | 2 +- skills/engineering/triage/SKILL.md | 2 +- skills/engineering/wayfinder/SKILL.md | 6 +++--- 4 files changed, 7 insertions(+), 5 deletions(-) diff --git a/.agents/invocation.md b/.agents/invocation.md index 7f9016b..d5227f4 100644 --- a/.agents/invocation.md +++ b/.agents/invocation.md @@ -17,6 +17,8 @@ Dependencies are expressed as an explicit instruction to **call the Skill tool** 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. +The Skill tool takes one skill per call. A step that needs two skills is two calls, not one call with two names — say so (`Call the Skill tool twice, for "grilling" and "domain-modeling"`), not "call it with X and Y," which reads as a single call taking both. + ## Passive vs active domain work Merely _reading_ `CONTEXT.md` for vocabulary is a one-line prose pointer, not the `domain-modeling` skill. Only the active build/sharpen discipline (challenge terms, edge-case scenarios, write ADRs, update `CONTEXT.md` inline) is `domain-modeling`. diff --git a/skills/engineering/grill-with-docs/SKILL.md b/skills/engineering/grill-with-docs/SKILL.md index 184113e..62b9efb 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 with "grilling" and "domain-modeling" together. +Call the Skill tool twice, for "grilling" and "domain-modeling". diff --git a/skills/engineering/triage/SKILL.md b/skills/engineering/triage/SKILL.md index 87d98e2..407c04d 100644 --- a/skills/engineering/triage/SKILL.md +++ b/skills/engineering/triage/SKILL.md @@ -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 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. +4. **Grill (if needed).** If the request needs fleshing out, call the Skill tool twice, for "grilling" and "domain-modeling" — 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 0709d99..2a10850 100644 --- a/skills/engineering/wayfinder/SKILL.md +++ b/skills/engineering/wayfinder/SKILL.md @@ -76,7 +76,7 @@ Every ticket is either **HITL** — human in the loop, worked _with_ a human who - **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". +- **Grilling** (HITL): Conversation. The default case. Always call the Skill tool twice, for "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,7 +108,7 @@ 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 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. +1. **Name the destination.** Call the Skill tool twice, 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. 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. @@ -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 with "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 twice, for "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. From e3e547b57d549110a0aa6ff40fd7b871c01c76c9 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 15 Aug 2026 20:55:23 +0000 Subject: [PATCH 4/5] Add changeset; re-sync the two docs pages tied to this bug MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md requires a docs re-sync when a promoted skill's behaviour changes, and a changeset for versioning. Full re-syncs of all ten touched skills' docs pages would be disproportionate for a wording-only change to internal invocation instructions, but two pages specifically document the exact reliability problem this phrasing targets — the "most reported problem" FAQ on grill-with-docs's page, and the matching "rough edge" FAQ on grilling's page, plus a stale literal quote of grill-me's SKILL.md body. Updated those three spots to reflect the new mechanism without overclaiming the bug is fully fixed, and added a changeset summarizing the change across all ten affected skills. Co-Authored-By: Claude --- .changeset/skill-tool-invocation-terminology.md | 9 +++++++++ docs/engineering/grill-with-docs.md | 2 +- docs/productivity/grilling.md | 6 +++--- 3 files changed, 13 insertions(+), 4 deletions(-) create mode 100644 .changeset/skill-tool-invocation-terminology.md diff --git a/.changeset/skill-tool-invocation-terminology.md b/.changeset/skill-tool-invocation-terminology.md new file mode 100644 index 0000000..d570264 --- /dev/null +++ b/.changeset/skill-tool-invocation-terminology.md @@ -0,0 +1,9 @@ +--- +"mattpocock-skills": patch +--- + +Standardize cross-skill invocation on an explicit "call the Skill tool" instruction instead of bare `/skill`-style prose, across `code-review`, `diagnosing-bugs`, `grill-with-docs`, `grill-me`, `improve-codebase-architecture`, `tdd`, `to-spec`, `to-tickets`, `triage`, and `wayfinder`. + +- A skill that names another skill in prose ("run the `/grilling` skill") does not reliably cause it to load — this is the documented rough edge behind `grill-with-docs`'s most-reported problem. Naming the tool directly (`Call the Skill tool with "grilling"`) is intended to raise the hit rate. Dropping the leading `/` also makes the instruction harness-neutral rather than less: it no longer assumes Claude Code's trigger syntax. +- A step needing more than one skill now says so as multiple calls ("Call the Skill tool twice, for `grilling` and `domain-modeling`"), not one call carrying two names. +- Documents the convention in `.agents/invocation.md` for future skills to follow. diff --git a/docs/engineering/grill-with-docs.md b/docs/engineering/grill-with-docs.md index 9f2f28a..8fce5ff 100644 --- a/docs/engineering/grill-with-docs.md +++ b/docs/engineering/grill-with-docs.md @@ -55,7 +55,7 @@ Scope decides it. Use this for anything you can settle in one session; use [wayf Two known causes. The mundane one: nothing qualified. ADRs need all three gates, and a session about a change with no new vocabulary genuinely has nothing to write. The real bug: when the skill runs inside another orchestration layer — a spec-driven-development wrapper, a multi-agent framework, a rule that invokes it as a step in someone else's pipeline — the file-writing half is reported to silently not happen, while the interview still runs. This is filed and unfixed. If you are in that setup, check the working directory before you trust the session's output. **It asked everything at once, with no recommendations, and never mentioned `CONTEXT.md`.** -That is the skill failing to load its two dependencies. Because `SKILL.md` is a one-line delegation, an agent that does not pick up [grilling](https://aihero.dev/skills-grilling) and [domain-modeling](https://aihero.dev/skills-domain-modeling) guesses at what grilling means, and you get an undifferentiated question dump. Partial loading is the more confusing case — `grilling` loads, `domain-modeling` does not, and you get a good interview with no paper trail. It correlates with model and [effort](https://www.aihero.dev/ai-coding-dictionary/effort) level, and it is the most reported problem with this skill. If you suspect it, ask the agent directly which skills it loaded. +That is the skill failing to load its two dependencies. `SKILL.md` is a one-line delegation that now names both explicitly as separate Skill tool calls ("Call the Skill tool twice, for `grilling` and `domain-modeling`") rather than a bare mention, which is intended to raise the hit rate — but an agent that still doesn't pick up [grilling](https://aihero.dev/skills-grilling) and [domain-modeling](https://aihero.dev/skills-domain-modeling) guesses at what grilling means, and you get an undifferentiated question dump. Partial loading is the more confusing case — `grilling` loads, `domain-modeling` does not, and you get a good interview with no paper trail. It correlates with model and [effort](https://www.aihero.dev/ai-coding-dictionary/effort) level, and it has been the most reported problem with this skill. If you suspect it, ask the agent directly which skills it loaded. **Where did all my other decisions go?** Into the conversation only. This is the most substantive open complaint about the skill: the glossary is not a spec, most answers do not earn an ADR, and there is no ledger tying each resolved answer through to a spec, a ticket and a test. Precise answers — ordering guarantees, negative requirements, numeric defaults — get softened into weaker prose downstream, and the result can look complete while missing the thing you actually decided. The mitigation available today is to keep the session and feed it straight to [to-spec](https://aihero.dev/skills-to-spec), and to re-read the spec against your own answers rather than assuming it captured them. diff --git a/docs/productivity/grilling.md b/docs/productivity/grilling.md index 6882c9b..99e8f2e 100644 --- a/docs/productivity/grilling.md +++ b/docs/productivity/grilling.md @@ -16,7 +16,7 @@ Typing `/grilling` directly gets you the plain interview and nothing else. Where | You are in a working directory | [grill-with-docs](https://aihero.dev/skills-grill-with-docs) — the same session, and it writes `CONTEXT.md` and ADRs as it goes | | An effort too big to hold in one session | [wayfinder](https://aihero.dev/skills-wayfinder) — it charts a map and runs grilling inside the decision tickets | | A question that talking cannot settle — how something should look or feel | [prototype](https://aihero.dev/skills-prototype) — build the throwaway version, then come back | -| A skill of your own that needs an interview | Invoke `/grilling` from it, rather than writing another interview | +| A skill of your own that needs an interview | Call the Skill tool with "grilling" from it, rather than writing another interview | ## The round, the frontier, and who decides @@ -67,10 +67,10 @@ That is a bug in the run, not the intended behaviour, and it was the reason fact No, and a cap is deliberately out of scope. Some plans need three questions and some need fifty; a fixed ceiling either truncates the hard case or feels arbitrary on the easy one. Steering in plain language is the intended control — tell it to wrap up, or stop and accept the plan where it stands. If a session is running very long, the cause is usually that the scope was too big; break the work up and grill the pieces. **I installed `grill-me` on its own and nothing happens.** -`grill-me` is a one-line skill whose whole body is "run a `/grilling` session", so it needs this skill installed too. The same is true of `grill-with-docs`, which additionally needs [domain-modeling](https://aihero.dev/skills-domain-modeling). Installing the whole set avoids the problem; installing selectively means installing the primitives as well. +`grill-me` is a one-line skill whose whole body is `Call the Skill tool with "grilling"`, so it needs this skill installed too. The same is true of `grill-with-docs`, which additionally needs [domain-modeling](https://aihero.dev/skills-domain-modeling). Installing the whole set avoids the problem; installing selectively means installing the primitives as well. **`grill-with-docs` ran, but it never loaded `grilling`.** -A real and unfixed rough edge, reported across [harnesses](https://www.aihero.dev/ai-coding-dictionary/harness) and models: a skill that names another skill does not reliably cause that skill to load, and `grill-with-docs` names two. The tell is a session that asks everything at once with no recommendations attached — that is the model improvising an interview rather than running this one. Asking the agent directly whether it loaded `grilling` and `domain-modeling` usually recovers it. +A reported rough edge, seen across [harnesses](https://www.aihero.dev/ai-coding-dictionary/harness) and models: a skill that names another skill in prose does not reliably cause that skill to load, and `grill-with-docs` names two. The skill's body now names both explicitly as separate Skill tool calls ("Call the Skill tool twice, for `grilling` and `domain-modeling`") rather than a bare mention, which is intended to raise the hit rate — but if you still see it, the tell is a session that asks everything at once with no recommendations attached, which is the model improvising an interview rather than running this one. Asking the agent directly whether it loaded `grilling` and `domain-modeling` usually recovers it. ## It's working if From da2cb7d411c02c035c88f0c18047cce0a1934ea3 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 15 Aug 2026 20:59:36 +0000 Subject: [PATCH 5/5] =?UTF-8?q?Revert=20the=20docs=20re-sync=20=E2=80=94?= =?UTF-8?q?=20quoting=20SKILL.md=20text=20and=20narrating=20the=20change?= =?UTF-8?q?=20was=20bad=20documentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The two FAQ edits quoted the literal new SKILL.md instruction text and described "now X, replacing Y, intended to fix Z" — implementation-change narration, exactly what .agents/writing-docs.md's "explain the why, not the process" / "never reproduces the SKILL.md steps" rules argue against. It also duplicates content that lives in SKILL.md, which is precisely what caused the stale quote this PR already had to fix once. That story belongs in the changeset/CHANGELOG, not the docs page. Reverted both files to their pre-PR state; the changeset stays as the record of what changed and why. Co-Authored-By: Claude --- docs/engineering/grill-with-docs.md | 2 +- docs/productivity/grilling.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/engineering/grill-with-docs.md b/docs/engineering/grill-with-docs.md index 8fce5ff..9f2f28a 100644 --- a/docs/engineering/grill-with-docs.md +++ b/docs/engineering/grill-with-docs.md @@ -55,7 +55,7 @@ Scope decides it. Use this for anything you can settle in one session; use [wayf Two known causes. The mundane one: nothing qualified. ADRs need all three gates, and a session about a change with no new vocabulary genuinely has nothing to write. The real bug: when the skill runs inside another orchestration layer — a spec-driven-development wrapper, a multi-agent framework, a rule that invokes it as a step in someone else's pipeline — the file-writing half is reported to silently not happen, while the interview still runs. This is filed and unfixed. If you are in that setup, check the working directory before you trust the session's output. **It asked everything at once, with no recommendations, and never mentioned `CONTEXT.md`.** -That is the skill failing to load its two dependencies. `SKILL.md` is a one-line delegation that now names both explicitly as separate Skill tool calls ("Call the Skill tool twice, for `grilling` and `domain-modeling`") rather than a bare mention, which is intended to raise the hit rate — but an agent that still doesn't pick up [grilling](https://aihero.dev/skills-grilling) and [domain-modeling](https://aihero.dev/skills-domain-modeling) guesses at what grilling means, and you get an undifferentiated question dump. Partial loading is the more confusing case — `grilling` loads, `domain-modeling` does not, and you get a good interview with no paper trail. It correlates with model and [effort](https://www.aihero.dev/ai-coding-dictionary/effort) level, and it has been the most reported problem with this skill. If you suspect it, ask the agent directly which skills it loaded. +That is the skill failing to load its two dependencies. Because `SKILL.md` is a one-line delegation, an agent that does not pick up [grilling](https://aihero.dev/skills-grilling) and [domain-modeling](https://aihero.dev/skills-domain-modeling) guesses at what grilling means, and you get an undifferentiated question dump. Partial loading is the more confusing case — `grilling` loads, `domain-modeling` does not, and you get a good interview with no paper trail. It correlates with model and [effort](https://www.aihero.dev/ai-coding-dictionary/effort) level, and it is the most reported problem with this skill. If you suspect it, ask the agent directly which skills it loaded. **Where did all my other decisions go?** Into the conversation only. This is the most substantive open complaint about the skill: the glossary is not a spec, most answers do not earn an ADR, and there is no ledger tying each resolved answer through to a spec, a ticket and a test. Precise answers — ordering guarantees, negative requirements, numeric defaults — get softened into weaker prose downstream, and the result can look complete while missing the thing you actually decided. The mitigation available today is to keep the session and feed it straight to [to-spec](https://aihero.dev/skills-to-spec), and to re-read the spec against your own answers rather than assuming it captured them. diff --git a/docs/productivity/grilling.md b/docs/productivity/grilling.md index 99e8f2e..6882c9b 100644 --- a/docs/productivity/grilling.md +++ b/docs/productivity/grilling.md @@ -16,7 +16,7 @@ Typing `/grilling` directly gets you the plain interview and nothing else. Where | You are in a working directory | [grill-with-docs](https://aihero.dev/skills-grill-with-docs) — the same session, and it writes `CONTEXT.md` and ADRs as it goes | | An effort too big to hold in one session | [wayfinder](https://aihero.dev/skills-wayfinder) — it charts a map and runs grilling inside the decision tickets | | A question that talking cannot settle — how something should look or feel | [prototype](https://aihero.dev/skills-prototype) — build the throwaway version, then come back | -| A skill of your own that needs an interview | Call the Skill tool with "grilling" from it, rather than writing another interview | +| A skill of your own that needs an interview | Invoke `/grilling` from it, rather than writing another interview | ## The round, the frontier, and who decides @@ -67,10 +67,10 @@ That is a bug in the run, not the intended behaviour, and it was the reason fact No, and a cap is deliberately out of scope. Some plans need three questions and some need fifty; a fixed ceiling either truncates the hard case or feels arbitrary on the easy one. Steering in plain language is the intended control — tell it to wrap up, or stop and accept the plan where it stands. If a session is running very long, the cause is usually that the scope was too big; break the work up and grill the pieces. **I installed `grill-me` on its own and nothing happens.** -`grill-me` is a one-line skill whose whole body is `Call the Skill tool with "grilling"`, so it needs this skill installed too. The same is true of `grill-with-docs`, which additionally needs [domain-modeling](https://aihero.dev/skills-domain-modeling). Installing the whole set avoids the problem; installing selectively means installing the primitives as well. +`grill-me` is a one-line skill whose whole body is "run a `/grilling` session", so it needs this skill installed too. The same is true of `grill-with-docs`, which additionally needs [domain-modeling](https://aihero.dev/skills-domain-modeling). Installing the whole set avoids the problem; installing selectively means installing the primitives as well. **`grill-with-docs` ran, but it never loaded `grilling`.** -A reported rough edge, seen across [harnesses](https://www.aihero.dev/ai-coding-dictionary/harness) and models: a skill that names another skill in prose does not reliably cause that skill to load, and `grill-with-docs` names two. The skill's body now names both explicitly as separate Skill tool calls ("Call the Skill tool twice, for `grilling` and `domain-modeling`") rather than a bare mention, which is intended to raise the hit rate — but if you still see it, the tell is a session that asks everything at once with no recommendations attached, which is the model improvising an interview rather than running this one. Asking the agent directly whether it loaded `grilling` and `domain-modeling` usually recovers it. +A real and unfixed rough edge, reported across [harnesses](https://www.aihero.dev/ai-coding-dictionary/harness) and models: a skill that names another skill does not reliably cause that skill to load, and `grill-with-docs` names two. The tell is a session that asks everything at once with no recommendations attached — that is the model improvising an interview rather than running this one. Asking the agent directly whether it loaded `grilling` and `domain-modeling` usually recovers it. ## It's working if