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 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>
Three skills named Claude Code's `Agent` tool and its `general-purpose`
and `Explore` agent types directly. The repo installs across Claude Code,
Codex, and other Agent-Skills harnesses, none of which share that tool or
those type names, so the instruction was unfollowable outside Claude Code.
Each site now describes the shape of the dispatch — parallel subagents,
and what capability each one needs — and leaves the mechanism to the
harness.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Drop the curl exemplar and the enumerated secret and artifact lists —
the model does not need to be told what a secret looks like. Three
sentences carry the same rule.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A Snyk audit (W007, HIGH) flagged the skill for insecure credential
handling: it tells the agent to "paste the invocation and its output",
builds curl loops, and collects artifacts — three paths by which a live
token can end up reproduced in the agent's response.
Add a Redact section making redaction the first move on each, and point
the two call sites at it. Warn in the HITL template that `capture`
prints its value back to the terminal, where the agent reads it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`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>
