`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>
The docs pages carried 36 attributed opinions — "Matt's own answer",
"his position is", quoted replies from the author. A page is a
technical document about a skill, so the substance of each finding
stays and the attribution goes: "the fix is a direct instruction: …",
"the split comes down to session count".
Quotes from *users* stay, anonymous as they already were — those are
evidence about the skill in the wild rather than the author's view.
Records the rule in .agents/writing-docs.md so new pages don't
reintroduce it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The rename from writing-great-skills moved agents/openai.yaml without
updating it. Codex filters a skill out of the model-visible skills list
when policy.allow_implicit_invocation is false, so the description could
not trigger the skill — only an explicit $writing-for-agents mention.
Drop the policy block (implicit invocation defaults to true) and correct
the stale display_name and short_description. Move the skill into the
Model-invoked list in both READMEs, where the frontmatter already put it.
Closesmattpocock/skills#748
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Mirrors how the personal wiki is referenced: read
~/repos/ai/ai-coding-dictionary/dictionary/ where it exists, and fall
back to GitHub where it doesn't.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
writing-docs.md now tells doc authors to prefer the dictionary's word
over an invented synonym, and to link each term's first use on the page.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Every docs page now links the first occurrence of each AI Coding
Dictionary term to its entry on aihero.dev. 202 links across 25 pages,
one link per term per page. Prose is unchanged — only links added.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The intro spent a paragraph arguing when not to use the skill. Replace it
with what the skill actually is: the agent writes the script, you run it.
Cut the agent-browser question and the closing guard for the same reason,
and plain up the densest sentences.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Removes the five docs-page-only changesets (quickstart drop, grill-me pass,
four-section spine, rewrite-to-standard, writing-for-agents pass) — the
changelog reports on the shipped skills, not on the site pages.
Merges the clusters that describe one change each: ask-matt routing,
the grilling round-by-round rework, prototype, wayfinder, wizard and
writing-for-agents. 27 changesets become 15.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The agent can now reach for wizard the moment it hits a step only a
human can perform, instead of writing numbered instructions into the
chat. Typing /wizard is unaffected — model-invocation only adds the
agent's reach.
The description is rewritten as the pointer that decides when it fires:
a short statement of the artifact, four trigger branches, and an
explicit non-trigger for steps the agent can perform itself.
Behaviour is unchanged — same name, same template.sh, same four process
steps, same stage-list confirmation, which now doubles as the proposal
when the agent fires it mid-build.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ask-matt is written last, against the final state of the other 21 pages.
It stays a node rather than redrawing the graph the skill itself holds.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Coherence pass over the rewritten docs set. The recurring defect was a
refactor whose removals landed and whose replacements did not.
- tdd: restore the pointer to /codebase-design that the v1.0 changelog
and ask-matt both claim exists. The inline deep-module notes were
deleted then; nothing replaced them.
- ask-matt: /grilling and /resolving-merge-conflicts were missing from
the router entirely. Split grill-me from grill-with-docs on the
working directory rather than on whether the subject is code.
- READMEs: wayfinder maps decision tickets, not investigation tickets;
the diagnosing-bugs loop starts by building a loop that goes red;
improve-codebase-architecture is a survey, not a rescue; grilling
resolves a design tree and is the primitive behind five skills.
- Drop the /implement reliability claim from the implement and tdd
pages.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
One agent per page, each rewriting from its SKILL.md up and running its
own evidence hunt across the wiki, the issue tracker and the unreleased
changesets. Question counts track the evidence: wayfinder earns ten,
resolving-merge-conflicts earns three.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Encode a new rule in writing-docs.md: a multi-way branch goes in a table
or a list, never a paragraph the reader has to read in full.
- to-spec: trigger becomes a table; stop implying the tracker must be
remote, since local markdown is supported out of the box.
- prototype: wayfinder is the largest consumer (prototype is one of its
four decision-ticket types); the ask-matt handoff round trip is
demoted to one line.
- handoff: trigger becomes a table; dead prose throughout.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ask-matt still told the agent to 'keep the answer, delete the code',
which prototype-primary-source made false — the prototype is kept on a
prototype/<name> branch and pointed at from the implementation issue.
Both READMEs still called the logic artifact a runnable terminal app;
it is a single shareable HTML file.
The old page read as session resumption, which is why people skip the
skill. Leads with portability rather than compression, names branching
as the use that gets missed, and is honest that /compact wins most
phase boundaries. Nine observed questions, compact-vs-clear-vs-handoff
first.
The old page still said the prototype gets deleted and the logic branch
builds a terminal app; both changed. Leads with throwaway-as-a-writing-
constraint, carries the primary-source branch rule, and answers the two
behaviour changes plus the recommend-by-name failure (#384).
Leads with the defining constraint — it synthesises, it does not
interview — and carries nine observed questions: the to-prd rename, the
ready-for-agent rough edge (#606), why not skip the spec, what to feed
it after a wayfinder map, and the refactor-shaped-work limitation.
An observed question still beats an invented one and the hunt is still
mandatory, but a thin skill may carry a question a reader would plainly
ask. The count stays honest to the evidence rather than padding every
page out to match a richer one.
grill-with-docs is a shim that runs grilling using domain-modeling, so
the two are one route, not two.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Rewrite the extinguisher/sprinkler framing as plain prose across the
docs page, the changeset and the ask-matt router line.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
An audit of all 25 docs pages found the two sections that carry the most
weight are the two the standard treated as optional. Only grill-me has a
Common questions section. Twelve pages have no It's working if, and
several that do use it for compliance checks on the skill's internals
rather than for signals the reader can see.
writing-docs.md now names the four-section spine, gates Common questions
on evidence -- the personal wiki where it exists on the machine, this
repo's issues, and CHANGELOG.md -- and raises the It's working if bar to
"checkable without opening SKILL.md". CLAUDE.md names the four sections
in the pointer.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Every docs page opened with a [Source](github.com/...) link, and
.agents/writing-docs.md told agents to add one to each new page.
Remove the line from all 25 pages, rewrite the one inline use in
ask-matt.md, and drop the rule from the page template, the fixed
frame list, and the "Done when" list so the links do not come back.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The page described grill-me as operating on an existing plan and sitting
at the front of the build chain. Both are wrong. It takes a loose idea,
not a plan, and it is a productivity skill rather than an engineering
one: stateless, so it needs no repo and does not assume the subject is
software at all.
Routing now keys on portability rather than on whether a codebase
exists, and Where it fits names it a standalone that runs anywhere on
anything. Handing off to to-spec is presented as an option for when the
idea turns out to be software, not as the purpose of the skill.
The old page explained the mechanism and stopped. It answered none of
the questions people actually ask: which grilling skill to reach for,
how many questions is normal, what to do with a question talking can't
settle, whether to clear context before to-spec.
Keep the mechanism short and spend the page on judgement instead:
three-way sibling routing keyed on what you have in front of you; a
section naming passivity as the main failure mode; grillable vs
ungrillable as the move for questions that need a prototype; an
"It's working if" list; and a "Common questions" section answering the
six highest-volume ones. Say plainly to leave plan mode off.
Sourced from user questions across X, Discord and YouTube.
aihero.dev renders an install widget above every skill page. Each page
then repeated the same commands in its body, and the two copies had
drifted: the widget uses the current `npx skills@latest ...` wording
while the hand-written blocks mostly carried the older bare `npx skills
...`. Pages showed the right command and a stale one together.
Delete the block from all 25 pages and record the rule in
.agents/writing-docs.md: install wording belongs to the site, not the
page. The template no longer carries a Quickstart, and
.agents/install-block.md notes that docs pages are not one of its
consumers.
Moves the skill out of in-progress/ and ships it: bucket README,
top-level README, plugin.json, an ask-matt router entry, and a docs
page at docs/productivity/wait-what.md.
Productivity rather than engineering — it fires in any conversation
with an agent, code or not. The CONTEXT.md clause is an opportunistic
hook, not a prerequisite.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Delete the four skills in deprecated/ — design-an-interface, qa,
request-refactor-plan, ubiquitous-language — each already absorbed by a
promoted skill. The bucket itself stays, now empty: a retired skill is
deleted, and the changeset that removes it names its replacement.
Delete edit-article and obsidian-vault along with the personal/ bucket.
obsidian-vault hardcoded a path to Matt's own vault and was
model-invocable, so any skills.sh user could have had it fire on them.
None of the six was in the plugin, but skills.sh serves every SKILL.md in
the repo, so all six were installable — hence the changeset.
Reframe in-progress/ from scratchpad to beta channel: public on purpose,
feedback wanted, not in the plugin, and installable one skill at a time
through skills.sh. Nothing there is deleted or graduated.
Drop qa from the two live docs that cited it as an issue-tracker skill.
ADR 0002 is left untouched — it records reasoning that was true when
decided.
Resolvesmattpocock/personal-wiki#256
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
"Re-pitch that last message" pinned the correction to one message.
"Re-pitch that" leaves the agent to judge how much of what it said
failed to land — and is shorter.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A three-line, user-invoked skill in in-progress/. Fire it when the
agent's last message doesn't land; it re-pitches that message with
the missing context, in ASD-STE100 Simplified Technical English,
using the ubiquitous language from CONTEXT.md.
The name is the mechanism. Concision skills fail by growing, so this
one is a single precise leading word and nothing else.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
CLAUDE.md is always-loaded, so every word costs on every turn. The
edit had grown it by ~65 words, nearly all of which paid load without
changing behaviour:
- The official-marketplace sentence was exposition — a fact the
pointer target already carries.
- "Never reword an install command" steered by prohibition, which
makes the banned behaviour more available, not less.
- The fallback rationale was a third copy of what install-block.md
owns.
- The paragraph split doubled the surface with no branch behind it.
What remains is the one line that does work — the context pointer,
front-loaded on its trigger — leaving CLAUDE.md 10 words longer than
before rather than 65.
Refs mattpocock/personal-wiki#250
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Replaces the two-bullet `Crossing sessions` section with all five options
at a phase boundary — continue, /clear, /handoff, subagent, /compact —
and discloses the ordered tree into a new PHASE-BOUNDARIES.md.
Corrections that come with it:
- /handoff was oversold as the general bridge between context windows.
It is narrow: a new harness, a new directory, a colleague, or a side
task forked mid-phase. What it buys is portability.
- /compact is the default at the bottom of the tree, not the first reach.
- Continue and subagent were missing branches entirely.
Context hygiene's escape hatch now says /compact rather than /handoff,
and the smart zone figure moves from ~120k to ~150k tokens.
Resolves the T5 grilling ticket on the v1.2 release map.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- install-block.md: state the invariant as a requirement rather than
as already-true (docs/ is brought into line downstream); mark all
three canonical snippets, not just the Claude Code one; pin the
`skills@latest` spelling; restore the `setup-matt-pocock-skills`
instruction the whole-set form carries; cite the docs source for
the auto-update claim.
- writing-docs.md: say plainly that the template's Quickstart is the
older wording, so the file no longer contradicts itself.
- CLAUDE.md: split the paragraph, stop restating the fallback rationale.
- ADR 0002: record what was actually verified, on which version, and
the two things that were not — the pinned sha in the official
listing, and the in-session slash command.
Refs mattpocock/personal-wiki#250
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
mattpocock-skills is now listed in Claude Code's official marketplace,
so the own-marketplace route is superseded. The queued changeset still
documented it, and changeset bodies ship verbatim into CHANGELOG.md —
the release would have published a superseded install route as its
headline.
- Rewrite .changeset/ship-as-claude-plugin.md around
`claude plugins install mattpocock-skills`.
- Add .agents/install-block.md as the single source for install
wording, so the docs pass has one true thing to copy.
- Point .agents/writing-docs.md and CLAUDE.md at it.
- Note the official listing in ADR 0002, and record that it reads
plugin.json directly and does not depend on marketplace.json.
.claude-plugin/marketplace.json is kept as a fallback for direct-repo
installs; nothing in CI or scripts references it.
Refs mattpocock/personal-wiki#250
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Move `wizard` out of in-progress into `engineering/` and wire it up as a
promoted skill: plugin.json 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.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Drop the "you may know this document as a PRD" hedge from to-spec and
the local tracker template, switch code-review to issue/spec, bring the
GitHub and GitLab tracker templates in line with the local one, and fix
research.md's dead skills-to-prd link.
CHANGELOG and existing changesets keep the old term where they document
the rename itself.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The round-by-round rework left the wrappers and callers still promising
a one-question-at-a-time interview. Sync grill-me, grill-with-docs and
triage (docs + skill step), plus grilling's Codex short_description and
the loop-me draft.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The title now carries its own bold alongside the bold Q-number, so the
question line reads as a heading. Sync the docs page and changeset.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Prefix the numbered question line with ❓ so questions and their ➡️
recommendations are both scannable. Sync the docs page and changeset.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The recommendation now stands alone on its arrow line. Sync the docs
page and changeset to match.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Add the fixed per-question shape (numbered title, body, recommendation
line) to grilling's SKILL.md, sync the docs page, and add a changeset.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Single source of truth now reaches past the document into the environment.
package.json scripts, config files, directory layout and --help output are
authoritative already, so a doc restating them is a cache of a lookup that
earns its load only when the lookup is expensive.
Co-authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Move `to-questionnaire` out of in-progress into `productivity/` and wire
it up as a promoted skill: plugin.json 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.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The reference now covers any document an agent consumes — skills,
AGENTS.md/CLAUDE.md, docs reached by a pointer. GLOSSARY.md merged into
SKILL.md as a dedup (Avoid-lists and the standalone Predictability
definition pruned); skill-only mechanics disclosed to SKILL-MECHANICS.md;
the skill is now model-invoked. Clean rename, no alias.
Spec: mattpocock/personal-wiki#187 · ships via mattpocock/personal-wiki#193
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Reshape the logic branch from a terminal app into a single
self-contained HTML file a non-developer can drive: a labelled
state panel, free-play buttons, and tabbed guided walkthroughs
(scenarios) with the ordered buttons to press underneath each.
The portable pure-logic module still lifts into the real code;
the HTML shell is the throwaway primary source.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rework grilling from one-question-at-a-time to asking the whole
frontier each round, with background sub-agents for fact-finding so
research never blocks the round. Fold the batch-grill-me experiment
into grilling and delete it. Re-sync the docs page, including how to
opt back into one-at-a-time via global CLAUDE.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The round-by-round rework left the wrappers and callers still promising
a one-question-at-a-time interview. Sync grill-me, grill-with-docs and
triage (docs + skill step), plus grilling's Codex short_description and
the loop-me draft.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The title now carries its own bold alongside the bold Q-number, so the
question line reads as a heading. Sync the docs page and changeset.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Prefix the numbered question line with ❓ so questions and their ➡️
recommendations are both scannable. Sync the docs page and changeset.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The recommendation now stands alone on its arrow line. Sync the docs
page and changeset to match.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Add the fixed per-question shape (numbered title, body, recommendation
line) to grilling's SKILL.md, sync the docs page, and add a changeset.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Single source of truth now reaches past the document into the environment.
package.json scripts, config files, directory layout and --help output are
authoritative already, so a doc restating them is a cache of a lookup that
earns its load only when the lookup is expensive.
Co-authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Collapse the skills.sh Quickstart and the "Install as a Claude Code
plugin" section into one Installation section, ordered Claude Code →
Codex/other agents → tinkerers, each in a collapsed details block.
Claude Code now leads with the one-liner `claude plugins install
mattpocock-skills` — the plugin ships in Claude Code's official
marketplace, so the old two-step `marketplace add` → `install` dance is
gone.
`/setup-matt-pocock-skills` is promoted to a shared step 2, since every
install path needs it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Move `to-questionnaire` out of in-progress into `productivity/` and wire
it up as a promoted skill: plugin.json 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.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The reference now covers any document an agent consumes — skills,
AGENTS.md/CLAUDE.md, docs reached by a pointer. GLOSSARY.md merged into
SKILL.md as a dedup (Avoid-lists and the standalone Predictability
definition pruned); skill-only mechanics disclosed to SKILL-MECHANICS.md;
the skill is now model-invoked. Clean rename, no alias.
Spec: mattpocock/personal-wiki#187 · ships via mattpocock/personal-wiki#193
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Reshape the logic branch from a terminal app into a single
self-contained HTML file a non-developer can drive: a labelled
state panel, free-play buttons, and tabbed guided walkthroughs
(scenarios) with the ordered buttons to press underneath each.
The portable pure-logic module still lifts into the real code;
the HTML shell is the throwaway primary source.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rework grilling from one-question-at-a-time to asking the whole
frontier each round, with background sub-agents for fact-finding so
research never blocks the round. Fold the batch-grill-me experiment
into grilling and delete it. Re-sync the docs page, including how to
opt back into one-at-a-time via global CLAUDE.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Fire fact-finding to a sub-agent and treat a running exploration as an
unsettled prerequisite, so only the downstream questions wait — the rest
of the frontier is asked now, instead of the whole next round blocking
behind one lookup. Phrase throughout in terms of the user.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A user-invoked interview that walks the design tree in rounds: each round
asks the whole frontier of decisions whose prerequisites are already
settled, then recomputes the frontier from the answers.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Drop the sentence explaining why interrogating the subject fails — the
model already obeys it, so it was paying load to say nothing.
Replace the bulleted document structure with an XML-tagged
<questionnaire-template>, mirroring to-spec's <spec-template>: headings
with prose fill-in guidance and a nested <question-example>.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A user-invoked skill that turns a decision you can't fully answer into a
Markdown discovery questionnaire to hand to one person async, or fill out
over a meeting.
Its defining move: it grills you about the *send* (who it's going to, what
you need back), never the subject — sidestepping the "I don't know, I don't
know" spiral you'd hit if it interrogated you on the very knowledge you're
offloading. The written questions then target the gap between what the
recipient knows and what you need.
Landed in in-progress/ to shake out over a few real sends before promoting.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds an `agents/openai.yaml` beside each `SKILL.md` so the skills work in
Codex as well as Claude Code, without generated copies:
- `interface.display_name` + `interface.short_description` for the Codex
skill picker, hand-written for all 39 skills.
- `policy.allow_implicit_invocation: false` on the 22 user-invoked skills —
the Codex analog of `disable-model-invocation: true`, so Codex excludes
them from implicit invocation while explicit `$skill` 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
instructions; note Codex as a `link-skills.sh` install target.
Slimmed-down rework of the approach prototyped in #522: keeps the essential
cross-harness metadata, drops the Ruby validator, the runtime-detector test,
per-skill `default_prompt`s, and the unrelated promotion changes.
Co-authored-by: gabimoncha <gabimoncha@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
