From 735c0f3ede0f9f0dd39c0964f9a88fac79302d7e Mon Sep 17 00:00:00 2001 From: Dean Sharon Date: Sat, 7 Mar 2026 00:34:00 +0200 Subject: [PATCH] fix(skills): audit skill descriptions to trigger-only format Rewrites 12 skill descriptions from process summaries to trigger-only format. Descriptions now start with "This skill should be used when..." to prevent Claude from treating descriptions as instructions. Closes #82 --- docs/reference/skills-architecture.md | 20 ++++++++++++++++++- .../skills/self-review/SKILL.md | 2 +- .../skills/security-patterns/SKILL.md | 2 +- shared/skills/architecture-patterns/SKILL.md | 2 +- shared/skills/complexity-patterns/SKILL.md | 2 +- shared/skills/consistency-patterns/SKILL.md | 2 +- shared/skills/database-patterns/SKILL.md | 2 +- shared/skills/dependencies-patterns/SKILL.md | 2 +- shared/skills/documentation-patterns/SKILL.md | 2 +- shared/skills/performance-patterns/SKILL.md | 2 +- shared/skills/regression-patterns/SKILL.md | 2 +- shared/skills/review-methodology/SKILL.md | 2 +- shared/skills/security-patterns/SKILL.md | 2 +- shared/skills/self-review/SKILL.md | 2 +- .../skills/test-driven-development/SKILL.md | 5 +---- 15 files changed, 33 insertions(+), 18 deletions(-) diff --git a/docs/reference/skills-architecture.md b/docs/reference/skills-architecture.md index f960609..69909b6 100644 --- a/docs/reference/skills-architecture.md +++ b/docs/reference/skills-architecture.md @@ -91,7 +91,7 @@ Create in `shared/skills/skill-name/SKILL.md` (~120-150 lines): ```markdown --- name: skill-name -description: Brief description with trigger phrases (<180 chars) +description: "This skill should be used when..." with concrete trigger words (<180 chars) user-invocable: false allowed-tools: Read, Grep, Glob, AskUserQuestion activation: @@ -140,6 +140,24 @@ For additional examples and detection patterns: - [ ] Checklist item 2 ``` +## Description Rules + +Skill descriptions appear in Claude Code's skill catalog and influence when Claude auto-invokes skills. Poorly written descriptions can cause Claude to treat the description itself as instructions, bypassing the actual SKILL.md flowchart. + +**Format**: Descriptions MUST start with `"This skill should be used when..."`. + +**Include**: Concrete trigger words -- tool names, error types, user phrases, file types, or review focus areas that signal when the skill is relevant. + +**Never**: Describe the skill's internal process, steps, methodology, or output format in the description. That information belongs in the SKILL.md body, not the frontmatter. + +### Examples + +| Bad (process summary) | Good (trigger-only) | +|---|---| +| "Standard review methodology providing the 6-step process and 3-category issue classification used by all review agents." | "This skill should be used when performing a code review to apply the standard 6-step review process." | +| "Security vulnerability analysis patterns for code review. Detects injection flaws, authentication bypasses, insecure cryptography." | "This skill should be used when reviewing code for injection flaws, auth bypasses, or hardcoded secrets." | +| "Enforce RED-GREEN-REFACTOR cycle during implementation. Write failing tests before production code." | "This skill should be used when implementing new features, fixing bugs, or writing new code. Enforces RED-GREEN-REFACTOR." | + ## Progressive Disclosure Structure ``` diff --git a/plugins/devflow-implement/skills/self-review/SKILL.md b/plugins/devflow-implement/skills/self-review/SKILL.md index 524b4b9..21f13e8 100644 --- a/plugins/devflow-implement/skills/self-review/SKILL.md +++ b/plugins/devflow-implement/skills/self-review/SKILL.md @@ -1,6 +1,6 @@ --- name: self-review -description: Self-review framework evaluating implementation quality against 9 pillars (correctness, completeness, security, performance, maintainability, testing, documentation, error handling, simplicity). Fixes P0/P1 issues immediately rather than reporting them. Used by the Scrutinizer agent as a quality gate. +description: This skill should be used when evaluating implementation quality before submission, checking correctness, security, and simplicity. user-invocable: false allowed-tools: Read, Grep, Glob, Edit, Write, Bash --- diff --git a/plugins/devflow-resolve/skills/security-patterns/SKILL.md b/plugins/devflow-resolve/skills/security-patterns/SKILL.md index ff91a07..3b93f2a 100644 --- a/plugins/devflow-resolve/skills/security-patterns/SKILL.md +++ b/plugins/devflow-resolve/skills/security-patterns/SKILL.md @@ -1,6 +1,6 @@ --- name: security-patterns -description: Security vulnerability analysis patterns for code review. Detects injection flaws, authentication bypasses, insecure cryptography, hardcoded secrets, and missing input sanitization. Loaded by Reviewer agent when focus=security. +description: This skill should be used when reviewing code for injection flaws, auth bypasses, or hardcoded secrets. user-invocable: false allowed-tools: Read, Grep, Glob --- diff --git a/shared/skills/architecture-patterns/SKILL.md b/shared/skills/architecture-patterns/SKILL.md index 899ca56..6a74ae5 100644 --- a/shared/skills/architecture-patterns/SKILL.md +++ b/shared/skills/architecture-patterns/SKILL.md @@ -1,6 +1,6 @@ --- name: architecture-patterns -description: Architecture analysis patterns for code review. Detects SOLID violations, tight coupling, layering issues, and dependency direction problems. Loaded by Reviewer agent when focus=architecture. +description: This skill should be used when reviewing code for SOLID violations, tight coupling, or layering issues. user-invocable: false allowed-tools: Read, Grep, Glob --- diff --git a/shared/skills/complexity-patterns/SKILL.md b/shared/skills/complexity-patterns/SKILL.md index f7e749a..e3a0fec 100644 --- a/shared/skills/complexity-patterns/SKILL.md +++ b/shared/skills/complexity-patterns/SKILL.md @@ -1,6 +1,6 @@ --- name: complexity-patterns -description: Complexity analysis patterns for code review. Detects high cyclomatic complexity, deep nesting, long functions, and readability issues that hinder maintainability. Loaded by Reviewer agent when focus=complexity. +description: This skill should be used when reviewing code for high cyclomatic complexity, deep nesting, or long functions. user-invocable: false allowed-tools: Read, Grep, Glob --- diff --git a/shared/skills/consistency-patterns/SKILL.md b/shared/skills/consistency-patterns/SKILL.md index 1def245..b1a8ea8 100644 --- a/shared/skills/consistency-patterns/SKILL.md +++ b/shared/skills/consistency-patterns/SKILL.md @@ -1,6 +1,6 @@ --- name: consistency-patterns -description: Consistency analysis patterns for code review. Detects naming convention violations, pattern deviations, unnecessary simplification, and feature truncation in diffs. Loaded by Reviewer agent when focus=consistency. +description: This skill should be used when reviewing code for naming convention violations, pattern deviations, or inconsistent API styles. user-invocable: false allowed-tools: Read, Grep, Glob --- diff --git a/shared/skills/database-patterns/SKILL.md b/shared/skills/database-patterns/SKILL.md index 858872b..8b9c80f 100644 --- a/shared/skills/database-patterns/SKILL.md +++ b/shared/skills/database-patterns/SKILL.md @@ -1,6 +1,6 @@ --- name: database-patterns -description: Database analysis patterns for code review. Detects missing indexes, slow queries, unsafe migrations, schema design issues, and connection pool misuse. Loaded by Reviewer agent when focus=database. +description: This skill should be used when reviewing database queries, migrations, indexes, or schema changes. user-invocable: false allowed-tools: Read, Grep, Glob --- diff --git a/shared/skills/dependencies-patterns/SKILL.md b/shared/skills/dependencies-patterns/SKILL.md index 29a8d70..b7ddb7b 100644 --- a/shared/skills/dependencies-patterns/SKILL.md +++ b/shared/skills/dependencies-patterns/SKILL.md @@ -1,6 +1,6 @@ --- name: dependencies-patterns -description: Dependency analysis patterns for code review. Detects known CVEs, outdated packages, license incompatibilities, and unnecessary transitive dependencies. Loaded by Reviewer agent when focus=dependencies. +description: This skill should be used when reviewing dependency changes, lock files, or package additions. user-invocable: false allowed-tools: Read, Grep, Glob --- diff --git a/shared/skills/documentation-patterns/SKILL.md b/shared/skills/documentation-patterns/SKILL.md index 668c70f..42bdbea 100644 --- a/shared/skills/documentation-patterns/SKILL.md +++ b/shared/skills/documentation-patterns/SKILL.md @@ -1,6 +1,6 @@ --- name: documentation-patterns -description: Documentation analysis patterns for code review. Detects doc drift from code changes, missing documentation for public APIs, stale comments, and misleading README sections. Loaded by Reviewer agent when focus=documentation. +description: This skill should be used when reviewing for documentation drift, missing API docs, or stale comments. user-invocable: false allowed-tools: Read, Grep, Glob --- diff --git a/shared/skills/performance-patterns/SKILL.md b/shared/skills/performance-patterns/SKILL.md index c73806e..49f835c 100644 --- a/shared/skills/performance-patterns/SKILL.md +++ b/shared/skills/performance-patterns/SKILL.md @@ -1,6 +1,6 @@ --- name: performance-patterns -description: Performance analysis patterns for code review. Detects N+1 queries, memory leaks, unbounded allocations, I/O bottlenecks, and missing caching opportunities. Loaded by Reviewer agent when focus=performance. +description: This skill should be used when reviewing code for N+1 queries, memory leaks, or I/O bottlenecks. user-invocable: false allowed-tools: Read, Grep, Glob --- diff --git a/shared/skills/regression-patterns/SKILL.md b/shared/skills/regression-patterns/SKILL.md index 9e1ce9d..179fd91 100644 --- a/shared/skills/regression-patterns/SKILL.md +++ b/shared/skills/regression-patterns/SKILL.md @@ -1,6 +1,6 @@ --- name: regression-patterns -description: Regression analysis patterns for code review. Detects lost functionality, removed exports, changed signatures, and behavioral changes that break existing consumers. Loaded by Reviewer agent when focus=regression. +description: This skill should be used when reviewing changes that may remove exports, change signatures, or alter behavior. user-invocable: false allowed-tools: Read, Grep, Glob --- diff --git a/shared/skills/review-methodology/SKILL.md b/shared/skills/review-methodology/SKILL.md index d675c1b..1a6ee31 100644 --- a/shared/skills/review-methodology/SKILL.md +++ b/shared/skills/review-methodology/SKILL.md @@ -1,6 +1,6 @@ --- name: review-methodology -description: Standard review methodology providing the 6-step process and 3-category issue classification (must-fix, should-fix, nit) used by all DevFlow review agents. Ensures consistent, fair, and actionable code reviews across all focus areas. Loaded by the unified Reviewer agent. +description: This skill should be used when performing a code review to apply the standard 6-step review process. user-invocable: false allowed-tools: Read, Grep, Glob, Bash --- diff --git a/shared/skills/security-patterns/SKILL.md b/shared/skills/security-patterns/SKILL.md index ff91a07..3b93f2a 100644 --- a/shared/skills/security-patterns/SKILL.md +++ b/shared/skills/security-patterns/SKILL.md @@ -1,6 +1,6 @@ --- name: security-patterns -description: Security vulnerability analysis patterns for code review. Detects injection flaws, authentication bypasses, insecure cryptography, hardcoded secrets, and missing input sanitization. Loaded by Reviewer agent when focus=security. +description: This skill should be used when reviewing code for injection flaws, auth bypasses, or hardcoded secrets. user-invocable: false allowed-tools: Read, Grep, Glob --- diff --git a/shared/skills/self-review/SKILL.md b/shared/skills/self-review/SKILL.md index 524b4b9..21f13e8 100644 --- a/shared/skills/self-review/SKILL.md +++ b/shared/skills/self-review/SKILL.md @@ -1,6 +1,6 @@ --- name: self-review -description: Self-review framework evaluating implementation quality against 9 pillars (correctness, completeness, security, performance, maintainability, testing, documentation, error handling, simplicity). Fixes P0/P1 issues immediately rather than reporting them. Used by the Scrutinizer agent as a quality gate. +description: This skill should be used when evaluating implementation quality before submission, checking correctness, security, and simplicity. user-invocable: false allowed-tools: Read, Grep, Glob, Edit, Write, Bash --- diff --git a/shared/skills/test-driven-development/SKILL.md b/shared/skills/test-driven-development/SKILL.md index 2214c81..3e1c29c 100644 --- a/shared/skills/test-driven-development/SKILL.md +++ b/shared/skills/test-driven-development/SKILL.md @@ -1,9 +1,6 @@ --- name: test-driven-development -description: >- - Enforce RED-GREEN-REFACTOR cycle during implementation. Write failing tests before - production code. Distinct from test-patterns (which reviews test quality) — this - skill enforces the TDD workflow during code generation. +description: This skill should be used when implementing new features, fixing bugs, or writing new code. Enforces RED-GREEN-REFACTOR. user-invocable: false allowed-tools: Read, Grep, Glob activation: