chore: version skills

[github-actions]

This PR was opened by the Changesets release GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated.

Releases

mattpocock-skills@1.2.0

Minor Changes

• #551 697d4ce Thanks @mattpocock! - Add Codex metadata alongside each skill's Claude Code frontmatter so the set works in both harnesses without generated copies.

  • Add an agents/openai.yaml beside every SKILL.md with Codex UI metadata (interface.display_name, interface.short_description).
  • Mark every user-invoked skill with policy.allow_implicit_invocation: false, the Codex analog of disable-model-invocation: true, so Codex excludes it from implicit invocation while explicit $skill invocation still works.
  • Document the dual-harness invocation model in .agents/invocation.md, CLAUDE.md, and the promoted-bucket READMEs.
  • Add AGENTS.md as a symlink to CLAUDE.md so Codex reads the same repo instructions.

• #593 0f2bdbd Thanks @mattpocock! - Graduate to-questionnaire out of in-progress/ into the Productivity bucket, so it ships in the plugin. It turns a decision you can't answer alone into a Markdown questionnaire for the one person who can — filled in async, or worked through together in a meeting.

  Its defining move is that it grills you about the send, not the subject: a normal grilling session interrogates the topic, which is exactly what you can't answer here, so the interview asks only who the questionnaire is going to and what you need back, then aims every question at the gap between the two.

  Now wired as a promoted skill — plugin entry, top-level + Productivity READMEs under User-invoked, a docs page at docs/productivity/to-questionnaire.md, and a Standalone route in ask-matt framing it as the inverse of /grill-me (mine someone else, not yourself).

• #680 b3376f8 Thanks @mattpocock! - Graduate wizard out of in-progress/ into the Engineering bucket, so it ships in the plugin. It generates an interactive bash script that walks a human through a manual procedure — third-party setup, a one-off migration, an A→B state transition — opening each URL, saying what to click, capturing the values, and writing them into .env files and GitHub Actions secrets.

  The delightful UX is pre-solved by the bundled template.sh (progress with time-remaining, confirmation gates, cross-platform URL opening including WSL, hidden secret entry, idempotent .env upserts, gh secret/gh variable writes with graceful degradation, closing skip summary). Everything above the STAGES marker is a fixed library that's never hand-edited — the skill's job is only to scope the procedure and author its stages.

  Engineering rather than Productivity: it reads .env*, docker-compose*, framework config and every secrets.*/vars.* reference in .github/workflows/ to scope itself, writes CI secrets, and verifies its output with bash -n and shellcheck.

  Now wired as a promoted skill — plugin entry, top-level + Engineering READMEs under User-invoked, a docs page at docs/engineering/wizard.md, and a Standalone route in ask-matt for the steps only a human can take.

• #593 6bcbcb0 Thanks @mattpocock! - Reshape the prototype skill's logic branch to produce a single shareable HTML file instead of a terminal app. The demo is one self-contained file (plain HTML/CSS/JS, no build, no server) a non-developer can open by double-click and drive in their own domain language: a labelled state panel, always-available free-play buttons, and a set of tabbed guided walkthroughs — each a scenario with the ordered buttons to press underneath it. The portable pure-logic module still lifts into the real code; the HTML shell is the throwaway primary source.

• #488 cdec9f6 Thanks @mattpocock! - Reword how the prototype skill handles its artifacts around a single idea: the prototype is a primary source. Rather than being deleted once it's answered its question, the prototype is captured as runnable evidence on a throwaway branch (prototype/<name>) out of main, with a context pointer to it left on the implementation issue — so the main branch keeps only the validated decision while the exploration stays findable. The answer (verdict + question) is still captured durably in an issue/ADR/commit.

• #536 42a5b70 Thanks @mattpocock! - Ship the skill set as a native Claude Code plugin, listed in Claude Code's official marketplace. You can now subscribe to the promoted skills as a managed, read-only bundle instead of copying editable files:

  claude plugins install mattpocock-skills

  Or, from inside a session:

  /plugin install mattpocock-skills
  

  There is no marketplace to add first — the official marketplace is configured by default.

  .claude-plugin/plugin.json carries the full plugin metadata (version, description, author, license, keywords) and the explicit list of promoted skills. skills.sh remains the universal installer (and the path for Codex and other harnesses today); a native Codex plugin is deferred — see .agents/adr/0002-ship-as-a-claude-code-plugin.md for why.

