From 08333f6aec3b85b70932fdbc2e34b8ad932af565 Mon Sep 17 00:00:00 2001 From: Tym Rabchuk Date: Sat, 11 Apr 2026 15:41:27 -0400 Subject: [PATCH] fix(skills): remove unquoted ": " from description frontmatter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 10 SKILL.md files had unquoted `: ` sequences inside plain-scalar `description:` values, violating YAML 1.2 §7.3.3. Strict YAML parsers dropped the description and Claude Code fell back to the plugin-prefixed slash name + H1 heading, causing the asymmetric Mac/Windows rendering reported in #87. Fix strategy: - 8 files rephrased (`when:` → `when —`, `flag:` → `flag —`, etc.) - 2 files (mega-pr, pr-ready) converted to folded block scalar (`>-`) to preserve inline slash paths like `/devkit:tri-review` Verified with Ruby Psych strict YAML parser — all 10 files parse cleanly and return non-empty description strings. Closes #87 --- skills/audit/SKILL.md | 2 +- skills/bugfix/SKILL.md | 2 +- skills/deep-research/SKILL.md | 2 +- skills/feature/SKILL.md | 2 +- skills/mega-pr/SKILL.md | 17 ++++++++++++++++- skills/pr-ready/SKILL.md | 18 +++++++++++++++++- skills/refactor/SKILL.md | 2 +- skills/tri-debug/SKILL.md | 2 +- skills/tri-dispatch/SKILL.md | 2 +- skills/tri-security/SKILL.md | 2 +- 10 files changed, 41 insertions(+), 10 deletions(-) diff --git a/skills/audit/SKILL.md b/skills/audit/SKILL.md index 41cc321..871c9f1 100644 --- a/skills/audit/SKILL.md +++ b/skills/audit/SKILL.md @@ -1,6 +1,6 @@ --- name: audit -description: External-scanner-driven project health check — runs the actual ecosystem tools (npm audit, eslint, govulncheck, semgrep, pip-audit, etc.) to surface what the standard scanners flag: outdated or vulnerable dependencies, lint violations, known CVEs, and config drift. Use when the user asks to "audit this project", "check project health", "run a project audit", "check deps/lint/security state", "is this repo up to date", or wants a stateless rundown of what the standard tools report. Worth using when kicking off work on an unfamiliar project, before a release, after a dependency bump, or when triaging a long-neglected repo. Do NOT use for introspective "what's wrong with this repo and what should I fix first" questions (use self-audit — that ranks issues by evidence), security-focused review of a specific code change (use tri-security), or debugging specific failures (use tri-debug or bugfix). This skill reports what scanners say, not what a human should prioritize. +description: External-scanner-driven project health check — runs the actual ecosystem tools (npm audit, eslint, govulncheck, semgrep, pip-audit, etc.) to surface what the standard scanners flag — outdated or vulnerable dependencies, lint violations, known CVEs, and config drift. Use when the user asks to "audit this project", "check project health", "run a project audit", "check deps/lint/security state", "is this repo up to date", or wants a stateless rundown of what the standard tools report. Worth using when kicking off work on an unfamiliar project, before a release, after a dependency bump, or when triaging a long-neglected repo. Do NOT use for introspective "what's wrong with this repo and what should I fix first" questions (use self-audit — that ranks issues by evidence), security-focused review of a specific code change (use tri-security), or debugging specific failures (use tri-debug or bugfix). This skill reports what scanners say, not what a human should prioritize. --- # Project Audit diff --git a/skills/bugfix/SKILL.md b/skills/bugfix/SKILL.md index 7c831aa..2538bc3 100644 --- a/skills/bugfix/SKILL.md +++ b/skills/bugfix/SKILL.md @@ -1,6 +1,6 @@ --- name: bugfix -description: Deterministic full-lifecycle bugfix workflow — triage → reproduce → diagnose → fix → regression-test → run-tests, with a reproduction gate that must fail before the fix and pass after. Use when the user asks to "fix a bug", "debug this issue", "resolve this error", "patch a defect", "this is broken, fix it", or reports a specific failure they want systematically fixed with a regression test added. Worth the ceremony when: the bug is non-trivial, reproduction isn't obvious, a regression test would prevent recurrence, or the fix needs the full test suite to verify nothing else broke. Do NOT use for one-line typos, missing imports, or obvious null-checks (just fix them directly — the workflow has a fast path but the lookup is still overhead). Do NOT use for hard bugs where the user wants divergent hypotheses before committing to one (use tri-debug). Do NOT use for "something's slow" performance work (use self-perf) or for fixing failing tests specifically (use self-test). +description: Deterministic full-lifecycle bugfix workflow — triage → reproduce → diagnose → fix → regression-test → run-tests, with a reproduction gate that must fail before the fix and pass after. Use when the user asks to "fix a bug", "debug this issue", "resolve this error", "patch a defect", "this is broken, fix it", or reports a specific failure they want systematically fixed with a regression test added. Worth the ceremony when — the bug is non-trivial, reproduction isn't obvious, a regression test would prevent recurrence, or the fix needs the full test suite to verify nothing else broke. Do NOT use for one-line typos, missing imports, or obvious null-checks (just fix them directly — the workflow has a fast path but the lookup is still overhead). Do NOT use for hard bugs where the user wants divergent hypotheses before committing to one (use tri-debug). Do NOT use for "something's slow" performance work (use self-perf) or for fixing failing tests specifically (use self-test). --- # Bug Fix diff --git a/skills/deep-research/SKILL.md b/skills/deep-research/SKILL.md index c4bc6bc..bd698aa 100644 --- a/skills/deep-research/SKILL.md +++ b/skills/deep-research/SKILL.md @@ -1,6 +1,6 @@ --- name: deep-research -description: High-stakes research with Analysis of Competing Hypotheses, disconfirmation testing, evidence matrices, and sensitivity checks (~400k token budget) — use when the user needs to be SURE, not just well-informed. Trigger phrases include "deep research", "deeply investigate", "validate that X", "prove/disprove", "we're making a big decision", "correctness is critical", "I need to trust this answer", or "actively try to disprove this". Worth the extra cost when: the wrong answer has real consequences (architecture commitment, vendor choice, security claim, compliance question, public-facing claim), the user has already seen shallow answers and doesn't trust them, they explicitly ask for rigor or disconfirmation, or they're defending a position to stakeholders. Do NOT use for exploratory "what's out there" questions (use research), routine library comparisons where a single good answer suffices (use research), or quick factual lookups. This is the bias-catching, evidence-calibrating tier — overkill for casual exploration but essential when you can't afford to be wrong. +description: High-stakes research with Analysis of Competing Hypotheses, disconfirmation testing, evidence matrices, and sensitivity checks (~400k token budget) — use when the user needs to be SURE, not just well-informed. Trigger phrases include "deep research", "deeply investigate", "validate that X", "prove/disprove", "we're making a big decision", "correctness is critical", "I need to trust this answer", or "actively try to disprove this". Worth the extra cost when — the wrong answer has real consequences (architecture commitment, vendor choice, security claim, compliance question, public-facing claim), the user has already seen shallow answers and doesn't trust them, they explicitly ask for rigor or disconfirmation, or they're defending a position to stakeholders. Do NOT use for exploratory "what's out there" questions (use research), routine library comparisons where a single good answer suffices (use research), or quick factual lookups. This is the bias-catching, evidence-calibrating tier — overkill for casual exploration but essential when you can't afford to be wrong. --- # Deep Research diff --git a/skills/feature/SKILL.md b/skills/feature/SKILL.md index 6a25d3d..ba711fb 100644 --- a/skills/feature/SKILL.md +++ b/skills/feature/SKILL.md @@ -1,6 +1,6 @@ --- name: feature -description: Deterministic full-lifecycle feature workflow (engine-driven, gated, looped) — triage → brainstorm → plan → implement → gen-tests → run-tests → lint → review → final-report. Use when the user asks to "add a feature", "build X", "implement Y", "ship a new capability", "new feature: ...", or wants an end-to-end pass from rough spec to PR-ready implementation with lint and test gates enforced. Worth the ceremony when: the feature is non-trivial (touches multiple files, needs tests, needs a plan), the user wants a structured walk from idea to working code, or wants gated iteration instead of free-form building. Do NOT use for the separate `/feature-dev:feature-dev` plugin — that is an agent-guided collaborative workflow; if the user explicitly invokes that command, respect it. Do NOT use for one-file quick additions (just write the code), bug fixes (use bugfix), or pure refactoring of existing behavior (use refactor). Includes a fast path for trivial changes so the workflow self-adjusts to scale. +description: Deterministic full-lifecycle feature workflow (engine-driven, gated, looped) — triage → brainstorm → plan → implement → gen-tests → run-tests → lint → review → final-report. Use when the user asks to "add a feature", "build X", "implement Y", "ship a new capability", "new feature X", or wants an end-to-end pass from rough spec to PR-ready implementation with lint and test gates enforced. Worth the ceremony when — the feature is non-trivial (touches multiple files, needs tests, needs a plan), the user wants a structured walk from idea to working code, or wants gated iteration instead of free-form building. Do NOT use for the separate `/feature-dev:feature-dev` plugin — that is an agent-guided collaborative workflow; if the user explicitly invokes that command, respect it. Do NOT use for one-file quick additions (just write the code), bug fixes (use bugfix), or pure refactoring of existing behavior (use refactor). Includes a fast path for trivial changes so the workflow self-adjusts to scale. --- # Feature diff --git a/skills/mega-pr/SKILL.md b/skills/mega-pr/SKILL.md index 3b74dde..87d7ccc 100644 --- a/skills/mega-pr/SKILL.md +++ b/skills/mega-pr/SKILL.md @@ -1,6 +1,21 @@ --- name: mega-pr -description: Fan-out PR review that runs BOTH `/devkit:tri-review` AND `/pr-review-toolkit:review-pr` in parallel for maximum coverage, then presents unified results — this skill does not compete with its sub-skills, it delegates to both simultaneously. Use when the user asks for "mega PR review", "mega-pr", "mega review", "full PR review with everything", "both review tools", "maximum coverage review", or explicitly wants every available reviewer looking at a change at once (Claude + Codex + Gemini model diversity PLUS specialized aspect reviewers like silent-failure-hunter, type-design-analyzer, test-analyzer, code-reviewer). Worth the extra cost when: the PR is high-stakes and the user wants every angle covered, or before merging a critical or hard-to-revert change. Do NOT use when the user only wants one review system (use tri-review or pr-review-toolkit:review-pr directly). Do NOT use for routine code review where a single reviewer suffices. This is deliberate overkill for when you want absolutely everything. +description: >- + Fan-out PR review that runs BOTH `/devkit:tri-review` AND + `/pr-review-toolkit:review-pr` in parallel for maximum coverage, then + presents unified results — this skill does not compete with its sub-skills, + it delegates to both simultaneously. Use when the user asks for "mega PR + review", "mega-pr", "mega review", "full PR review with everything", "both + review tools", "maximum coverage review", or explicitly wants every + available reviewer looking at a change at once (Claude + Codex + Gemini + model diversity PLUS specialized aspect reviewers like + silent-failure-hunter, type-design-analyzer, test-analyzer, code-reviewer). + Worth the extra cost when: the PR is high-stakes and the user wants every + angle covered, or before merging a critical or hard-to-revert change. Do + NOT use when the user only wants one review system (use tri-review or + pr-review-toolkit:review-pr directly). Do NOT use for routine code review + where a single reviewer suffices. This is deliberate overkill for when you + want absolutely everything. --- # Mega PR Review diff --git a/skills/pr-ready/SKILL.md b/skills/pr-ready/SKILL.md index 8dcf404..7614ee1 100644 --- a/skills/pr-ready/SKILL.md +++ b/skills/pr-ready/SKILL.md @@ -1,6 +1,22 @@ --- name: pr-ready -description: Full end-to-end PR pipeline — validate → necessity-check → lint (loop) → test (loop) → security scan → doc-check → changelog → create-pr → monitor reviews (loop). Takes a branch from "code done" to "merged" with every gate enforced. Use when the user asks to "submit a PR", "open a pull request", "ship this", "make this PR-ready", "finalize this branch", or wants the full pipeline run end-to-end with CI monitoring and reviewer-comment handling automated. Worth the ceremony when: lint and test gates must pass before the PR opens, docs need syncing alongside code (README, ROADMAP, SKILL.md, workflows), security scan is required, or the user wants reviewer comments automatically classified and responded to. Do NOT use for a quick commit+push+PR without gates — use `/commit-commands:commit-push-pr` for that lighter path. Do NOT use when already mid-PR and just handling existing review comments in isolation. Do NOT use on the main branch or with uncommitted changes — the validate step will block you. This is devkit's heaviest PR workflow; pick it when you want everything run. +description: >- + Full end-to-end PR pipeline — validate → necessity-check → lint (loop) → + test (loop) → security scan → doc-check → changelog → create-pr → monitor + reviews (loop). Takes a branch from "code done" to "merged" with every gate + enforced. Use when the user asks to "submit a PR", "open a pull request", + "ship this", "make this PR-ready", "finalize this branch", or wants the + full pipeline run end-to-end with CI monitoring and reviewer-comment + handling automated. Worth the ceremony when: lint and test gates must pass + before the PR opens, docs need syncing alongside code (README, ROADMAP, + SKILL.md, workflows), security scan is required, or the user wants + reviewer comments automatically classified and responded to. Do NOT use + for a quick commit+push+PR without gates — use + `/commit-commands:commit-push-pr` for that lighter path. Do NOT use when + already mid-PR and just handling existing review comments in isolation. Do + NOT use on the main branch or with uncommitted changes — the validate step + will block you. This is devkit's heaviest PR workflow; pick it when you + want everything run. --- # PR Ready diff --git a/skills/refactor/SKILL.md b/skills/refactor/SKILL.md index 09aa9e7..8b93170 100644 --- a/skills/refactor/SKILL.md +++ b/skills/refactor/SKILL.md @@ -1,6 +1,6 @@ --- name: refactor -description: Deterministic refactor workflow with tests as the safety net — analyze → plan → refactor → run-tests → fix-tests → comparison. The workflow will not exit until tests pass, guaranteeing behavior preservation. Use when the user asks to "refactor", "restructure", "reorganize", "clean up", "extract", "rename across files", or "modernize" existing code that has test coverage. Worth the ceremony when: the refactor spans multiple files, behavior must be preserved exactly, test coverage exists to prove nothing broke, or the user explicitly wants a safety-netted transformation. Do NOT use for renaming a single variable or function in one file (just do it — the workflow overhead isn't worth it). Do NOT use for adding new behavior (use feature) or fixing broken behavior (use bugfix). Do NOT use when there are no tests — the safety net is the entire point; without tests, do the refactor manually with careful review. If the user wants refactoring advice or a discussion (not the transformation), answer directly instead of dispatching the workflow. +description: Deterministic refactor workflow with tests as the safety net — analyze → plan → refactor → run-tests → fix-tests → comparison. The workflow will not exit until tests pass, guaranteeing behavior preservation. Use when the user asks to "refactor", "restructure", "reorganize", "clean up", "extract", "rename across files", or "modernize" existing code that has test coverage. Worth the ceremony when — the refactor spans multiple files, behavior must be preserved exactly, test coverage exists to prove nothing broke, or the user explicitly wants a safety-netted transformation. Do NOT use for renaming a single variable or function in one file (just do it — the workflow overhead isn't worth it). Do NOT use for adding new behavior (use feature) or fixing broken behavior (use bugfix). Do NOT use when there are no tests — the safety net is the entire point; without tests, do the refactor manually with careful review. If the user wants refactoring advice or a discussion (not the transformation), answer directly instead of dispatching the workflow. --- # Refactor diff --git a/skills/tri-debug/SKILL.md b/skills/tri-debug/SKILL.md index e61255d..8a5e08a 100644 --- a/skills/tri-debug/SKILL.md +++ b/skills/tri-debug/SKILL.md @@ -1,6 +1,6 @@ --- name: tri-debug -description: Three independent root-cause analyses of a hard bug or failure — smart + general + fast model tiers diagnose in parallel, then theories are compared and reconciled. Use when the user asks for tri-debug, triple debug, three-way debugging, multi-model diagnosis, parallel debug, consensus root-cause analysis, or is stuck on a hard bug and wants divergent hypotheses. Worth the extra cost when: the bug is hard (heisenbug, intermittent, cross-system), logs are ambiguous, the obvious fixes have already failed, or the user explicitly wants three independent theories before committing to one. Do NOT use for code review (use tri-review), security audits (use tri-security), or comparing greenfield implementation approaches (use tri-dispatch). Do NOT use for simple "what does this error mean" or routine null-check / typo bugs — a single pass is faster. +description: Three independent root-cause analyses of a hard bug or failure — smart + general + fast model tiers diagnose in parallel, then theories are compared and reconciled. Use when the user asks for tri-debug, triple debug, three-way debugging, multi-model diagnosis, parallel debug, consensus root-cause analysis, or is stuck on a hard bug and wants divergent hypotheses. Worth the extra cost when — the bug is hard (heisenbug, intermittent, cross-system), logs are ambiguous, the obvious fixes have already failed, or the user explicitly wants three independent theories before committing to one. Do NOT use for code review (use tri-review), security audits (use tri-security), or comparing greenfield implementation approaches (use tri-dispatch). Do NOT use for simple "what does this error mean" or routine null-check / typo bugs — a single pass is faster. --- # Tri-Debug diff --git a/skills/tri-dispatch/SKILL.md b/skills/tri-dispatch/SKILL.md index 60f41f4..fcf7778 100644 --- a/skills/tri-dispatch/SKILL.md +++ b/skills/tri-dispatch/SKILL.md @@ -1,6 +1,6 @@ --- name: tri-dispatch -description: Three model tiers (smart + general + fast) each tackle the SAME open-ended task independently, then their divergent approaches are compared — this is the GENERAL-PURPOSE tri-* skill for tasks that don't fit the specialized siblings. Use when the user asks for tri-dispatch, triple dispatch, three-way comparison of model approaches, says "send this to three models and show me their takes", or wants to see divergent solutions before picking one. Worth the extra cost when: the task is exploratory or greenfield (design, architecture, new implementation, optimization), the user wants to compare model strengths on a novel problem, or is deliberately seeking diversity of approach before committing. Do NOT use for code review of existing code (use tri-review), debugging a specific failure (use tri-debug), or security audits (use tri-security). Do NOT use when the user already knows which approach they want — tri-dispatch is for exploration, not execution. +description: Three model tiers (smart + general + fast) each tackle the SAME open-ended task independently, then their divergent approaches are compared — this is the GENERAL-PURPOSE tri-* skill for tasks that don't fit the specialized siblings. Use when the user asks for tri-dispatch, triple dispatch, three-way comparison of model approaches, says "send this to three models and show me their takes", or wants to see divergent solutions before picking one. Worth the extra cost when — the task is exploratory or greenfield (design, architecture, new implementation, optimization), the user wants to compare model strengths on a novel problem, or is deliberately seeking diversity of approach before committing. Do NOT use for code review of existing code (use tri-review), debugging a specific failure (use tri-debug), or security audits (use tri-security). Do NOT use when the user already knows which approach they want — tri-dispatch is for exploration, not execution. --- # Tri-Dispatch diff --git a/skills/tri-security/SKILL.md b/skills/tri-security/SKILL.md index 3b084a4..2daa1cd 100644 --- a/skills/tri-security/SKILL.md +++ b/skills/tri-security/SKILL.md @@ -1,6 +1,6 @@ --- name: tri-security -description: Three-tier parallel security audit (injection + auth + config, each examined by a different model tier) with severity-ranked consolidation — use when the user asks for tri-security, triple security audit, three-way security review, multi-model vulnerability scan, or parallel security audit of a code change, branch, module, or endpoint. Worth the extra cost when: touching auth/payments/user-uploads/admin surfaces, before prod deploy of security-sensitive code, after a security incident, or when the user is paranoid about a specific attack class. Do NOT use for general code quality review (use tri-review), bug diagnosis (use tri-debug), or approach comparison on greenfield work (use tri-dispatch). Do NOT use for a single-line "is this XSS safe" question, or for running pre-existing scanners like npm audit / gosec / semgrep — those are single-tool tasks, not a tri workflow. +description: Three-tier parallel security audit (injection + auth + config, each examined by a different model tier) with severity-ranked consolidation — use when the user asks for tri-security, triple security audit, three-way security review, multi-model vulnerability scan, or parallel security audit of a code change, branch, module, or endpoint. Worth the extra cost when — touching auth/payments/user-uploads/admin surfaces, before prod deploy of security-sensitive code, after a security incident, or when the user is paranoid about a specific attack class. Do NOT use for general code quality review (use tri-review), bug diagnosis (use tri-debug), or approach comparison on greenfield work (use tri-dispatch). Do NOT use for a single-line "is this XSS safe" question, or for running pre-existing scanners like npm audit / gosec / semgrep — those are single-tool tasks, not a tri workflow. --- # Tri-Security