docs(skills): description-quality pass across 13 collision-prone skills - #82
Merged
Conversation
All four tri-* skills shared near-identical synonym soup ("triple/three-way/
multi-agent/parallel/consensus") which caused the description layer to offer
no differentiation. A query like "tri security audit" could plausibly pull
in tri-review, and "compare three models on this" could swallow work that
belongs to tri-debug or tri-security.
Each description now:
- opens with its unique function (not a generic "Triple-agent X" stamp)
- names the specific trigger phrases that fit only that skill
- gives a "worth-it" signal so the model doesn't fire on trivial tasks
(3x model cost only pays off on high-stakes / hard / exploratory work)
- explicitly hands off to siblings by function, killing the collision
- excludes routine single-pass tasks that don't need triple ceremony
tri-dispatch repositioned as the general-purpose/exploratory tri-* for
greenfield tasks that don't fit review/debug/security — it was the most
dangerous one previously because "triple dispatch" is vague enough to
swallow anything.
Bodies untouched. Underlying workflow YAMLs confirmed structurally sound
(engine.go:111 correctly dispatches parallel: [ids] steps).
…es-based routing
The previous research description used brittle negative-keyword routing
("NOT for 'deep research' or 'validate' — those go to deep-research"). That
pattern breaks as soon as a user rephrases. Replaced with stakes-based
positioning: research is the default/exploratory tier, deep-research is the
high-stakes / ACH / disconfirmation tier.
research now explicitly says "default to this over deep-research unless the
user signals stakes" — which is the right bias since research is cheaper
and covers 80% of real queries. deep-research now opens with "needs to be
SURE, not just well-informed" and lists the consequence categories that
justify the 400k token budget (architecture commitment, vendor choice,
security claim, compliance question, public-facing claim).
Each description also carves out what it is NOT for, by function rather
than keyword, so rephrasing doesn't break routing.
…nner vs ranking
Both descriptions used the word "audit" with no functional differentiation,
so the user (and Claude's triggering) had no way to tell them apart. The
names alone ("audit" vs "self-audit") don't hint at the real distinction:
- audit runs EXTERNAL scanners (npm audit, eslint, govulncheck, semgrep)
and reports what the tools say. Stateless, tool-driven.
- self-audit is INTROSPECTIVE evidence ranking (karpathy-style): measure
quality/security/git signals, then produce a prioritized "what's wrong
here ranked by evidence" improvement plan. Judgment-driven.
Each description now leads with that distinction, gives worth-it conditions,
and carves out the sibling by function. "What scanners say" vs "what a
human should prioritize" is now explicit.
…iggering on common phrases
Five dispatcher skills whose descriptions collided either with native Claude
behavior ("fix this bug", "refactor this") or with other plugins
(feature-dev:feature-dev, commit-commands:commit-push-pr,
pr-review-toolkit:review-pr). Previous descriptions listed trigger phrases
without carve-outs, so the workflow ceremony risked firing on trivial tasks.
- bugfix: explicit "not for typos / null-checks / simple fixes" carve-out,
plus hand-offs to tri-debug (hard bugs) and self-perf (performance).
- feature: clarified boundary with feature-dev:feature-dev plugin (devkit
is deterministic engine-driven; feature-dev is agent-guided collaboration),
with "just write the code" exclusion for one-file additions.
- refactor: added the crucial exclusion "no tests = do it manually, safety
net is the entire point", plus a rename-one-var exclusion.
- pr-ready: clear separation from commit-commands:commit-push-pr (that is
the lighter commit+push+PR path; pr-ready runs full gated pipeline),
and explicit "heaviest PR workflow in devkit" positioning.
- mega-pr: repositioned as a FAN-OUT skill that delegates to both tri-review
and pr-review-toolkit, so it doesn't compete with its own sub-skills. Made
the "deliberate overkill" nature explicit so it won't fire on routine PRs.
Every description now includes worth-it conditions (when the workflow
ceremony is justified) and negative carve-outs (when a lighter path or a
sibling skill is the right choice). Bodies untouched.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rewrites the
description:frontmatter on 13 skills that previously collided with each other, with native Claude behavior, or with other plugins. Bodies, workflow YAMLs, and the engine are untouched — this is a pure documentation/triggering pass.Four themed commits, each addressing a distinct collision cluster:
bf0abe5— tri-* family (tri-review, tri-debug, tri-security, tri-dispatch). The four tri-* skills previously shared synonym soup ("triple/three-way/multi-agent/parallel/consensus"), leaving the description layer with zero differentiation. Now each opens with its unique function, names specific triggers, gives worth-it conditions, and hands off to siblings by function.tri-dispatchrepositioned as the general-purpose exploratory tri-* for greenfield work — it was the most dangerous previously because "triple dispatch" is vague enough to swallow anything.32b78f1— research / deep-research. Replaced brittle negative-keyword routing (the oldresearchdescription said "NOT for 'deep research' or 'validate' — those go to deep-research", which breaks the moment a user rephrases) with stakes-based positioning:researchis the default/exploratory tier,deep-researchis the high-stakes ACH/disconfirmation tier justified by concrete consequence categories (architecture commitment, vendor choice, compliance claim, etc.).bab79a9— audit / self-audit. Both descriptions used the word "audit" with no functional differentiation; names alone didn't hint at the real distinction. Now explicitly:audit= scanner-driven (npm audit,eslint,govulncheck,semgrep) reporting what tools say;self-audit= evidence-ranked introspection (karpathy-style) reporting what a human should prioritize.c25822c— dispatcher skills (bugfix, feature, refactor, pr-ready, mega-pr). Five workflow triggers whose descriptions collided with native Claude behavior ("fix this bug", "refactor this") or with other plugins (feature-dev:feature-dev,commit-commands:commit-push-pr,pr-review-toolkit:review-pr). Each now includes worth-it conditions, trivial-task exclusions, and explicit plugin carve-outs.mega-prrepositioned as a fan-out that delegates to both tri-review and pr-review-toolkit, so it no longer competes with its own sub-skills.Shared pattern applied to all 13
Bonus finding
Verified
src/engine/engine.go:111correctly handles theparallel: [ids]pattern — steps listed in a parallel directive are skipped during the sequential walk and dispatched viarunParallel. The tri-* workflow YAMLs genuinely fan out to all 3 model tiers in parallel. No engine changes needed.Not in this PR
browser(161 lines),scrape(156),screenshot(105) — different kind of work, risks breaking behavior, needs a separate PR with test runs.clean-code,dry,yagni,dont-reinvent) — their triggering nature is different, descriptions are fine.doc-gen,onboard,test-gen,self-*except the two above,setup-rules) — less collision-prone; descriptions are acceptable, diminishing returns.Test plan
tri-securityquery, verifytri-reviewdoes NOT fire (and vice versa across the family)researchfor a low-stakes exploratory question and confirmdeep-researchdoes NOT fire; askdeep-researchwith explicit "correctness is critical" phrasing and confirm it DOES/feature-dev:feature-devexplicitly and confirm devkit'sfeatureskill respects that boundary