• #538 2602257 Thanks @mattpocock! - Wayfinder now burns research tickets down with subagents instead of leaving them parked for a separately-launched session.

  Research stays a real ticket type — it's a genuine shared blocker that downstream decisions hang on, and that dependency is exactly what the frontier's blocking edges exist to render. What changes is how it's resolved: because research is AFK, charting doesn't stop and read it. After creating the tickets, the charting session fires a /research subagent for each research ticket to burn it down in parallel, capturing the findings on a throwaway research/<name> branch with a context pointer. Research tickets are the one exception to one ticket per session.

• #593 f054def Thanks @mattpocock! - Extend writing-for-agents' pruning section with a new leading word: cache. Single source of truth now reaches past the document into the environment — package.json scripts, config files, directory layout, --help output are themselves authoritative, so a doc that restates them is a cache of a lookup, earning its load only when the lookup is expensive. The positive target: cache what the agent cannot find by looking (unwritten conventions, the reason behind a choice, gotchas no config confesses), and leave one-file, one-command lookups to the environment, where they cannot go stale.

• #593 1fc6573 Thanks @mattpocock! - Breaking: rename writing-great-skills → writing-for-agents and restructure it. The reference now covers any document an agent consumes — skills, AGENTS.md / CLAUDE.md, docs reached by a pointer — not just skills. GLOSSARY.md is merged into SKILL.md (one authoritative treatment per term; the _Avoid_ synonym lists and the standalone Predictability definition are gone); the skill-only mechanics (frontmatter, model- vs user-invoked, router skills, the invocation cut of splitting) are disclosed to a new SKILL-MECHANICS.md. The skill is now model-invoked: it fires when creating or editing skills or modifying AGENTS.md/CLAUDE.md. ask-matt's pointer updated. Reinstall under the new name; the old name is gone (no alias).

• #533 45afd80 Thanks @mattpocock! - Add a YAGNI scoping filter to the improve-codebase-architecture skill's Explore step. Instead of scanning the whole repo evenly, it now scopes to where change is actually landing: if you name a direction it takes it, otherwise it reads the last ~20 commit messages to bias exploration toward actively-developed paths. A deepening opportunity in code nobody touches is a refactor you'll never cash in — the leverage only pays off where you keep editing — so the report stops tidying dormant corners of the repo.

Patch Changes

• #750 fa1e322 Thanks @mattpocock! - Give /ask-matt the phase boundary decision tree, replacing the two-bullet Crossing sessions section.

  A phase is a chunk of work inside a session — the grilling, the implementation, the QA — and the boundary between two of them is where you decide what to do with the context you've built. The router now carries all five options in order (continue, /clear, /handoff, subagent, /compact), with the ordered tree and its reasoning disclosed in a new PHASE-BOUNDARIES.md. Three fixes come with it:

  • /handoff was oversold. It read as the general bridge between context windows. It's narrow: you need it only when something has to travel — a new harness, a new directory, a colleague, or a side task forked mid-phase. What it buys is portability.
  • /compact is the default, not the first reach. It sits at the bottom of the tree, after the four cheaper or more precise questions above it. Starting there produces a session that's confidently wrong about whatever the summary flattened.
  • Two branches were missing entirely. Continue is the one to rule out first — it's the only move that keeps the conversation as a primary source rather than a summary of one — and a subagent handles anything scoped tightly enough to run AFK.

  Context hygiene's escape hatch now says /compact rather than /handoff (same harness, same directory, at a boundary — the handoff clause doesn't apply), and the smart zone figure is updated from ~120k to ~150k tokens.

• #535 e74fee8 Thanks @mattpocock! - Make /ask-matt clued-up about /wayfinder — the heaviest, most cognitively demanding flow.

  The router now sharpens the two routing mistakes people most often make with wayfinder:

  • Over-reaching for it. It's slower and denser than a single grill, so it's flagged as the heaviest flow and reserved for the idea that genuinely won't fit one session — a well-scoped feature belongs on /grill-with-docs, not here.
  • Losing the way at the handoff. When the map clears, wayfinder hands off, it doesn't build: merge onto the main flow at /to-spec (which collapses the map's linked decisions into a buildable plan) rather than looping the map straight into /implement. Straight-to-/implement is only for efforts that turned out genuinely small.

