feat: improve skill review scores for 5 lowest-scoring skills

claude-plugins/consultant/skills/investigate-bug/SKILL.md

@@ -1,23 +1,27 @@
 ---
 name: investigate-bug
-description: Deep bug investigation using consultant agent. Identifies root causes and fix suggestions.
+description: "Deep bug investigation via the consultant agent and external LLM analysis. Gathers symptoms, traces execution flow, identifies root causes, and proposes targeted fixes with regression test plans. Use when the user asks to debug, troubleshoot, investigate errors, exceptions, crashes, race conditions, or unexpected behavior."
 ---
 
 Investigate bug: $ARGUMENTS
 
 ---
 
-Launch the consultant:consultant agent. The agent gathers symptoms, invokes the consultant CLI, and reports root cause analysis.
+Launch the consultant:consultant agent to perform deep root-cause analysis via external LLM consultation.
 
-**Investigation focus**:
-1. **Root cause**: What's actually broken and why
-2. **Execution flow**: Path from trigger to failure
-3. **State analysis**: Invalid states, race conditions, timing issues
-4. **Data validation**: Input validation gaps, edge cases
-5. **Error handling**: Missing handlers, improper recovery
+## Workflow
 
-**Severity levels**:
-- **CRITICAL**: Production down, data corruption, widespread impact
-- **HIGH**: Core functionality broken, major user impact
-- **MEDIUM**: Feature partially broken, workaround available
-- **LOW**: Minor issue, limited impact
+1. **Gather symptoms** — collect error messages, stack traces, reproduction steps, and relevant git history from the user's description and codebase
+2. **Identify scope** — determine affected files, services, and blast radius
+3. **Invoke consultant agent** — the agent gathers full context (diffs, related files, architecture docs), constructs a focused investigation prompt, and delegates analysis to the consultant CLI
+4. **Relay findings** — present the root-cause analysis, execution flow trace, and recommended fix verbatim from the consultant output
+
+## Expected output format
+
+The consultant agent produces a structured bug investigation report including:
+
+- **Root cause**: specific file, line range, and explanation of the defect
+- **Execution flow**: step-by-step trace from trigger to failure
+- **Blast radius**: affected systems, users, and data integrity concerns
+- **Recommended fix**: concrete code changes with rationale
+- **Regression test plan**: test scenarios to prevent recurrence

claude-plugins/prompt-engineering/skills/review-prompt/SKILL.md

@@ -1,7 +1,29 @@
 ---
 name: review-prompt
-description: Review and analyze LLM prompts using the 10-Layer Architecture. Provides detailed assessment without modifying files.
-context: fork
+description: "Review and analyze LLM prompts against first-principles using the 10-Layer Architecture framework. Evaluates identity, capabilities, decision logic, output specs, behavioral rules, examples, meta-cognition, complexity scaling, constraints, and quality standards. Read-only — reports findings without modifying files. Use when the user asks to review, critique, evaluate, assess, or audit an LLM prompt, system prompt, or agent instructions."
 ---
 
 Use the prompt-reviewer agent to review the following prompt: $ARGUMENTS
+
+---
+
+The prompt-reviewer agent loads the prompt-engineering principles, then evaluates the target prompt against the 10-Layer Architecture:
+
+| Layer | Evaluates |
+|-------|-----------|
+| 1. Identity & Purpose | Role clarity, mission statement |
+| 2. Capabilities & Boundaries | Scope definition, expertise bounds |
+| 3. Decision Architecture | IF-THEN logic, routing rules, fallbacks |
+| 4. Output Specifications | Format requirements, required elements |
+| 5. Behavioral Rules | Priority levels (MUST > SHOULD > PREFER) |
+| 6. Examples | Perfect execution samples, edge cases |
+| 7. Meta-Cognitive Instructions | Thinking process, uncertainty handling |
+| 8. Complexity Scaling | Simple vs complex query handling |
+| 9. Constraints & Guardrails | NEVER/ALWAYS rules, exception handling |
+| 10. Quality Standards | Minimum viable, target, exceptional |
+
+## Output
+
+A structured report with overall assessment, score, strengths, and an issues table (type, severity, recommended fix). Issues are tagged `AUTO_FIXABLE` or `NEEDS_USER_INPUT`. Only high-confidence findings are reported — style preferences and uncertain issues are skipped.
+
+**This skill is read-only** — it reports findings without modifying any files.

claude-plugins/solo-dev/skills/audit-ux/SKILL.md

@@ -1,7 +1,29 @@
 ---
 name: audit-ux
-description: Audit UI/UX changes in a focus area against design guidelines for accessibility, consistency, and usability issues.
-context: fork
+description: "Audit UI/UX changes in a focus area against design guidelines, accessibility standards (WCAG), and design system compliance. Performs read-only analysis of changed UI files, checking layout, accessibility, consistency, interaction patterns, and visual hierarchy. Use when the user asks for a UX review, UI audit, accessibility check, design system compliance review, or wants to validate UI changes before merging."
 ---
 
 Launch the ux-auditor agent to perform a comprehensive UX audit of the specified focus area.
+
+Focus area: $ARGUMENTS
+
+---
+
+The ux-auditor agent performs a read-only audit scoped to the specified focus area (e.g., "checkout", "navigation", "forms"):
+
+1. **Gather references** — reads design system docs, brand guidelines, and accessibility requirements
+2. **Identify changes** — runs `git diff main...HEAD` to scope the audit to recent UI modifications in the focus area
+3. **Systematic review** — checks each changed UI file against design documentation, WCAG standards, interaction patterns, responsive behavior, and visual hierarchy
+4. **Report findings** — produces a structured report grouped by priority (Critical / High / Medium / Low)
+
+## Issue categories
+
+- **Layout**: spacing, alignment, grid compliance, responsive breakpoints
+- **Accessibility**: WCAG violations, keyboard navigation, ARIA labels, color contrast, focus management
+- **Consistency**: design system deviations, inconsistent patterns, component misuse
+- **Interaction**: confusing flows, missing feedback, unclear affordances
+- **Visual**: typography issues, color usage, visual hierarchy problems
+
+## Output
+
+A structured UX Audit Report with issues grouped by priority, each containing file references, category, description, user impact, and a specific fix recommendation. This skill is read-only — it reports findings without modifying files.

