chore: sync the plugin version from package.json on release

`npm run version` now runs `changeset version` and then
`scripts/sync-plugin-version.mjs`, which copies the new version into
`.claude-plugin/plugin.json`. The release workflow calls `npm run version`
instead of `npx changeset version`, so the version PR carries both files.

Also closes the drift this replaces: `plugin.json` was manually bumped to
1.2.1 while `package.json` stayed at 1.2.0. `package.json` moves up to
1.2.1 so the plugin version never goes backwards.

`npm run check-plugin-version` reports drift without writing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.changeset/writing-for-agents-codex-metadata.md

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

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

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.1",
   "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/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"