Skip to content

docs(skills): description-quality pass across 13 collision-prone skills - #82

Merged
5uck1ess merged 4 commits into
mainfrom
skill-improvement
Apr 11, 2026
Merged

docs(skills): description-quality pass across 13 collision-prone skills#82
5uck1ess merged 4 commits into
mainfrom
skill-improvement

Conversation

@5uck1ess

Copy link
Copy Markdown
Owner

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-dispatch repositioned 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 old research description said "NOT for 'deep research' or 'validate' — those go to deep-research", which breaks the moment a user rephrases) with stakes-based positioning: research is the default/exploratory tier, deep-research is 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-pr repositioned 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

  1. Open with the unique function (not a generic "deterministic X" stamp)
  2. List specific trigger phrases tied to the function
  3. State a worth-it signal — when the ceremony (or cost) is justified
  4. Carve out negatives by function so rephrasing doesn't break routing
  5. Where relevant, carve out other plugins by name to prevent cross-plugin collisions

Bonus finding

Verified src/engine/engine.go:111 correctly handles the parallel: [ids] pattern — steps listed in a parallel directive are skipped during the sequential walk and dispatched via runParallel. The tri-* workflow YAMLs genuinely fan out to all 3 model tiers in parallel. No engine changes needed.

Not in this PR

  • Body bloat in browser (161 lines), scrape (156), screenshot (105) — different kind of work, risks breaking behavior, needs a separate PR with test runs.
  • Principle/doctrine skills (clean-code, dry, yagni, dont-reinvent) — their triggering nature is different, descriptions are fine.
  • Remaining dispatcher skills (doc-gen, onboard, test-gen, self-* except the two above, setup-rules) — less collision-prone; descriptions are acceptable, diminishing returns.

Test plan

  • Manually invoke each of the 13 skills in a fresh Claude Code session and confirm they still activate on their primary triggers
  • Cross-collision smoke test: send a tri-security query, verify tri-review does NOT fire (and vice versa across the family)
  • Stakes smoke test: ask research for a low-stakes exploratory question and confirm deep-research does NOT fire; ask deep-research with explicit "correctness is critical" phrasing and confirm it DOES
  • Plugin collision smoke test: invoke /feature-dev:feature-dev explicitly and confirm devkit's feature skill respects that boundary
  • Verify all existing workflow YAML tests still pass (no workflow files were touched)

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.
@5uck1ess
5uck1ess merged commit 123799c into main Apr 11, 2026
6 checks passed
@5uck1ess
5uck1ess deleted the skill-improvement branch April 11, 2026 17:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant