fix: cut the added prose back to the bare instruction

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) <noreply@anthropic.com>

.changeset/harness-neutral-subagent-language.md

@@ -0,0 +1,5 @@
+---
+"mattpocock-skills": patch
+---
+
+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.

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mattpocock-skills",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Matt Pocock's agent skills for real engineering — grilling, spec/ticket flows, TDD, code review, domain modelling and more. Plug-and-play, not vibe coding.",
   "author": {
     "name": "Matt Pocock",

.github/workflows/release.yml

@@ -29,7 +29,7 @@ jobs:
       - name: Create Version Pull Request
         uses: changesets/action@v1
         with:
-          version: npx changeset version
+          version: npm run version
           publish: npx changeset tag
           commit: "chore: version skills"
           title: "chore: version skills"

CHANGELOG.md

@@ -1,5 +1,15 @@
 # mattpocock-skills
 
+## 1.2.2
+
+### Patch Changes
+
+- [#766](https://github.com/mattpocock/skills/pull/766) [`4aaccb5`](https://github.com/mattpocock/skills/commit/4aaccb58d40559d7e3c59a029b2290ae5ba538de) Thanks [@mattpocock](https://github.com/mattpocock)! - Make `writing-for-agents` model-invokable in Codex again.
+
+  - Drop `policy.allow_implicit_invocation: false` from `agents/openai.yaml`. Codex filtered the skill out of the model-visible skills list, so its description could not trigger it — only an explicit `$writing-for-agents` mention worked.
+  - Update the stale `interface.display_name` and `interface.short_description`, which still named the old `writing-great-skills` skill.
+  - Move the skill from the **User-invoked** list to the **Model-invoked** list in `README.md` and `skills/productivity/README.md`.
+
 ## 1.2.0
 
 ### Minor Changes

CLAUDE.md

@@ -8,7 +8,7 @@ Skills are organized into bucket folders under `skills/`:
 
 Every skill in `engineering/` or `productivity/` (the **promoted** buckets) must have a reference in the top-level `README.md` and an entry in `.claude-plugin/plugin.json`'s `skills` array (the Claude Code plugin ships exactly the promoted set). Skills in `misc/`, `in-progress/`, and `deprecated/` must not appear in either.
 
-Install commands are copied verbatim from [.agents/install-block.md](./.agents/install-block.md). `.claude-plugin/marketplace.json` makes the repo its own single-plugin marketplace — a fallback the install block explains, not the documented route. When bumping the release version, keep `.claude-plugin/plugin.json`'s `version` in sync with `package.json`'s — Claude uses the plugin `version` to decide when installed users see an update. Run `claude plugin validate . --strict` after touching either manifest. Why a Claude plugin but not (yet) a Codex one lives in [.agents/adr/0002-ship-as-a-claude-code-plugin.md](./.agents/adr/0002-ship-as-a-claude-code-plugin.md).
+Install commands are copied verbatim from [.agents/install-block.md](./.agents/install-block.md). `.claude-plugin/marketplace.json` makes the repo its own single-plugin marketplace — a fallback the install block explains, not the documented route. Run `claude plugin validate . --strict` after touching either manifest. Why a Claude plugin but not (yet) a Codex one lives in [.agents/adr/0002-ship-as-a-claude-code-plugin.md](./.agents/adr/0002-ship-as-a-claude-code-plugin.md).
 
 Each skill entry in the top-level `README.md` must link the skill name to its `SKILL.md`.
 

README.md

@@ -224,8 +224,8 @@ General workflow tools, not code-specific.
 - **[teach](./skills/productivity/teach/SKILL.md)** — Teach the user a new skill or concept over multiple sessions, using the current directory as a stateful teaching workspace.
 - **[to-questionnaire](./skills/productivity/to-questionnaire/SKILL.md)** — Turn a decision you can't answer alone into a Markdown questionnaire for the one person who can — filled in async, or together over a meeting. It grills you about the send (who it's for, what you need back), not the subject.
 - **[wait-what](./skills/productivity/wait-what/SKILL.md)** — Fire this the moment a message doesn't land. The agent re-pitches it with the context you're missing, in plain English, using your `CONTEXT.md` vocabulary.
-- **[writing-for-agents](./skills/productivity/writing-for-agents/SKILL.md)** — Writing documents for agents: skills, AGENTS.md/CLAUDE.md, and any doc an agent reaches by a pointer.
 
 **Model-invoked**
 
 - **[grilling](./skills/productivity/grilling/SKILL.md)** — Interview the user relentlessly about a plan, decision, or idea until every branch of the design tree is resolved. The reusable interview primitive behind `grill-me`, `grill-with-docs`, `triage`, `wayfinder` and `improve-codebase-architecture`.
+- **[writing-for-agents](./skills/productivity/writing-for-agents/SKILL.md)** — Writing documents for agents: skills, AGENTS.md/CLAUDE.md, and any doc an agent reaches by a pointer.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "mattpocock-skills",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "private": true,
   "description": "Matt Pocock's agent skills for real engineering",
   "repository": {
@@ -10,7 +10,8 @@
   "license": "MIT",
   "scripts": {
     "changeset": "changeset",
-    "version": "changeset version"
+    "version": "changeset version && node scripts/sync-plugin-version.mjs",
+    "check-plugin-version": "node scripts/sync-plugin-version.mjs --check"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.7.0",

scripts/sync-plugin-version.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// Copies package.json's version into .claude-plugin/plugin.json.
+// Runs as part of `npm run version`, immediately after `changeset version`.
+// With --check it changes nothing and exits 1 if the two versions differ.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repo = join(dirname(fileURLToPath(import.meta.url)), "..");
+const pluginPath = join(repo, ".claude-plugin", "plugin.json");
+
+const { version } = JSON.parse(readFileSync(join(repo, "package.json"), "utf8"));
+const source = readFileSync(pluginPath, "utf8");
+const plugin = JSON.parse(source);
+
+if (plugin.version === version) {
+  console.log(`plugin.json version is ${version} — already in sync`);
+  process.exit(0);
+}
+
+if (process.argv.includes("--check")) {
+  console.error(
+    `plugin.json version is ${plugin.version}, package.json is ${version}. Run \`node scripts/sync-plugin-version.mjs\`.`,
+  );
+  process.exit(1);
+}
+
+// Rewrite only the version line, to keep the key order and the formatting.
+const updated = source.replace(
+  /("version"\s*:\s*")[^"]*(")/,
+  `$1${version}$2`,
+);
+
+if (JSON.parse(updated).version !== version) {
+  console.error(`Could not find a version field to replace in ${pluginPath}.`);
+  process.exit(1);
+}
+
+writeFileSync(pluginPath, updated);
+console.log(`plugin.json version ${plugin.version} -> ${version}`);

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
 
-Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both.
-
 **Standards sub-agent prompt** — include:
 
 - The full diff command and commit list.

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. 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:
 

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 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?

skills/productivity/README.md

@@ -11,10 +11,10 @@ Reachable only when you type them (Claude Code: `disable-model-invocation: true`
 - **[teach](./teach/SKILL.md)** — Teach the user a new skill or concept over multiple sessions, using the current directory as a stateful teaching workspace.
 - **[to-questionnaire](./to-questionnaire/SKILL.md)** — Turn a decision you can't answer alone into a Markdown questionnaire for the one person who can — filled in async, or together over a meeting.
 - **[wait-what](./wait-what/SKILL.md)** — Fire this the moment a message doesn't land. The agent re-pitches it with the context you're missing, in plain English, using your `CONTEXT.md` vocabulary.
-- **[writing-for-agents](./writing-for-agents/SKILL.md)** — Writing documents for agents: skills, AGENTS.md/CLAUDE.md, and any doc an agent reaches by a pointer.
 
 ## Model-invoked
 
 Model- or user-reachable (rich trigger phrasing so the model can reach for them).
 
 - **[grilling](./grilling/SKILL.md)** — Interview the user relentlessly about a plan, decision, or idea until every branch of the design tree is resolved.
+- **[writing-for-agents](./writing-for-agents/SKILL.md)** — Writing documents for agents: skills, AGENTS.md/CLAUDE.md, and any doc an agent reaches by a pointer.

skills/productivity/writing-for-agents/agents/openai.yaml

@@ -1,5 +1,3 @@
 interface:
-  display_name: "Writing Great Skills"
-  short_description: "Principles for predictable skills"
-policy:
-  allow_implicit_invocation: false
+  display_name: "Writing for Agents"
+  short_description: "Write documents agents consume"