The skill only knew to reach for a root CONTEXT.md, so it went silent
on multi-context repos that index their contexts through
CONTEXT-MAP.md instead.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Per writing-for-agents' no-op test: "tell the user to run /X" is
already an unambiguous instruction with no branch where the agent
would otherwise try to call it, so the trailing justification changes
nothing at runtime. It also duplicates the rule .agents/invocation.md
already states as the single source of truth. Cut it from all five
call sites; the carve-out paragraph there is the one place the reason
needs to live.
Five skills (to-spec, wayfinder, to-tickets, triage, code-review) told
the agent to call the Skill tool on setup-matt-pocock-skills as a
missing-config precondition. It's user-invoked, so per
.agents/invocation.md no other skill — user- or model-invoked — can
ever reach it that way. PR #878 turned the old soft "/skill"-style
prose into a literal "Call the Skill tool with ..." instruction
without checking invocation type, which made this fire more reliably
in the wrong direction. Reworded all five as instructions to tell the
human to run it instead.
diagnosing-bugs had the same problem handing its post-mortem off to
improve-codebase-architecture, with no human anywhere in that loop to
catch the failed call. Removed the hand-off outright rather than
softening it, since it rarely fired in practice; Phase 6 is now
"Cleanup" only.
Added a carve-out to .agents/invocation.md's "Dependencies between
them" section — the section PR #878 introduced — so future
"call the Skill tool" instructions can't repeat this against a
user-invoked target.
Fixes#453.
The two FAQ edits quoted the literal new SKILL.md instruction text and
described "now X, replacing Y, intended to fix Z" — implementation-change
narration, exactly what .agents/writing-docs.md's "explain the why, not
the process" / "never reproduces the SKILL.md steps" rules argue against.
It also duplicates content that lives in SKILL.md, which is precisely
what caused the stale quote this PR already had to fix once. That story
belongs in the changeset/CHANGELOG, not the docs page. Reverted both
files to their pre-PR state; the changeset stays as the record of what
changed and why.
Co-Authored-By: Claude <noreply@anthropic.com>
CLAUDE.md requires a docs re-sync when a promoted skill's behaviour
changes, and a changeset for versioning. Full re-syncs of all ten
touched skills' docs pages would be disproportionate for a wording-only
change to internal invocation instructions, but two pages specifically
document the exact reliability problem this phrasing targets — the
"most reported problem" FAQ on grill-with-docs's page, and the matching
"rough edge" FAQ on grilling's page, plus a stale literal quote of
grill-me's SKILL.md body. Updated those three spots to reflect the new
mechanism without overclaiming the bug is fully fixed, and added a
changeset summarizing the change across all ten affected skills.
Co-Authored-By: Claude <noreply@anthropic.com>
"Call the Skill tool with X and Y" reads as a single call taking two
arguments, but the tool takes one skill per call. Reworded every
two-skill site (grill-with-docs, triage, wayfinder x3) to "Call the
Skill tool twice, for X and Y," and added a line to
.agents/invocation.md documenting the convention for future skills.
Co-Authored-By: Claude <noreply@anthropic.com>
Matt's preferred form is `Call the Skill tool with "codebase-design"` —
quoted string, "with" not "for" — applied consistently everywhere a
literal skill name follows. Also reverts an unwanted rewording of
grill-with-docs's SKILL.md back to a direct terminology swap of the
original sentence, rather than restating what it does.
Co-Authored-By: Claude <noreply@anthropic.com>
Bare `/skill`-style prose ("run the `/grilling` skill") relies on the model
reading a slash-prefixed name as a command to fire. Naming the tool directly
gets a higher hit rate, and it's actually more harness-neutral than the old
convention since it drops the Claude-Code-specific `/` trigger syntax
entirely rather than assuming it. Updates the documented convention in
.agents/invocation.md and every operative cross-skill invocation site in
skills/**/SKILL.md to match.
Co-Authored-By: Claude <noreply@anthropic.com>
Every skill that delegates to domain-modeling (grill-with-docs,
wayfinder, improve-codebase-architecture, triage) already invokes
/domain-modeling explicitly by name, so the description never needed
to carry that branch — it's the invoking skill's job to say so, not
this one's to anticipate it.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
"Pin down domain terminology or a ubiquitous language" was stiff and
leaned on DDD jargon. Swap it for the plainer, more naturally-phrased
"discussing codebase terminology".
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The description only fired on conversational framing ("pin down
terminology", "record a decision"). Add explicit triggers for writing
or editing a CONTEXT.md or an ADR directly, so the skill loads even
when the file operation itself is the request rather than the
underlying activity.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The catalog row now reads "Align on an idea before committing to it."
The page's opening carried the same metaphor — "until it has real
decisions in it" — so it now says "until you can commit to it".
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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>
