The skill itself takes a spec plus its tickets and drives them to one
PR, reading the tickets as a task graph so implementer subagents can run
concurrently across the ready frontier.
Documentation duties for the in-progress bucket:
- List it in skills/in-progress/README.md (flat list, name linked to its
SKILL.md), the one entry every skill in a bucket must have. It stays
out of the top-level README and .claude-plugin/plugin.json, and gets no
docs page, as the bucket requires.
- Add a changeset, so the release notes carry it.
- Match the bucket's openai.yaml style in short_description: a short verb
phrase, no closing period.
Also ignore .claude, which holds settings.local.json and agent worktrees
that should never be committed.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Multi-question rounds ran straight into each other with no visual
break. Fold the horizontal rule (---) directly into the round
template so consecutive questions are shown as distinct blocks; the
template demonstrates the separator, so no extra prose instruction
is needed.
The colon-space sequences left behind by #905's em-dash-to-colon
sweep make these six front-matter blocks invalid YAML, so skills.sh
skips them during discovery and they can't be installed via
`npx skills`. Quoting the description scalar fixes parsing without
changing the wording.
Fixes#907
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Rebasing onto main picked up PR #904's new sentence in docs/productivity/wait-what.md,
which used an em-dash. Rewrote it with parentheses per the no-em-dash rule in CLAUDE.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
CHANGELOG.md is changeset-generated; hand-editing its historical prose
was out of scope, so it's back to main's version. Added a patch changeset
describing the em-dash removal instead, and a line in CLAUDE.md/AGENTS.md
so future prose in this repo doesn't reintroduce them.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Every em-dash across docs, skill files, scripts, and JSON/YAML metadata
was rewritten by hand (commas, colons, periods, parentheses, conjunctions)
rather than mechanically substituted, so sentences still read naturally.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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>
Matt Pocock