From 14bfbbd8654a8d2910299e1a004c19c1979687d8 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Thu, 6 Aug 2026 13:58:35 +0100 Subject: [PATCH] fix: make subagent dispatch harness-neutral MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three skills named Claude Code's `Agent` tool and its `general-purpose` and `Explore` agent types directly. The repo installs across Claude Code, Codex, and other Agent-Skills harnesses, none of which share that tool or those type names, so the instruction was unfollowable outside Claude Code. Each site now describes the shape of the dispatch — parallel subagents, and what capability each one needs — and leaves the mechanism to the harness. Co-Authored-By: Claude Opus 5 (1M context) --- .changeset/harness-neutral-subagent-language.md | 7 +++++++ skills/engineering/code-review/SKILL.md | 2 +- skills/engineering/codebase-design/DESIGN-IT-TWICE.md | 2 +- skills/engineering/improve-codebase-architecture/SKILL.md | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) create mode 100644 .changeset/harness-neutral-subagent-language.md diff --git a/.changeset/harness-neutral-subagent-language.md b/.changeset/harness-neutral-subagent-language.md new file mode 100644 index 0000000..0490881 --- /dev/null +++ b/.changeset/harness-neutral-subagent-language.md @@ -0,0 +1,7 @@ +--- +"mattpocock-skills": patch +--- + +Make the subagent-dispatch instructions harness-neutral. + +`code-review`, `codebase-design`'s `DESIGN-IT-TWICE.md`, and `improve-codebase-architecture` named Claude Code's `Agent` tool and its `general-purpose` / `Explore` agent types directly. Codex and other Agent-Skills harnesses have no such tool or type, so the instruction was unfollowable there. Each now describes the *shape* of the dispatch — parallel subagents, and what capability each one needs — and leaves the mechanism to the harness. diff --git a/skills/engineering/code-review/SKILL.md b/skills/engineering/code-review/SKILL.md index 62a18e4..d4dedb3 100644 --- a/skills/engineering/code-review/SKILL.md +++ b/skills/engineering/code-review/SKILL.md @@ -57,7 +57,7 @@ Each smell reads *what it is* → *how to fix*; match it against the diff: ### 4. Spawn both sub-agents in parallel -Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both. +Dispatch both with your harness's subagent mechanism, in parallel — one message with two calls where the harness supports it. Pick its most general-purpose agent for both: each must read files and run `git`, so a search-only agent is too narrow. **Standards sub-agent prompt** — include: diff --git a/skills/engineering/codebase-design/DESIGN-IT-TWICE.md b/skills/engineering/codebase-design/DESIGN-IT-TWICE.md index 49a7c42..331e159 100644 --- a/skills/engineering/codebase-design/DESIGN-IT-TWICE.md +++ b/skills/engineering/codebase-design/DESIGN-IT-TWICE.md @@ -18,7 +18,7 @@ Show this to the user, then immediately proceed to Step 2. The user reads and th ### 2. Spawn sub-agents -Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module. +Spawn 3+ sub-agents in parallel with your harness's subagent mechanism. Each must produce a **radically different** interface for the deepened module. Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint: diff --git a/skills/engineering/improve-codebase-architecture/SKILL.md b/skills/engineering/improve-codebase-architecture/SKILL.md index b56969e..20497e9 100644 --- a/skills/engineering/improve-codebase-architecture/SKILL.md +++ b/skills/engineering/improve-codebase-architecture/SKILL.md @@ -24,7 +24,7 @@ This command is _informed_ by the project's domain model and built on a shared d Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first. -Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction: +Then dispatch a subagent to walk the codebase — a read-only exploration agent if your harness has one. Don't follow rigid heuristics — explore organically and note where you experience friction: - Where does understanding one concept require bouncing between many small modules? - Where are modules **shallow** — interface nearly as complex as the implementation?