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>
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>
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.
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>
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 "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>
Rename the in-progress `review` skill to `code-review` and move it from
`skills/in-progress/` into the promoted `skills/engineering/` bucket.
- Add it to `.claude-plugin/plugin.json` and the Model-invoked sections of
the top-level and Engineering READMEs; drop it from the in-progress README.
- Add a docs page at `docs/engineering/code-review.md`.
- Point `/implement` and its docs at `/code-review`.
- Update the smell-baseline changeset reference; add a changeset for the move.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude Sonnet 5