• #502 44eed54 Thanks @mattpocock! - Make /setup-matt-pocock-skills friendlier and align the local-markdown tracker with the current spec.

  • Triage labels are now asked about only when the triage skill is installed, and then as a single recommended-yes question ("keep the default triage labels?") instead of an override interrogation. When triage isn't installed, the section — and docs/agents/triage-labels.md — are skipped.
  • External PRs as a request surface is no longer a setup question. The GitHub/GitLab templates still carry the flag, defaulted off; a user can flip it in docs/agents/issue-tracker.md later.
  • Domain docs default to single-context without asking; multi-context is only offered when the repo shows monorepo signals.
  • Local-markdown tickets are now one file per ticket under .scratch/<feature>/issues/<NN>-<slug>.md — never a single combined tickets.md. /to-tickets and the local issue-tracker template now agree, and the spec file is spec.md (not PRD.md) to match /to-spec.

  Docs pages for setup-matt-pocock-skills and to-tickets re-synced.

• #532 170ad48 Thanks @mattpocock! - Reword grilling for general use. Its description and body no longer scope the interview to a software plan: "this plan" → "this", "enact the plan" → "act on it", and "exploring the codebase" → "exploring the environment". The technique is unchanged; it now reads as a stress-test of any plan, decision, or idea.

• #593 294a2c9 Thanks @mattpocock! - Pin the question format in grilling. Every question in a round is now emitted in one fixed shape — ❓ **Q1** - **<title>**, then the body (prose or multiple choices), then the recommendation on its own ➡️ line. A round reads as a scannable numbered list with each recommendation visually separated from the question, so you can answer by number instead of quoting questions back.

• #593 a4b2009 Thanks @mattpocock! - Rework grilling from one-question-at-a-time to round-by-round. It now maps the decision tree and asks the whole frontier — every question whose prerequisites are already settled — in a single numbered round, then recomputes the frontier from the user's answers and asks the next round. Same 13 questions land in ~3 rounds instead of 13. Facts the environment can answer are dispatched to background sub-agents so research never blocks the round: only questions downstream of a running exploration wait for it. The session ends when the frontier is empty.

• #593 bfdaef8 Thanks @mattpocock! - Sync the skills and docs that still described grilling as a one-question-at-a-time interview. Since the round-by-round rework, grill-me, grill-with-docs and triage all run the frontier a round at a time — their pages, triage's grill step and grilling's Codex short_description now say so. The opt-out for the old rhythm (a line in your global CLAUDE.md) is unchanged.

• #734 a2f9333 Thanks @mattpocock! - Finish the to-prd → to-spec rename: "spec" is now the only term in the shipped text.

  • to-spec no longer opens with "you may know this document as a PRD" — the parenthetical is dropped from the skill and its docs page. The local-markdown tracker template drops the same hedge.
  • code-review talks about the originating issue/spec rather than issue/PRD, in its frontmatter description, its two-axis summary, and the spec-source search order. Both READMEs re-synced.
  • The GitHub and GitLab tracker templates now say "Issues and specs for this repo live as GitHub/GitLab issues" — they had been left on "PRDs" when the local template was updated, so the stale term propagated into every repo they were written into.
  • docs/engineering/research.md pointed at https://aihero.dev/skills-to-prd, a dead slug for the renamed skill; it now links to-spec like the other nineteen docs pages do.

  The CHANGELOG and existing changesets still name PRDs where they document the rename itself, which is correct.

• #534 7d694b7 Thanks @mattpocock! - Name the /wayfinder unit a decision ticket.

  People kept reading a wayfinder ticket as an ordinary implementation ticket — a slice of a build to execute — when wayfinder uses them as decision tickets: questions whose resolution is a decision. The skill description and its opening line now introduce "decision ticket" (and say what makes it one), and the ask-matt / engineering README wayfinder blurbs and the docs page match — while "ticket" stays the everyday word once the term is established. CONTEXT.md records Decision ticket as a domain term so the "avoid: ticket" guidance no longer contradicts wayfinder's deliberate use of the word.