claude-plugins/vibe-extras/skills/clean-slop/SKILL.md

@@ -1,7 +1,28 @@
 ---
 name: clean-slop
-description: Find and remove AI-generated slop (useless comments, verbose patterns, unnecessary abstractions).
-context: fork
+description: "Find and remove AI-generated code slop — useless comments, verbose patterns, unnecessary abstractions, filler phrases, and redundant documentation. Analyzes target files or git diff, applies conservative surgical edits, and reports a summary of changes. Use when the user asks to clean up code, remove AI artifacts, simplify verbose output, strip obvious comments, or refactor slop from AI-assisted coding sessions."
 ---
 
 Use the slop-cleaner agent to clean up AI slop in: $ARGUMENTS
+
+---
+
+The slop-cleaner agent identifies and removes four categories of AI-generated noise:
+
+1. **Useless comments** — restating what code does, repeating function names, commented-out code
+2. **Verbose documentation** — trivial JSDoc/docstrings on simple getters, redundant type documentation
+3. **Filler phrases** — "It is important to note that...", "Successfully completed", overly apologetic error messages
+4. **Unnecessary patterns** — empty catch blocks, redundant else-after-return, single-use wrapper abstractions
+
+## Scope
+
+- If file paths are provided as arguments, those files are analyzed
+- If no arguments, the agent diffs the current branch against main/master and analyzes changed files
+
+## Decision rule
+
+**Remove** when the comment/pattern restates *what* the code does or adds zero information beyond what code and types already provide. **Keep** when it explains *why*, documents edge cases, or you're uncertain about its value.
+
+## Output
+
+A per-file cleaning report showing removals made, patterns preserved with rationale, and total change counts.

claude-plugins/vibe-extras/skills/update-claude-md/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: update-claude-md
-description: Create or update CLAUDE.md with best practices - brevity, universal applicability, progressive disclosure
+description: "Create or update CLAUDE.md project instructions with best practices for brevity, universal applicability, and progressive disclosure. Handles structure (tech stack, purpose, commands), length budgets (30-300 lines), and pointer-over-copy patterns. Use when the user asks to create, update, edit, or improve their CLAUDE.md, project instructions, or Claude Code configuration file."
 ---
 
 Update my CLAUDE.md based on: $ARGUMENTS
@@ -10,37 +10,64 @@ Current CLAUDE.md:
 
 ---
 
-Make targeted updates based on my request. Only explore codebase if essential info is missing.
+Make targeted updates based on the request. Only explore the codebase if essential info is missing.
 
-If my request conflicts with best practices below, still make the update but note the tradeoff.
+If the request conflicts with best practices below, still apply the update but note the tradeoff.
 
-**Best Practices** (CLAUDE.md is the highest-leverage config point):
+## Best Practices
+
+CLAUDE.md is the highest-leverage config point for Claude Code.
+
+### Structure — cover these if creating or missing critical sections
 
-**Structure** - Cover these if creating/missing critical sections:
 - **WHAT**: Tech stack, project structure, key entry points (critical for monorepos)
 - **WHY**: Project purpose, component relationships, domain terminology
 - **HOW**: Build/test/run commands, verification steps
 
-**Length** (LLMs follow ~150 instructions reliably; system uses ~50):
-- Simple: 30-60 lines | Standard: 60-150 | Complex: 150-300 max
+### Length budget
+
+LLMs follow ~150 instructions reliably; system uses ~50.
+
+| Complexity | Lines |
+|------------|-------|
+| Simple | 30–60 |
+| Standard | 60–150 |
+| Complex | 150–300 max |
+
+### Progressive disclosure
 
-**Progressive Disclosure** - For complex projects, create separate docs and reference them:
+For complex projects, create separate docs and reference them:
 ```
 docs/testing.md, docs/architecture.md, docs/conventions.md
 ```
-Then in CLAUDE.md: "See docs/testing.md for test patterns"
+Then in CLAUDE.md: `See docs/testing.md for test patterns`
 
-**Prefer pointers over copies** - Use `file:line` references instead of pasting code snippets (avoids staleness).
+### Prefer pointers over copies
 
-**Do**: Universal instructions | Imperative language | Verified commands | Reference (don't copy) README
+Use `file:line` references instead of pasting code snippets (avoids staleness).
+
+### Do
+
+- Universal instructions (apply to every task)
+- Imperative language
+- Verified, runnable commands
+- Reference (don't copy) README
+
+### Don't
 
-**Don't**:
 - Style rules → use linters, formatters, or Claude Code hooks instead
-- Task-specific instructions → gets ignored if not relevant to current task
+- Task-specific instructions → ignored when irrelevant to current task
 - File/function enumeration → describe patterns instead
 - Auto-generated boilerplate
 
+### Examples
+
 Bad: `Always use camelCase. Document with JSDoc.`
 Good: `npm test  # Required before PR`
 
-Verify: <300 lines, no style rules, universal instructions, commands tested.
+## Verification checklist
+
+- [ ] Under 300 lines
+- [ ] No style rules (use linters instead)
+- [ ] All instructions are universal
+- [ ] Commands tested and runnable