From c0d69015e0cc8b66715beb3f93f9e53256e20f30 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Thu, 6 Aug 2026 14:12:30 +0100 Subject: [PATCH] fix: cut the added prose back to the bare instruction MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The first pass replaced Claude Code's tool names with an explanation of what the harness should supply. "Your harness's subagent mechanism" is a wordy restatement of "subagent", and the note about which agent type to pick is a no-op — the agent picks a capable one by default. Say only what changes behaviour: "spawn 3+ sub-agents in parallel". In code-review the sentence goes entirely, because its heading already carries the instruction. Co-Authored-By: Claude Opus 5 (1M context) --- .changeset/harness-neutral-subagent-language.md | 4 +--- 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, 3 insertions(+), 7 deletions(-) diff --git a/.changeset/harness-neutral-subagent-language.md b/.changeset/harness-neutral-subagent-language.md index 0490881..3e4db73 100644 --- a/.changeset/harness-neutral-subagent-language.md +++ b/.changeset/harness-neutral-subagent-language.md @@ -2,6 +2,4 @@ "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. +Drop Claude Code's tool and agent-type names from the subagent-dispatch instructions in `code-review`, `codebase-design`, and `improve-codebase-architecture`, so the step is followable on Codex and other harnesses. diff --git a/skills/engineering/code-review/SKILL.md b/skills/engineering/code-review/SKILL.md index d4dedb3..2d276fe 100644 --- a/skills/engineering/code-review/SKILL.md +++ b/skills/engineering/code-review/SKILL.md @@ -57,8 +57,6 @@ Each smell reads *what it is* → *how to fix*; match it against the diff: ### 4. Spawn both sub-agents in parallel -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: - The full diff command and commit list. diff --git a/skills/engineering/codebase-design/DESIGN-IT-TWICE.md b/skills/engineering/codebase-design/DESIGN-IT-TWICE.md index 331e159..8419ad6 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 with your harness's subagent mechanism. Each must produce a **radically different** interface for the deepened module. +Spawn 3+ sub-agents in parallel. 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 20497e9..529761a 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 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: +Then spawn a sub-agent to walk the codebase. 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?