Telling the agent not to give minutes, in a template that has no
minutes, pays load to say nothing — and naming the banned behaviour
makes it more available, not less. The absence does the work.
- SKILL.md: drop the "never give a time estimate" paragraph and the
"stage takes no duration" note; the example stage already shows it.
- template.sh: drop the two comments about not printing minutes.
- docs: drop the sentence about there being no estimate.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The wizard always told the human how many minutes the procedure would
take and how many were left. The number was invented at authoring time
and never true, so it is gone.
- template.sh: drop TOTAL_MINUTES and _MINUTES_ELAPSED, the "about N
minutes" banner line, and the "(~N min left)" stage suffix. stage()
takes a name only; progress is a stage count.
- SKILL.md: state the rule — no minutes in the script, in stage
headers, or in what the agent tells the user.
- docs: the Stages section counts stages, not minutes.
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>
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>
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>
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>
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>
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>
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>
Drop the software-plan scoping from grilling's description and body so the
interview reads as a stress-test of any plan, decision, or idea:
"this plan" → "this", "enact the plan" → "act on it", "codebase" →
"environment". The technique is unchanged, and grill-me is left as-is.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Research stays a real ticket type — it's a shared blocker downstream
decisions hang on, which the frontier's blocking edges exist to render.
What changes is resolution: because research is AFK, charting doesn't
stop and read. After creating the tickets, the charting session fires a
/research subagent for each research ticket to burn it down in parallel,
capturing findings on a throwaway research/<name> branch with a context
pointer.
Charting's "fire the research subagents" step owns how research is
handled; the Ticket Types bullet just names the resolver, and the
one-ticket-per-session rule carries the research exception.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Before scanning, decide where to look. If the user named a direction, take
it; otherwise read 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 — leverage only pays off where you keep editing.
Syncs the docs page and adds a changeset.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.
Introduce "decision ticket" as a light leading word: the skill
description and its opening line name it (and say what makes it one),
and the ask-matt / engineering README blurbs and the docs page match,
while "ticket" stays the everyday word once the term is established.
Record "Decision ticket" in CONTEXT.md so the "avoid: ticket" domain
rule no longer contradicts wayfinder's deliberate use of the word.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Wayfinder is the heaviest, most cognitively demanding flow, and the
wiki shows people misusing it two ways: over-reaching for it on
well-scoped work (it's slower and denser than a single grill), and
losing the way at the handoff after the map (looping straight into
/implement and skipping /to-spec). Sharpen the router's wayfinder
on-ramp to steer both.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a Claude Code plugin marketplace so the promoted skills can be
installed as a managed, read-only bundle (subscribe rather than fork),
alongside the existing skills.sh installer.
- Enrich .claude-plugin/plugin.json with marketplace metadata (version,
description, author, license, keywords); keep the curated promoted-only
skills array.
- Add .claude-plugin/marketplace.json making the repo its own
single-plugin marketplace (mattpocock-skills@mattpocock).
- README: document /plugin install alongside skills.sh, and the
subscribe-vs-fork tradeoff.
- CLAUDE.md: extend the promoted-set invariant to cover marketplace.json
and plugin.json/package.json version sync.
- ADR 0002: record why Claude ships now and a native Codex plugin is
deferred (Codex skills field is single-path + drops symlinks, which
can't express a curated subset of a bucketed repo without a restructure).
Verified: 'claude plugin validate . --strict' passes, and marketplace
add -> install resolves all 21 promoted skills at v1.2.0.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Reframe the artifact handling as capturing the prototype somewhere out
of main — a throwaway branch — with a context pointer to it left on the
implementation issue, instead of "disposing" of it. The main branch
still keeps only the validated decision.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rework /setup-matt-pocock-skills to ask fewer, friendlier questions and
align the local-markdown issue tracker with the current spec.
- Triage labels: asked 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: no longer a setup question. The
GitHub/GitLab templates still carry the flag, defaulted off; 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: one file per ticket under
.scratch/<feature>/issues/<NN>-<slug>.md, never a single combined
tickets.md. /to-tickets, ask-matt, and the local template now agree, and
the spec file is spec.md (not PRD.md) to match /to-spec.
- Re-sync docs pages for setup-matt-pocock-skills and to-tickets; changeset.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Drop the secondary-source label — the actionable distinction is just
that the prototype is a primary source to retain on a throwaway branch.
Collapse the re-descriptions in LOGIC/UI so they point to SKILL for the
disposal concept and add only branch-specific nuance.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
