From 447ca70872026d5b79d6073a546dac082117fed7 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 15 Aug 2026 20:48:40 +0000 Subject: [PATCH] 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.