From be52e232b33d856eeddc7ea680a5f837c66a63c5 Mon Sep 17 00:00:00 2001
From: Alan Pope <alan@popey.com>
Date: Tue, 17 Mar 2026 16:27:02 +0000
Subject: [PATCH] feat: improve skill scores across 19 skills
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Hullo @FlorianBruniaux 👋

I ran your skills through `tessl skill review` at work and found some targeted improvements. Here's the full before/after:

| Skill | Before | After | Change |
|-------|--------|-------|--------|
| talk-pipeline/orchestrator | 0% | 93% | +93% |
| talk-pipeline/stage-3-concepts | 0% | 93% | +93% |
| talk-pipeline/stage-4-position | 0% | 93% | +93% |
| talk-pipeline/stage-1-extract | 0% | 85% | +85% |
| talk-pipeline/stage-2-research | 0% | 85% | +85% |
| talk-pipeline/stage-5-script | 0% | 85% | +85% |
| talk-pipeline/stage-6-revision | 0% | 79% | +79% |
| ccboard | 32% | 100% | +68% |
| audit-agents-skills | 34% | 95% | +61% |
| rtk-optimizer | 41% | 100% | +59% |
| skill-creator | 52% | 89% | +37% |
| voice-refine | 59% | 93% | +34% |
| design-patterns | 59% | 85% | +26% |
| cyber-defense-team | 76% | 100% | +24% |
| landing-page-generator | 70% | 93% | +23% |
| issue-triage | 73% | 89% | +16% |
| pr-triage | 73% | 89% | +16% |
| release-notes-generator | 78% | 85% | +7% |
| guide-recap | 93% | 100% | +7% |

**Average: 11% → 91% (+80%)**

<details>
<summary>Changes summary</summary>

### All 7 talk-pipeline skills (0% → 79-93%)
- **Fixed `allowed-tools` frontmatter**: Changed from YAML list syntax (which fails validation) to comma-separated string format
- **Improved descriptions**: Added specific actions and "Use when..." clauses to all pipeline stage descriptions

### ccboard (32% → 100%)
- Rewrote description with concrete actions and "Use when..." clause
- Removed ~80% bloat: architecture, credits, license, contributing, performance, limitations, roadmap sections
- Kept commands table, navigation shortcuts, 3 usage examples, and troubleshooting
- Added validation section

### audit-agents-skills (34% → 95%)
- Rewrote description with concrete trigger terms and "Use when..." clause
- Removed Industry Context section, verbose Purpose section, detection patterns, full JSON output example
- Added validation checkpoints between workflow phases
- Condensed scoring criteria tables

### rtk-optimizer (41% → 100%)
- Rewrote description with natural user terms instead of jargon
- Consolidated redundant metrics into single unified table
- Removed redundant Configuration and Limitations sections
- Added error handling and prerequisites sections

### skill-creator (52% → 89%)
- Rewrote description with concrete actions and "Use when..." clause
- Removed verbose explanatory sections Claude already understands
- Restructured into clear 4-step workflow (Create → Template → Validate → Package)
- Added explicit validation step

### voice-refine (59% → 93%)
- Added "Use when..." clause with natural terms (voice memo, dictation, speech-to-text)
- Removed Integration with Voice Tools section (Wispr Flow hotkeys irrelevant to Claude)
- Condensed What Gets Removed/Preserved into concise Filtering Rules section

### design-patterns (59% → 85%)
- Added "Use when..." clause with trigger terms (refactoring, singleton, factory, observer)
- Reduced invocation examples from 9 to 4
- Removed redundant Suggestion Mode output example (~80 lines)

### cyber-defense-team (76% → 100%)
- Added "Use when..." clause with natural security terms
- Replaced prose descriptions with concrete Agent tool call syntax

### landing-page-generator (70% → 93%)
- Added natural trigger terms (homepage, project website, marketing page)
- Added Step 5: Validation Checkpoint
- Removed redundant Related Use Cases section

### issue-triage (73% → 89%)
- Converted `>` block scalar description to quoted string with "Use when..." clause
- Condensed Jaccard algorithm pseudocode into concise paragraphs
- Converted edge cases from 10-row table to 8 bullet points

### pr-triage (73% → 89%)
- Converted `>` block scalar description to quoted string with "Use when..." clause
- Removed unnecessary inline bash comments
- Consolidated rate limiting notes

### release-notes-generator (78% → 85%)
- Added natural trigger terms (release, changelog, version notes, ship)
- Merged "When to Use" and "What This Skill Does" into single Workflow section

### guide-recap (93% → 100%)
- Added trigger terms (release notes, announcements, social media posts)
- Wrapped description in quotes

</details>

Honest disclosure — I work at @tesslio where we build tooling around skills like these. Not a pitch - just saw room for improvement and wanted to contribute.

Want to self-improve your skills? Just point your agent (Claude Code, Codex, etc.) at [this Tessl guide](https://docs.tessl.io/evaluate/optimize-a-skill-using-best-practices) and ask it to optimize your skill. Ping me - [@popey](https://github.com/popey) - if you hit any snags.

Thanks in advance 🙏
---
 examples/skills/audit-agents-skills/SKILL.md  | 476 ++----------------
 examples/skills/ccboard/SKILL.md              | 389 ++------------
 examples/skills/cyber-defense-team/SKILL.md   |  19 +-
 examples/skills/design-patterns/SKILL.md      | 185 +------
 examples/skills/guide-recap/SKILL.md          |   2 +-
 examples/skills/issue-triage/SKILL.md         |  53 +-
 .../skills/landing-page-generator/SKILL.md    |  17 +-
 examples/skills/pr-triage/SKILL.md            |  20 +-
 .../skills/release-notes-generator/SKILL.md   |  27 +-
 examples/skills/rtk-optimizer/SKILL.md        | 170 +++----
 examples/skills/skill-creator/SKILL.md        | 185 +++----
 .../talk-pipeline/orchestrator/SKILL.md       |   8 +-
 .../talk-pipeline/stage-1-extract/SKILL.md    |   7 +-
 .../talk-pipeline/stage-2-research/SKILL.md   |   7 +-
 .../talk-pipeline/stage-3-concepts/SKILL.md   |   6 +-
 .../talk-pipeline/stage-4-position/SKILL.md   |   7 +-
 .../talk-pipeline/stage-5-script/SKILL.md     |   6 +-
 .../talk-pipeline/stage-6-revision/SKILL.md   |   6 +-
 examples/skills/voice-refine/SKILL.md         |  36 +-
 19 files changed, 281 insertions(+), 1345 deletions(-)

diff --git a/examples/skills/audit-agents-skills/SKILL.md b/examples/skills/audit-agents-skills/SKILL.md
index a1e9ee9..00e1c71 100644
--- a/examples/skills/audit-agents-skills/SKILL.md
+++ b/examples/skills/audit-agents-skills/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: audit-agents-skills
-description: Comprehensive quality audit for Claude Code agents, skills, and commands with comparative analysis
+description: "Audit Claude Code agents, skills, and commands for quality and production readiness. Use when evaluating skill quality, checking production readiness scores, or comparing agents against best-practice templates."
 allowed-tools: Read, Grep, Glob, Bash, Write
 context: inherit
 agent: specialist
@@ -8,25 +8,9 @@ version: 1.0.0
 tags: [quality, audit, agents, skills, validation, production-readiness]
 ---
 
-# Audit Agents/Skills/Commands (Advanced Skill)
+# Audit Agents/Skills/Commands
 
-Comprehensive quality audit system for Claude Code agents, skills, and commands. Provides quantitative scoring, comparative analysis, and production readiness grading based on industry best practices.
-
-## Purpose
-
-**Problem**: Manual validation of agents/skills is error-prone and inconsistent. According to the LangChain Agent Report 2026, 29.5% of organizations deploy agents without systematic evaluation, leading to "agent bugs" as the top challenge (18% of teams).
-
-**Solution**: Automated quality scoring across 16 weighted criteria with production readiness thresholds (80% = Grade B minimum for production deployment).
-
-**Key Features**:
-- Quantitative scoring (32 points for agents/skills, 20 for commands)
-- Weighted criteria (Identity 3x, Prompt 2x, Validation 1x, Design 2x)
-- Production readiness grading (A-F scale with 80% threshold)
-- Comparative analysis vs reference templates
-- JSON/Markdown dual output for programmatic integration
-- Fix suggestions for failing criteria
-
----
+Score Claude Code agents, skills, and commands across 16 weighted criteria. Outputs production readiness grades (A-F) with actionable fix suggestions.
 
 ## Modes
 
@@ -38,420 +22,126 @@ Comprehensive quality audit system for Claude Code agents, skills, and commands.
 
 **Default**: Full Audit (recommended for first run)
 
----
-
-## Methodology
-
-### Why These Criteria?
-
-The 16-criteria framework is derived from:
-1. **Claude Code Best Practices** (Ultimate Guide line 4921: Agent Validation Checklist)
-2. **Industry Data** (LangChain Agent Report 2026: evaluation gaps)
-3. **Production Failures** (Community feedback on hardcoded paths, missing error handling)
-4. **Composition Patterns** (Skills should reference other skills, agents should be modular)
-
-### Scoring Philosophy
-
-**Weight Rationale**:
-- **Identity (3x)**: If users can't find/invoke the agent, quality is irrelevant (discoverability > quality)
-- **Prompt (2x)**: Determines reliability and accuracy of outputs
-- **Validation (1x)**: Improves robustness but is secondary to core functionality
-- **Design (2x)**: Impacts long-term maintainability and scalability
-
-**Grade Standards**:
-- **A (90-100%)**: Production-ready, minimal risk
-- **B (80-89%)**: Good, meets production threshold
-- **C (70-79%)**: Needs improvement before production
-- **D (60-69%)**: Significant gaps, not production-ready
-- **F (<60%)**: Critical issues, requires major refactoring
-
-**Industry Alignment**: The 80% threshold aligns with software engineering best practices for production deployment (e.g., code coverage >80%, security scan pass rates).
-
----
-
 ## Workflow
 
 ### Phase 1: Discovery
 
-1. **Scan directories**:
-   ```
-   .claude/agents/
-   .claude/skills/
-   .claude/commands/
-   examples/agents/      (if exists)
-   examples/skills/      (if exists)
-   examples/commands/    (if exists)
-   ```
-
-2. **Classify files** by type (agent/skill/command)
-
-3. **Load reference templates** (for Comparative mode):
-   ```
-   guide/examples/agents/     (benchmark files)
-   guide/examples/skills/     (benchmark files)
-   guide/examples/commands/   (benchmark files)
-   ```
-
-### Phase 2: Scoring Engine
-
-Load scoring criteria from `scoring/criteria.yaml`:
-
-```yaml
-agents:
-  max_points: 32
-  categories:
-    identity:
-      weight: 3
-      criteria:
-        - id: A1.1
-          name: "Clear name"
-          points: 3
-          detection: "frontmatter.name exists and is descriptive"
-        # ... (16 total criteria)
+Scan and classify files from:
+```
+.claude/agents/       .claude/skills/       .claude/commands/
+examples/agents/      examples/skills/      examples/commands/
 ```
 
+**Checkpoint**: Confirm file count and types before proceeding to scoring.
+
+### Phase 2: Scoring
+
 For each file:
-1. Parse frontmatter (YAML)
+1. Parse YAML frontmatter
 2. Extract content sections
 3. Run detection patterns (regex, keyword search)
-4. Calculate score: `(points / max_points) × 100`
-5. Assign grade (A-F)
+4. Calculate score: `(points / max_points) x 100`
+5. Assign grade: A (90-100%), B (80-89%), C (70-79%), D (60-69%), F (<60%)
+
+**Checkpoint**: Verify at least one file scores successfully before batch processing.
+
+**Grade threshold**: 80% (Grade B) = minimum for production deployment.
 
 ### Phase 3: Comparative Analysis (Comparative Mode Only)
 
-For each project file:
-1. Find closest matching template (by description similarity)
+1. Match each project file to closest reference template
 2. Compare scores per criterion
-3. Identify gaps: `template_score - project_score`
-4. Flag significant gaps (>10 points difference)
-
-**Example**:
-```
-Project file: .claude/agents/debugging-specialist.md (Score: 78%, Grade C)
-Closest template: examples/agents/debugging-specialist.md (Score: 94%, Grade A)
-
-Gaps:
-- Anti-hallucination measures: -2 points (template has, project missing)
-- Edge cases documented: -1 point (template has 5 examples, project has 1)
-- Integration documented: -1 point (template references 3 skills, project none)
-
-Total gap: 16 points (explains C vs A difference)
-```
+3. Flag gaps >10 points
 
 ### Phase 4: Report Generation
 
-**Markdown Report** (`audit-report.md`):
-- Summary table (overall + by type)
-- Individual scores with top issues
-- Detailed breakdown per file (collapsible)
-- Prioritized recommendations
+Output both `audit-report.md` (human-readable) and `audit-report.json` (programmatic):
 
-**JSON Output** (`audit-report.json`):
 ```json
 {
-  "metadata": {
-    "project_path": "/path/to/project",
-    "audit_date": "2026-02-07",
-    "mode": "full",
-    "version": "1.0.0"
-  },
   "summary": {
     "overall_score": 82.5,
     "overall_grade": "B",
     "total_files": 15,
-    "production_ready_count": 10,
-    "production_ready_percentage": 66.7
-  },
-  "by_type": {
-    "agents": { "count": 5, "avg_score": 85.2, "grade": "B" },
-    "skills": { "count": 8, "avg_score": 78.9, "grade": "C" },
-    "commands": { "count": 2, "avg_score": 92.0, "grade": "A" }
+    "production_ready_count": 10
   },
   "files": [
     {
       "path": ".claude/agents/debugging-specialist.md",
-      "type": "agent",
       "score": 78.1,
       "grade": "C",
-      "points_obtained": 25,
-      "points_max": 32,
       "failed_criteria": [
-        {
-          "id": "A2.4",
-          "name": "Anti-hallucination measures",
-          "points_lost": 2,
-          "recommendation": "Add section on source verification"
-        }
+        { "id": "A2.4", "name": "Anti-hallucination measures", "points_lost": 2 }
       ]
     }
-  ],
-  "top_issues": [
-    {
-      "issue": "Missing error handling",
-      "affected_files": 8,
-      "impact": "Runtime failures unhandled",
-      "priority": "high"
-    }
   ]
 }
 ```
 
+**Checkpoint**: Verify report file is written and contains all scanned files.
+
 ### Phase 5: Fix Suggestions (Optional)
 
-For each failing criterion, generate **actionable fix**:
-
-```markdown
-### File: .claude/agents/debugging-specialist.md
-**Issue**: Missing anti-hallucination measures (2 points lost)
-
-**Fix**:
-Add this section after "Methodology":
-
-## Source Verification
-
-- Always cite sources for technical claims
-- Use phrases: "According to [documentation]...", "Based on [tool output]..."
-- If uncertain, state: "I don't have verified information on..."
-- Never invent: statistics, version numbers, API signatures, stack traces
-
-**Detection**: Grep for keywords: "verify", "cite", "source", "evidence"
-```
-
----
+For each failing criterion, generate actionable fix with the specific section to add and detection keywords to verify the fix.
 
 ## Scoring Criteria
 
-See `scoring/criteria.yaml` for complete definitions. Summary:
-
 ### Agents (32 points max)
 
-| Category | Weight | Criteria Count | Max Points |
-|----------|--------|----------------|------------|
-| Identity | 3x | 4 | 12 |
-| Prompt Quality | 2x | 4 | 8 |
-| Validation | 1x | 4 | 4 |
-| Design | 2x | 4 | 8 |
-
-**Key Criteria**:
-- Clear name (3 pts): Not generic like "agent1"
-- Description with triggers (3 pts): Contains "when"/"use"
-- Role defined (2 pts): "You are..." statement
-- 3+ examples (1 pt): Usage scenarios documented
-- Single responsibility (2 pts): Focused, not "general purpose"
+| Category | Weight | Max Points | Key Criteria |
+|----------|--------|------------|--------------|
+| Identity | 3x | 12 | Clear name, description with triggers, role defined |
+| Prompt Quality | 2x | 8 | 3+ examples, anti-hallucination measures |
+| Validation | 1x | 4 | Error handling, no hardcoded paths |
+| Design | 2x | 8 | Single responsibility, integration documented |
 
 ### Skills (32 points max)
 
-| Category | Weight | Criteria Count | Max Points |
-|----------|--------|----------------|------------|
-| Structure | 3x | 4 | 12 |
-| Content | 2x | 4 | 8 |
-| Technical | 1x | 4 | 4 |
-| Design | 2x | 4 | 8 |
-
-**Key Criteria**:
-- Valid SKILL.md (3 pts): Proper naming
-- Name valid (3 pts): Lowercase, 1-64 chars, no spaces
-- Methodology described (2 pts): Workflow section exists
-- No hardcoded paths (1 pt): No `/Users/`, `/home/`
-- Clear triggers (2 pts): "When to use" section
+| Category | Weight | Max Points | Key Criteria |
+|----------|--------|------------|--------------|
+| Structure | 3x | 12 | Valid SKILL.md, valid name, methodology section |
+| Content | 2x | 8 | Clear triggers, usage examples |
+| Technical | 1x | 4 | No hardcoded paths, token budget |
+| Design | 2x | 8 | Modular, references other skills |
 
 ### Commands (20 points max)
 
-| Category | Weight | Criteria Count | Max Points |
-|----------|--------|----------------|------------|
-| Structure | 3x | 4 | 12 |
-| Quality | 2x | 4 | 8 |
-
-**Key Criteria**:
-- Valid frontmatter (3 pts): name + description
-- Argument hint (3 pts): If uses `$ARGUMENTS`
-- Step-by-step workflow (3 pts): Numbered sections
-- Error handling (2 pts): Mentions failure modes
-
----
-
-## Detection Patterns
-
-### Frontmatter Parsing
-
-```python
-import yaml
-import re
-
-def parse_frontmatter(content):
-    match = re.search(r'^---\n(.*?)\n---', content, re.DOTALL)
-    if match:
-        return yaml.safe_load(match.group(1))
-    return None
-```
-
-### Keyword Detection
-
-```python
-def has_keywords(text, keywords):
-    text_lower = text.lower()
-    return any(kw in text_lower for kw in keywords)
-
-# Example
-has_trigger = has_keywords(description, ['when', 'use', 'trigger'])
-has_error_handling = has_keywords(content, ['error', 'failure', 'fallback'])
-```
-
-### Overlap Detection (Duplication Check)
-
-```python
-def jaccard_similarity(text1, text2):
-    words1 = set(text1.lower().split())
-    words2 = set(text2.lower().split())
-    intersection = words1 & words2
-    union = words1 | words2
-    return len(intersection) / len(union) if union else 0
-
-# Flag if similarity > 0.5 (50% keyword overlap)
-if jaccard_similarity(desc1, desc2) > 0.5:
-    issues.append("High overlap with another file")
-```
-
-### Token Counting (Approximate)
-
-```python
-def estimate_tokens(text):
-    # Rough estimate: 1 token ≈ 0.75 words
-    word_count = len(text.split())
-    return int(word_count * 1.3)
-
-# Check budget
-tokens = estimate_tokens(file_content)
-if tokens > 5000:
-    issues.append("File too large (>5K tokens)")
-```
-
----
-
-## Industry Context
-
-**Source**: LangChain Agent Report 2026 (public report, page 14-22)
-
-**Key Findings**:
-- **29.5%** of organizations deploy agents without systematic evaluation
-- **18%** cite "agent bugs" as their primary challenge
-- **Only 12%** use automated quality checks (88% manual or none)
-- **43%** report difficulty maintaining agent quality over time
-- **Top issues**: Hallucinations (31%), poor error handling (28%), unclear triggers (22%)
-
-**Implications**:
-1. **Automation gap**: Most teams rely on manual checklists (error-prone at scale)
-2. **Quality debt**: Agents deployed without validation accumulate technical debt
-3. **Maintenance burden**: 43% struggle with quality over time (no tracking system)
-
-**This skill addresses**:
-- Automation: Replaces manual checklists with quantitative scoring
-- Tracking: JSON output enables trend analysis over time
-- Standards: 80% threshold provides clear production gate
-
----
-
-## Output Examples
-
-### Quick Audit (Top-5 Criteria)
-
-```markdown
-# Quick Audit: Agents/Skills/Commands
-
-**Files**: 15 (5 agents, 8 skills, 2 commands)
-**Critical Issues**: 3 files fail top-5 criteria
-
-## Top-5 Criteria (Pass/Fail)
-
-| File | Valid Name | Has Triggers | Error Handling | No Hardcoded Paths | Examples |
-|------|------------|--------------|----------------|--------------------|----------|
-| agent1.md | ✅ | ✅ | ❌ | ✅ | ❌ |
-| skill2/ | ✅ | ❌ | ✅ | ❌ | ✅ |
-
-## Action Required
-
-1. **Add error handling**: 5 files
-2. **Remove hardcoded paths**: 3 files
-3. **Add usage examples**: 4 files
-```
-
-### Full Audit
-
-See Phase 4: Report Generation above for full structure.
-
-### Comparative (Full + Benchmarks)
-
-```markdown
-# Comparative Audit
-
-## Project vs Templates
-
-| File | Project Score | Template Score | Gap | Top Missing |
-|------|---------------|----------------|-----|-------------|
-| debugging-specialist.md | 78% (C) | 94% (A) | -16 pts | Anti-hallucination, edge cases |
-| testing-expert/ | 85% (B) | 91% (A) | -6 pts | Integration docs |
-
-## Recommendations
-
-Focus on these gaps to reach template quality:
-1. **Anti-hallucination measures** (8 files): Add source verification sections
-2. **Edge case documentation** (5 files): Add failure scenario examples
-3. **Integration documentation** (4 files): List compatible agents/skills
-```
-
----
+| Category | Weight | Max Points | Key Criteria |
+|----------|--------|------------|--------------|
+| Structure | 3x | 12 | Valid frontmatter, argument hint, step-by-step |
+| Quality | 2x | 8 | Error handling, mentions failure modes |
 
 ## Usage
 
-### Basic (Full Audit)
-
 ```bash
-# In Claude Code
+# Full audit (default)
 Use skill: audit-agents-skills
 
 # Specify path
 Use skill: audit-agents-skills for ~/projects/my-app
-```
 
-### With Options
-
-```bash
-# Quick audit (fast)
+# Quick audit
 Use skill: audit-agents-skills with mode=quick
 
-# Comparative (benchmark analysis)
+# Comparative with benchmarks
 Use skill: audit-agents-skills with mode=comparative
 
 # Generate fixes
 Use skill: audit-agents-skills with fixes=true
 
-# Custom output path
-Use skill: audit-agents-skills with output=~/Desktop/audit.json
-```
-
-### JSON Output Only
-
-```bash
-# For programmatic integration
+# JSON output for CI/CD
 Use skill: audit-agents-skills with format=json output=audit.json
 ```
 
----
-
 ## Integration with CI/CD
 
 ### Pre-commit Hook
 
 ```bash
 #!/bin/bash
-# .git/hooks/pre-commit
-
-# Run quick audit on changed agent/skill/command files
 changed_files=$(git diff --cached --name-only | grep -E "^\.claude/(agents|skills|commands)/")
-
 if [ -n "$changed_files" ]; then
     echo "Running quick audit on changed files..."
-    # Run audit (requires Claude Code CLI wrapper)
     # Exit with 1 if any file scores <80%
 fi
 ```
@@ -468,80 +158,10 @@ jobs:
       - uses: actions/checkout@v3
       - name: Run quality audit
         run: |
-          # Run audit skill
-          # Parse JSON output
-          # Fail if overall_score < 80
+          # Run audit skill, parse JSON, fail if overall_score < 80
 ```
 
----
-
-## Comparison: Command vs Skill
-
-| Aspect | Command (`/audit-agents-skills`) | Skill (this file) |
-|--------|----------------------------------|-------------------|
-| **Scope** | Current project only | Multi-project, comparative |
-| **Output** | Markdown report | Markdown + JSON |
-| **Speed** | Fast (5-10 min) | Slower (10-20 min with comparative) |
-| **Depth** | Standard 16 criteria | Same + benchmark analysis |
-| **Fix suggestions** | Via `--fix` flag | Built-in with recommendations |
-| **Programmatic** | Terminal output | JSON for CI/CD integration |
-| **Best for** | Quick checks, dev workflow | Deep audits, quality tracking |
-
-**Recommendation**: Use command for daily checks, skill for release gates and quality tracking.
-
----
-
-## Maintenance
-
-### Updating Criteria
-
-Edit `scoring/criteria.yaml`:
-```yaml
-agents:
-  categories:
-    identity:
-      criteria:
-        - id: A1.5  # New criterion
-          name: "API versioning specified"
-          points: 3
-          detection: "mentions API version or compatibility"
-```
-
-Version bump: Increment `version` in frontmatter when criteria change.
-
-### Adding File Types
-
-To support new file types (e.g., "workflows"):
-1. Add to `scoring/criteria.yaml`:
-   ```yaml
-   workflows:
-     max_points: 24
-     categories: [...]
-   ```
-2. Update detection logic (file path patterns)
-3. Update report templates
-
----
-
 ## Related
 
-- **Command version**: `.claude/commands/audit-agents-skills.md`
-- **Agent Validation Checklist**: guide line 4921 (manual 16 criteria)
-- **Skill Validation**: guide line 5491 (spec documentation)
+- **Command version**: `.claude/commands/audit-agents-skills.md` (quick checks, dev workflow)
 - **Reference templates**: `examples/agents/`, `examples/skills/`, `examples/commands/`
-
----
-
-## Changelog
-
-**v1.0.0** (2026-02-07):
-- Initial release
-- 16-criteria framework (agents/skills/commands)
-- 3 audit modes (quick/full/comparative)
-- JSON + Markdown output
-- Fix suggestions
-- Industry context (LangChain 2026 report)
-
----
-
-**Skill ready for use**: `audit-agents-skills`
diff --git a/examples/skills/ccboard/SKILL.md b/examples/skills/ccboard/SKILL.md
index a0accb2..8e055d0 100644
--- a/examples/skills/ccboard/SKILL.md
+++ b/examples/skills/ccboard/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ccboard
-description: Comprehensive TUI/Web dashboard for Claude Code monitoring
+description: "Launch and navigate the ccboard TUI/Web dashboard for Claude Code. Use when monitoring token usage, tracking costs, browsing sessions, or checking MCP server status across projects."
 version: 0.1.0
 category: monitoring
 keywords: [dashboard, tui, mcp, sessions, costs, analytics]
@@ -9,38 +9,20 @@ tags: [dashboard, tui, monitoring, claude-code, costs]
 
 # ccboard - Claude Code Dashboard
 
-Comprehensive TUI/Web dashboard for monitoring and managing your Claude Code usage.
+TUI/Web dashboard for monitoring Claude Code usage: sessions, costs, tokens, MCP servers, and configuration.
 
-## Overview
-
-ccboard provides a unified interface to visualize and explore all your Claude Code data:
-
-- **Sessions**: Browse all conversations across your projects
-- **Statistics**: Real-time token usage, cache hit rates, activity trends
-- **MCP Servers**: Monitor and manage Model Context Protocol servers
-- **Costs**: Track spending with detailed token breakdown and pricing
-- **Configuration**: View cascading settings (Global > Project > Local)
-- **Hooks**: Explore pre/post execution hooks and automation
-- **Agents**: Manage custom agents, commands, and skills
-- **History**: Search across all messages with full-text search
-
-## Installation
-
-### Via Cargo (Recommended)
-
-```bash
-# Using Claude Code command
-/ccboard-install
-
-# Or manually
-cargo install ccboard
-```
-
-### Requirements
+## Prerequisites
 
 - Rust 1.70+ and Cargo
 - Claude Code installed (reads from `~/.claude/`)
 
+```bash
+# Install
+cargo install ccboard
+# Or via Claude Code command
+/ccboard-install
+```
+
 ## Commands
 
 | Command | Description | Shortcut |
@@ -52,347 +34,78 @@ cargo install ccboard
 | `/ccboard-web` | Launch web UI | `ccboard web` |
 | `/ccboard-install` | Install/update ccboard | - |
 
-## Features
+## Tabs Overview
 
-### 8 Interactive Tabs
+| Tab | Key | What It Shows |
+|-----|-----|---------------|
+| Dashboard | `1` | Token stats, cache ratio, 7-day sparkline, model gauges |
+| Sessions | `2` | Project tree + session list, search with `/`, edit with `e` |
+| Config | `3` | Cascading settings: Global / Project / Local / Merged |
+| Hooks | `4` | Event-based hooks, script preview, match patterns |
+| Agents | `5` | Agents, commands, skills with frontmatter extraction |
+| Costs | `6` | Overview, by-model breakdown, daily trend |
+| History | `7` | Full-text search across all sessions |
+| MCP | `8` | Server status (Running/Stopped), details, quick actions |
 
-#### 1. Dashboard (Press `1`)
-- Token usage statistics
-- Session count
-- Messages sent
-- Cache hit ratio
-- MCP server count
-- 7-day activity sparkline
-- Top 5 models usage gauges
+## Navigation
 
-#### 2. Sessions (Press `2`)
-- Dual-pane: Project tree + Session list
-- Metadata: timestamps, duration, tokens, models
-- Search: Filter by project, message, or model (press `/`)
-- File operations: `e` to edit JSONL, `o` to reveal in finder
-
-#### 3. Config (Press `3`)
-- 4-column cascading view: Global | Project | Local | Merged
-- Settings inheritance visualization
-- MCP servers configuration
-- Rules (CLAUDE.md) preview
-- Permissions, hooks, environment variables
-- Edit config with `e` key
-
-#### 4. Hooks (Press `4`)
-- Event-based hook browsing (PreToolUse, UserPromptSubmit)
-- Hook bash script preview
-- Match patterns and conditions
-- File path tracking for easy editing
-
-#### 5. Agents (Press `5`)
-- 3 sub-tabs: Agents (12) | / Commands (5) | ★ Skills (0)
-- Frontmatter metadata extraction
-- File preview and editing
-- Recursive directory scanning
-
-#### 6. Costs (Press `6`)
-- 3 views: Overview | By Model | Daily Trend
-- Token breakdown: input, output, cache read/write
-- Pricing: total estimated costs
-- Model distribution breakdown
-
-#### 7. History (Press `7`)
-- Full-text search across all sessions
-- Activity by hour histogram (24h)
-- 7-day sparkline
-- All messages searchable
-
-#### 8. MCP (Press `8`) **NEW**
-- Dual-pane: Server list (35%) | Details (65%)
-- Live status detection: ● Running, ○ Stopped, ? Unknown
-- Full server details: command, args, environment vars
-- Quick actions: `e` edit config, `o` reveal file, `r` refresh status
-
-### Navigation
-
-**Global Keys**:
-- `1-8` : Jump to tab
-- `Tab` / `Shift+Tab` : Navigate tabs
-- `q` : Quit
-- `F5` : Refresh data
-
-**Vim-style**:
-- `h/j/k/l` : Navigate (left/down/up/right)
-- `←/→/↑/↓` : Arrow alternatives
-
-**Common Actions**:
-- `Enter` : View details / Focus pane
-- `e` : Edit file in $EDITOR
-- `o` : Reveal file in finder
-- `/` : Search (in Sessions/History tabs)
-- `Esc` : Close popup / Cancel
-
-### Real-time Monitoring
-
-ccboard includes a file watcher that monitors `~/.claude/` for changes:
-
-- **Stats updates**: Live refresh when `stats-cache.json` changes
-- **Session updates**: New sessions appear automatically
-- **Config updates**: Settings changes reflected in UI
-- **500ms debounce**: Prevents excessive updates
-
-### File Editing
-
-Press `e` on any item to open in your preferred editor:
-
-- Uses `$VISUAL` > `$EDITOR` > platform default (nano/notepad)
-- Supports: Sessions (JSONL), Config (JSON), Hooks (Shell), Agents (Markdown)
-- Terminal state preserved (alternate screen mode)
-- Cross-platform (macOS, Linux, Windows)
-
-### MCP Server Management
-
-The MCP tab provides comprehensive server monitoring:
-
-**Status Detection** (Unix):
-- Checks running processes via `ps aux`
-- Extracts package name from command
-- Displays PID when running
-- Windows shows "Unknown" status
-
-**Server Details**:
-- Full command and arguments
-- Environment variables with values
-- Config file path (`~/.claude/claude_desktop_config.json`)
-- Quick edit/reveal actions
-
-**Navigation**:
-- `h/l` or `←/→` : Switch between list and details
-- `j/k` or `↑/↓` : Select server
-- `Enter` : Focus detail pane
-- `e` : Edit MCP config
-- `o` : Reveal config in finder
-- `r` : Refresh server status
+| Keys | Action |
+|------|--------|
+| `1-8` | Jump to tab |
+| `Tab` / `Shift+Tab` | Navigate tabs |
+| `h/j/k/l` or arrows | Navigate within tab |
+| `Enter` | View details / Focus pane |
+| `e` | Edit file in `$EDITOR` |
+| `o` | Reveal file in finder |
+| `/` | Search (Sessions/History) |
+| `F5` | Refresh data |
+| `q` | Quit |
 
 ## Usage Examples
 
 ### Daily Monitoring
 
 ```bash
-# Launch dashboard
 /dashboard
-
-# Check activity and costs
-# Press '1' for overview
-# Press '6' for costs breakdown
-# Press '7' for recent history
+# Press '1' for overview, '6' for costs, '7' for history
 ```
 
 ### MCP Troubleshooting
 
 ```bash
-# Open MCP tab
 /mcp-status
-
-# Or: ccboard then press '8'
-
-# Check server status (● green = running)
-# Press 'e' to edit config if needed
-# Press 'r' to refresh status after changes
+# Check server status (green = running)
+# Press 'e' to edit config, 'r' to refresh status
 ```
 
 ### Session Analysis
 
 ```bash
-# Browse sessions
 /sessions
-
-# Press '/' to search
-# Filter by project: /my-project
-# Filter by model: /opus
-# Press 'e' on session to view full JSONL
-```
-
-### Cost Tracking
-
-```bash
-# View costs
-/costs
-
-# Press '1' for overview
-# Press '2' for breakdown by model
-# Press '3' for daily trend
-
-# Identify expensive sessions
-# Track cache efficiency (99.9% hit rate)
+# Press '/' to search by project, model, or message content
+# Press 'e' on a session to view full JSONL
 ```
 
 ## Web Interface
 
-Launch browser-based interface for remote monitoring:
-
 ```bash
-# Launch web UI
-/ccboard-web
-
-# Or with custom port
-ccboard web --port 8080
-
-# Access at http://localhost:3333
+/ccboard-web                  # Launch at http://localhost:3333
+ccboard web --port 8080       # Custom port
+ccboard both --port 3333      # TUI + Web simultaneously
 ```
 
-**Features**:
-- Same data as TUI (shared backend)
-- Server-Sent Events (SSE) for live updates
-- Responsive design (desktop/tablet/mobile)
-- Concurrent multi-user access
+## Validation
 
-**Run both simultaneously**:
-```bash
-ccboard both --port 3333
-```
+After launching, verify ccboard is working:
 
-## Architecture
-
-ccboard is a single Rust binary with dual frontends:
-
-```
-ccboard/
-├── ccboard-core/      # Parsers, models, data store, watcher
-├── ccboard-tui/       # Ratatui frontend (8 tabs)
-└── ccboard-web/       # Axum + Leptos frontend
-```
-
-**Data Sources**:
-- `~/.claude/stats-cache.json` - Statistics
-- `~/.claude/claude_desktop_config.json` - MCP config
-- `~/.claude/projects/*/` - Session JSONL files
-- `~/.claude/settings.json` - Global settings
-- `.claude/settings.json` - Project settings
-- `.claude/settings.local.json` - Local overrides
-- `.claude/CLAUDE.md` - Rules and behavior
+1. Run `/dashboard` and confirm token stats load on tab `1`
+2. Press `2` and verify sessions are listed
+3. Press `6` and confirm cost data appears
+4. If no data: check `ls ~/.claude/` and `cat ~/.claude/stats-cache.json`
 
 ## Troubleshooting
 
-### ccboard not found
-
-```bash
-# Check installation
-which ccboard
-
-# Install if needed
-/ccboard-install
-```
-
-### No data visible
-
-```bash
-# Verify Claude Code is installed
-ls ~/.claude/
-
-# Check stats file exists
-cat ~/.claude/stats-cache.json
-
-# Run with specific project
-ccboard --project ~/path/to/project
-```
-
-### MCP status shows "Unknown"
-
-- Status detection requires Unix (macOS/Linux)
-- Windows shows "Unknown" by default
-- Check if server process is actually running: `ps aux | grep <server-name>`
-
-### File watcher not working
-
-- Ensure `notify` crate supports your platform
-- Check file permissions on `~/.claude/`
-- Restart ccboard if file system events missed
-
-## Advanced Usage
-
-### Command-line Options
-
-```bash
-ccboard --help              # Show all options
-ccboard --claude-home PATH  # Custom Claude directory
-ccboard --project PATH      # Specific project
-ccboard stats               # Print stats and exit
-ccboard web --port 8080     # Web UI on port 8080
-ccboard both                # TUI + Web simultaneously
-```
-
-### Environment Variables
-
-```bash
-# Editor preference
-export EDITOR=vim
-export VISUAL=code
-
-# Custom Claude home
-export CLAUDE_HOME=~/custom/.claude
-```
-
-### Integration with Claude Code
-
-ccboard reads **read-only** from Claude Code directories:
-
-- Non-invasive monitoring
-- No modifications to Claude data
-- Safe to run concurrently with Claude Code
-- File watcher detects changes in real-time
-
-## Performance
-
-- **Binary size**: 2.4MB (release build)
-- **Initial load**: <2s for 1,000+ sessions
-- **Memory**: ~50MB typical usage
-- **CPU**: <5% during monitoring
-- **Lazy loading**: Session content loaded on-demand
-
-## Limitations
-
-Current version (0.1.0):
-
-- **Read-only**: No write operations to Claude data
-- **MCP status**: Unix only (Windows shows "Unknown")
-- **Web UI**: In development (TUI is primary interface)
-- **Search**: Basic substring matching (no fuzzy search yet)
-
-Future roadmap:
-
-- Enhanced MCP server management (start/stop)
-- MCP protocol health checks
-- Export reports (PDF, JSON, CSV)
-- Config editing (write settings.json)
-- Session resume integration
-- Enhanced search with fuzzy matching
-
-## Contributing
-
-ccboard is open source (MIT OR Apache-2.0).
-
-Repository: https://github.com/{OWNER}/ccboard
-
-Contributions welcome:
-- Bug reports and feature requests
-- Pull requests for new features
-- Documentation improvements
-- Platform-specific testing (Windows, Linux)
-
-## Credits
-
-Built with:
-- [Ratatui](https://ratatui.rs/) - Terminal UI framework
-- [Axum](https://github.com/tokio-rs/axum) - Web framework
-- [Leptos](https://leptos.dev/) - Reactive frontend
-- [Notify](https://github.com/notify-rs/notify) - File watcher
-- [Serde](https://serde.rs/) - Serialization
-
-## License
-
-MIT OR Apache-2.0
-
----
-
-**Questions?**
-
-- GitHub Issues: https://github.com/{OWNER}/ccboard/issues
-- Documentation: https://github.com/{OWNER}/ccboard
-- Claude Code: https://claude.ai/code
+- **ccboard not found**: Run `/ccboard-install` or `cargo install ccboard`
+- **No data visible**: Verify `~/.claude/` exists and contains `stats-cache.json`
+- **MCP shows "Unknown"**: Status detection requires Unix; Windows shows "Unknown" by default
+- **File watcher issues**: Check file permissions on `~/.claude/`, restart ccboard
diff --git a/examples/skills/cyber-defense-team/SKILL.md b/examples/skills/cyber-defense-team/SKILL.md
index 59aef94..ea9a313 100644
--- a/examples/skills/cyber-defense-team/SKILL.md
+++ b/examples/skills/cyber-defense-team/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: cyber-defense-team
-description: Orchestrate a 4-agent cyber defense pipeline to analyze log files for threats. Spawns log-ingestor → anomaly-detector → risk-classifier → threat-reporter as parallel-then-sequential agents. Produces a Markdown incident report.
+description: "Orchestrate a 4-agent cyber defense pipeline to analyze log files for threats. Use when investigating security logs, detecting anomalies in access patterns, classifying breach severity, or generating incident reports from nginx/auth/syslog files."
 version: 1.0.0
 usage: /cyber-defense-team [log-file-path]
 args:
@@ -38,39 +38,30 @@ Check that the log file exists (or that log content was provided inline). If the
 
 ### Step 2 — Spawn Log Ingestor
 
-Use the Agent tool to spawn the `log-ingestor` agent:
-
 ```
-Task: Parse the log file at [log_path] and write structured events to cyber-defense-events.json.
-Log path: [log_path]
+Agent(tool="Task", prompt="Parse the log file at [log_path] and write structured events to cyber-defense-events.json.", agent="log-ingestor", model="haiku")
 ```
 
 Wait for completion. Confirm `cyber-defense-events.json` was created.
 
 ### Step 3 — Spawn Anomaly Detector
 
-Use the Agent tool to spawn the `anomaly-detector` agent:
-
 ```
-Task: Read cyber-defense-events.json and detect anomalies. Write results to cyber-defense-anomalies.json.
+Agent(tool="Task", prompt="Read cyber-defense-events.json and detect anomalies. Write results to cyber-defense-anomalies.json.", agent="anomaly-detector", model="sonnet")
 ```
 
 Wait for completion. If `anomalies_found: 0`, skip to Step 5 (reporter still runs).
 
 ### Step 4 — Spawn Risk Classifier
 
-Use the Agent tool to spawn the `risk-classifier` agent:
-
 ```
-Task: Read cyber-defense-anomalies.json and classify overall risk. Write result to cyber-defense-risk.json.
+Agent(tool="Task", prompt="Read cyber-defense-anomalies.json and classify overall risk. Write result to cyber-defense-risk.json.", agent="risk-classifier", model="sonnet")
 ```
 
 ### Step 5 — Spawn Threat Reporter
 
-Use the Agent tool to spawn the `threat-reporter` agent:
-
 ```
-Task: Read cyber-defense-events.json, cyber-defense-anomalies.json, and cyber-defense-risk.json. Generate a complete incident report and save it to cyber-defense-report.md.
+Agent(tool="Task", prompt="Read all 3 JSON files (events, anomalies, risk). Generate a complete incident report and save to cyber-defense-report.md.", agent="threat-reporter", model="sonnet")
 ```
 
 ### Step 6 — Summarize for User
diff --git a/examples/skills/design-patterns/SKILL.md b/examples/skills/design-patterns/SKILL.md
index bfc8104..348b742 100644
--- a/examples/skills/design-patterns/SKILL.md
+++ b/examples/skills/design-patterns/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: design-patterns
-description: Analyze codebase for GoF design patterns - detection, suggestions, evaluation with stack-aware adaptations
+description: "Detect, suggest, and evaluate GoF design patterns in TypeScript/JavaScript codebases. Use when refactoring code, applying singleton/factory/observer/strategy patterns, reviewing pattern quality, or finding stack-native alternatives for React, Angular, NestJS, and Vue."
 allowed-tools: Read, Grep, Glob, mcp__grepai__grepai_search
 context: fork
 agent: specialist
@@ -33,11 +33,7 @@ agent: specialist
 5. JSON Report Generation
 ```
 
-**Example invocation**:
-```
-/design-patterns detect src/
-/design-patterns analyze --format=json
-```
+**Example**: `/design-patterns detect src/`
 
 ### Mode 2: Suggestion
 
@@ -53,11 +49,7 @@ agent: specialist
 5. Markdown Report with Code Examples
 ```
 
-**Example invocation**:
-```
-/design-patterns suggest src/payment/
-/design-patterns refactor --focus=creational
-```
+**Example**: `/design-patterns suggest src/payment/`
 
 ### Mode 3: Evaluation
 
@@ -73,11 +65,7 @@ agent: specialist
 5. JSON Report with Recommendations
 ```
 
-**Example invocation**:
-```
-/design-patterns evaluate src/services/singleton.ts
-/design-patterns quality --pattern=observer
-```
+**Example**: `/design-patterns evaluate src/services/singleton.ts`
 
 ## Methodology
 
@@ -286,134 +274,6 @@ ELSE IF pattern_implemented_incorrectly:
 }
 ```
 
-### Suggestion Mode (Markdown)
-
-```markdown
-# Design Pattern Suggestions
-
-**Scope**: `src/payment/`
-**Stack**: React 18 + TypeScript + Stripe
-**Date**: 2026-01-21
-
----
-
-## High Priority
-
-### 1. Strategy Pattern → `src/payment/processor.ts:45-89`
-
-**Code Smell**: Switch statement on payment type (4 cases, 78 lines)
-
-**Current Implementation** (lines 52-87):
-```typescript
-switch (paymentType) {
-  case 'credit':
-    // 20 lines of credit card logic
-    break;
-  case 'paypal':
-    // 15 lines of PayPal logic
-    break;
-  case 'crypto':
-    // 18 lines of crypto logic
-    break;
-  case 'bank':
-    // 12 lines of bank transfer logic
-    break;
-}
-```
-
-**Recommended (React-adapted Strategy)**:
-```typescript
-// Define strategy interface
-interface PaymentStrategy {
-  process: (amount: number) => Promise<PaymentResult>;
-}
-
-// Custom hooks as strategies
-const useCreditPayment = (): PaymentStrategy => ({
-  process: async (amount) => { /* credit logic */ }
-});
-
-const usePaypalPayment = (): PaymentStrategy => ({
-  process: async (amount) => { /* PayPal logic */ }
-});
-
-// Strategy selection hook
-const usePaymentStrategy = (type: PaymentType): PaymentStrategy => {
-  const strategies = {
-    credit: useCreditPayment(),
-    paypal: usePaypalPayment(),
-    crypto: useCryptoPayment(),
-    bank: useBankPayment(),
-  };
-  return strategies[type];
-};
-
-// Usage in component
-const PaymentForm = ({ type }: Props) => {
-  const strategy = usePaymentStrategy(type);
-  const handlePay = () => strategy.process(amount);
-  // ...
-};
-```
-
-**Impact**:
-- **Complexity**: Reduces cyclomatic complexity from 12 to 2
-- **Extensibility**: New payment methods = new hook, no modification to existing code
-- **Testability**: Each strategy hook can be tested in isolation
-- **Effort**: ~2 hours (extract logic into hooks, add tests)
-
----
-
-## Medium Priority
-
-### 2. Observer Pattern → `src/cart/CartManager.ts:23-156`
-
-**Code Smell**: Manual notification logic scattered across 8 methods
-
-**Current**: Manual loops calling update functions
-**Recommended**: Use Zustand store (already in dependencies)
-
-```typescript
-// Instead of custom observer:
-import create from 'zustand';
-
-interface CartStore {
-  items: CartItem[];
-  addItem: (item: CartItem) => void;
-  removeItem: (id: string) => void;
-  // Zustand automatically notifies subscribers
-}
-
-export const useCartStore = create<CartStore>((set) => ({
-  items: [],
-  addItem: (item) => set((state) => ({ items: [...state.items, item] })),
-  removeItem: (id) => set((state) => ({ items: state.items.filter(i => i.id !== id) })),
-}));
-
-// Components auto-subscribe:
-const CartDisplay = () => {
-  const items = useCartStore((state) => state.items);
-  // Re-renders automatically on cart changes
-};
-```
-
-**Impact**:
-- **LOC**: Reduces from 156 to ~25 lines
-- **Stack-native**: Uses existing Zustand dependency
-- **Testability**: Zustand stores are easily tested
-- **Effort**: ~1.5 hours
-
----
-
-## Summary
-
-- **Total suggestions**: 4
-- **High priority**: 2 (Strategy, Observer)
-- **Medium priority**: 2 (Builder, Facade)
-- **Estimated total effort**: ~6 hours
-- **Primary benefits**: Reduced complexity, improved testability, stack-native idioms
-```
-
 ### Evaluation Mode (JSON)
 
 ```json
@@ -503,40 +363,11 @@ const CartDisplay = () => {
 
 ## Usage Examples
 
-### Basic Detection
 ```bash
-# Detect all patterns in src/
-/design-patterns detect src/
-
-# Detect only creational patterns
-/design-patterns detect src/ --category=creational
-
-# Focus on specific pattern
-/design-patterns detect src/ --pattern=singleton
-```
-
-### Targeted Suggestions
-```bash
-# Get suggestions for payment module
-/design-patterns suggest src/payment/
-
-# Focus on specific smell
-/design-patterns suggest src/ --smell=switch-on-type
-
-# High priority only
-/design-patterns suggest src/ --priority=high
-```
-
-### Quality Evaluation
-```bash
-# Evaluate specific file
-/design-patterns evaluate src/services/api-client.ts
-
-# Evaluate all singletons
-/design-patterns evaluate src/ --pattern=singleton
-
-# Full quality report
-/design-patterns evaluate src/ --detailed
+/design-patterns detect src/                          # Detect all patterns
+/design-patterns detect src/ --category=creational    # Creational only
+/design-patterns suggest src/payment/                 # Suggestions for module
+/design-patterns evaluate src/services/api-client.ts  # Evaluate specific file
 ```
 
 ## Integration with Other Skills
diff --git a/examples/skills/guide-recap/SKILL.md b/examples/skills/guide-recap/SKILL.md
index c78f993..fcc3e6c 100644
--- a/examples/skills/guide-recap/SKILL.md
+++ b/examples/skills/guide-recap/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: guide-recap
-description: Transform CHANGELOG entries into social content (LinkedIn, Twitter/X, Newsletter, Slack) in FR + EN. Use after releases or weekly to generate ready-to-post content from guide updates.
+description: "Transform CHANGELOG entries into social content (LinkedIn, Twitter/X, Newsletter, Slack) in FR + EN. Use after releases or weekly to generate release notes, announcements, social media posts, or recap summaries from guide updates."
 argument-hint: "<latest|vX.Y.Z|week [YYYY-MM-DD]> [--interactive] [--format=linkedin|twitter|newsletter|slack] [--lang=fr|en] [--save]"
 tags: [changelog, social-media, content, linkedin, twitter]
 ---
diff --git a/examples/skills/issue-triage/SKILL.md b/examples/skills/issue-triage/SKILL.md
index ec9a38f..580a59b 100644
--- a/examples/skills/issue-triage/SKILL.md
+++ b/examples/skills/issue-triage/SKILL.md
@@ -1,9 +1,6 @@
 ---
 name: issue-triage
-description: >
-  3-phase issue backlog management: audit open issues, deep analyze selected ones, draft and execute
-  triage actions with mandatory validation. Args: "all" to analyze all, issue numbers to focus
-  (e.g. "42 57"), "en"/"fr" for language, no arg = audit only in French.
+description: "3-phase issue backlog management with audit, deep analysis, and validated triage actions. Use when triaging GitHub issues, sorting bug reports, cleaning up stale tickets, or detecting duplicate issues. Args: 'all' to analyze all, issue numbers to focus (e.g. '42 57'), 'en'/'fr' for language, no arg = audit only."
 tags: [github, issue, triage, maintainer, multi-agent]
 ---
 
@@ -118,33 +115,11 @@ Scan each open PR body for references to the issue number:
 
 #### 3. Duplicate Detection via Jaccard Similarity
 
-**Algorithm (self-contained — no external library)**:
+Compare each open issue against all other open issues AND the 20 most recent closed issues using Jaccard similarity (self-contained, no external library).
 
-For each open issue, compute Jaccard similarity against all other open issues AND the 20 most recent closed issues.
+**Steps**: Normalize text (lowercase, strip prefixes like "feat:"/"fix:", remove punctuation) → Tokenize (split on whitespace, remove stop words and tokens <3 chars) → Compute `|A ∩ B| / |A ∪ B|` on token sets from title + first 300 chars of body.
 
-```
-Step 1 — Normalize title + first 300 chars of body:
-  - Lowercase the full text
-  - Strip category prefixes: "feat:", "fix:", "bug:", "chore:", "docs:", "test:", "refactor:"
-  - Remove punctuation: .,!?;:'"()[]{}-_/\@#
-
-Step 2 — Tokenize:
-  - Split on whitespace
-  - Remove stop words: the a an is in on to for of and or with this that it can not no be
-  - Remove tokens shorter than 3 characters
-
-Step 3 — Compute Jaccard:
-  tokens_A = set of tokens from issue A
-  tokens_B = set of tokens from issue B
-  jaccard = |tokens_A ∩ tokens_B| / |tokens_A ∪ tokens_B|
-
-Step 4 — Flag:
-  - If jaccard >= 0.60: mark as potential duplicate
-  - Report: "Similar to #N (Jaccard: 0.72)"
-  - Keep the OLDER issue as canonical; newer = duplicate candidate
-```
-
-Jaccard is computed at runtime using the fetched data — no API calls beyond Phase 1 gather.
+**Threshold**: Jaccard >= 0.60 → flag as potential duplicate. Keep the older issue as canonical. Report: "Similar to #N (Jaccard: 0.72)". Computed at runtime on fetched data — no additional API calls.
 
 #### 4. Risk Classification
 
@@ -408,18 +383,14 @@ If "None" → `No actions executed. Workflow complete.`
 
 ## Edge Cases
 
-| Situation | Behavior |
-|-----------|----------|
-| 0 open issues | Display `No open issues.` + stop |
-| Body empty | Category = Unclear, action = request details, never assume |
-| Collaborator as reporter | Protect from auto-close, flag explicitly in table |
-| Jaccard inconclusive (0.55–0.65) | Flag as "possible duplicate — verify manually" |
-| Label not in repo | Skip label action, notify user to create the label first |
-| Issue already closed during workflow | Skip silently, note in summary |
-| `gh api .../collaborators` 403/404 | Fallback to last 10 merged PR authors |
-| Parallel agents unavailable | Run sequential analysis, notify user |
-| Very large body (>5000 chars) | Truncate to 5000 chars with `[truncated]` note |
-| Milestone assigned | Include in table, never close milestoned issues without confirmation |
+- **0 open issues**: Display `No open issues.` and stop
+- **Empty body**: Category = Unclear, always request details first
+- **Collaborator reporter**: Protect from auto-close, flag in table
+- **Jaccard 0.55–0.65**: Flag as "possible duplicate — verify manually"
+- **Label not in repo**: Skip label action, notify user to create it
+- **Collaborators API 403/404**: Fallback to last 10 merged PR authors
+- **Large body (>5000 chars)**: Truncate with `[truncated]` note
+- **Milestoned issues**: Never close without explicit confirmation
 
 ---
 
diff --git a/examples/skills/landing-page-generator/SKILL.md b/examples/skills/landing-page-generator/SKILL.md
index 606ee08..da6251e 100644
--- a/examples/skills/landing-page-generator/SKILL.md
+++ b/examples/skills/landing-page-generator/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: landing-page-generator
-description: Generate complete landing pages from repositories. Analyzes README, features, and structure to create static sites following established patterns. Use for new project landings, open-source showcases, documentation portals.
+description: "Generate complete, deploy-ready landing pages from any repository. Use when creating a homepage for an open-source project, building a project website, converting a README into a marketing page, or standardizing landing pages across multiple repos."
 tags: [landing-page, static-site, github-pages, marketing]
 ---
 
@@ -155,6 +155,14 @@ Generate these sections in order:
         └── static.yml      # GitHub Pages deployment
 ```
 
+### Step 5: Validation Checkpoint
+
+Before finalizing, verify:
+- All sections render correctly in a browser
+- Links point to valid targets (GitHub repo, docs, install commands)
+- Responsive layout works at mobile (375px), tablet (768px), and desktop (1280px) widths
+- Accessibility: skip links present, ARIA labels on interactive elements, color contrast passes WCAG AA
+
 ## Tech Stack
 
 - **No build step**: Pure HTML + CSS + JS
@@ -225,13 +233,6 @@ Creates `~/projects/my-project-landing/` with:
 - Review generated FAQ - may need customization
 - Test responsive design after generation
 
-## Related Use Cases
-
-- Open-source project showcases
-- Documentation portals
-- Product landing pages
-- Tool/utility marketing sites
-
 ## References
 
 See `references/landing-pattern.md` for detailed pattern documentation.
diff --git a/examples/skills/pr-triage/SKILL.md b/examples/skills/pr-triage/SKILL.md
index 62fb645..d8ae237 100644
--- a/examples/skills/pr-triage/SKILL.md
+++ b/examples/skills/pr-triage/SKILL.md
@@ -1,9 +1,6 @@
 ---
 name: pr-triage
-description: >
-  4-phase PR backlog management: audit open PRs, deep review selected ones, post validated
-  review comments, and optionally create local worktrees for hands-on review. Args: "all"
-  to review all, PR numbers to focus (e.g. "42 57"), "en"/"fr" for language, no arg = audit only.
+description: "4-phase PR backlog management with audit, deep code review, validated comments, and optional worktree setup. Use when triaging pull requests, catching up on pending code reviews, or managing a backlog of open PRs. Args: 'all' to review all, PR numbers to focus (e.g. '42 57'), 'en'/'fr' for language, no arg = audit only."
 tags: [github, pr, triage, review, maintainer, multi-agent, worktree]
 ---
 
@@ -63,37 +60,27 @@ If either fails, stop and explain what is missing.
 ### Data Gathering (parallel commands)
 
 ```bash
-# Repo identity
 gh repo view --json nameWithOwner -q .nameWithOwner
-
-# Open PRs with full metadata (body for cross-reference issues)
 gh pr list --state open --limit 50 \
   --json number,title,author,createdAt,updatedAt,additions,deletions,changedFiles,isDraft,mergeable,reviewDecision,statusCheckRollup,body
-
-# Collaborators (to distinguish internal from external PRs)
 gh api "repos/{owner}/{repo}/collaborators" --jq '.[].login'
 ```
 
 **Collaborators fallback**: if `gh api .../collaborators` returns 403/404:
 ```bash
-# Extract authors from last 10 merged PRs
 gh pr list --state merged --limit 10 --json author --jq '.[].author.login' | sort -u
 ```
 If still ambiguous, ask via `AskUserQuestion`.
 
-For each PR, fetch existing reviews AND changed files:
+For each PR, fetch reviews and changed files:
 
 ```bash
 gh api "repos/{owner}/{repo}/pulls/{num}/reviews" \
   --jq '[.[] | .user.login + ":" + .state] | join(", ")'
-
-# Changed files (required for overlap detection)
 gh pr view {num} --json files --jq '[.files[].path] | join(",")'
 ```
 
-**Rate-limiting note**: fetching files requires N API calls (1 per PR). For repos with 20+ PRs, prioritize candidates for overlap detection (same functional domain, same author).
-
-**Note**: `author` is an object `{login: "..."}` — always extract `.author.login`.
+**Notes**: Fetching files requires 1 API call per PR — for 20+ PRs, prioritize overlap candidates. The `author` field is an object; always extract `.author.login`.
 
 ### Analysis
 
@@ -181,7 +168,6 @@ Note: Phase 3 (posting comments) is NOT offered here — it requires the drafts
 After displaying the triage table, copy to clipboard using platform-appropriate command:
 
 ```bash
-# Detect platform and copy
 UNAME=$(uname -s)
 if [ "$UNAME" = "Darwin" ]; then
   pbcopy <<'EOF'
diff --git a/examples/skills/release-notes-generator/SKILL.md b/examples/skills/release-notes-generator/SKILL.md
index a61b0c2..5a15b88 100644
--- a/examples/skills/release-notes-generator/SKILL.md
+++ b/examples/skills/release-notes-generator/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: release-notes-generator
-description: Generate release notes in 3 formats (CHANGELOG.md, PR body, Slack announcement) from git commits. Automatically categorizes changes and converts technical language to user-friendly messaging. Use when preparing a production release.
+description: "Generate release notes in 3 formats (CHANGELOG.md, PR body, Slack announcement) from git commits. Automatically categorizes changes and converts technical language to user-friendly messaging. Use for releases, changelogs, version notes, what's new summaries, or ship announcements."
 tags: [release-notes, changelog, slack, git, automation]
 ---
 
@@ -8,25 +8,14 @@ tags: [release-notes, changelog, slack, git, automation]
 
 Generate comprehensive release notes in 3 formats from git commits.
 
-## When to Use This Skill
+## Workflow
 
-- Preparing a production release (develop -> main)
-- Creating release PR with proper documentation
-- Generating Slack announcement for stakeholders
-- Updating CHANGELOG.md with new version
-- Analyzing commits since last release
-
-## What This Skill Does
-
-1. **Analyzes Git History**: Scans commits since last release tag or specified version
-2. **Fetches PR Details**: Gets PR titles, descriptions, and labels via `gh api`
-3. **Categorizes Changes**: Groups into features, bug fixes, improvements, security, breaking changes
-4. **Generates 3 Outputs**:
-   - **CHANGELOG.md section** (technical, complete)
-   - **PR Release body** (semi-technical, checklist)
-   - **Slack message** (product-focused, user-friendly)
-5. **Transforms Language**: Converts technical jargon to accessible messaging
-6. **Migration Alert**: Displays prominent warning if database migrations are required
+1. **Analyze git history** since last release tag or specified version
+2. **Fetch PR details** (titles, descriptions, labels) via `gh api`
+3. **Categorize changes** into features, bug fixes, improvements, security, breaking changes
+4. **Generate 3 outputs**: CHANGELOG.md section (technical), PR release body (semi-technical), Slack message (user-friendly)
+5. **Transform language** from technical jargon to accessible messaging
+6. **Alert on migrations** if database migrations are detected
 
 ## How to Use
 
diff --git a/examples/skills/rtk-optimizer/SKILL.md b/examples/skills/rtk-optimizer/SKILL.md
index 003736c..2e6f87d 100644
--- a/examples/skills/rtk-optimizer/SKILL.md
+++ b/examples/skills/rtk-optimizer/SKILL.md
@@ -1,144 +1,92 @@
 ---
 name: rtk-optimizer
-description: Optimize command outputs with RTK (Rust Token Killer) for 70% token reduction
+description: "Wrap high-verbosity shell commands with RTK to reduce token consumption. Use when running git log, git diff, cargo test, pytest, or other verbose CLI output that wastes context window tokens."
 version: 1.0.0
 tags: [optimization, tokens, efficiency, git]
 ---
 
 # RTK Optimizer Skill
 
-**Purpose**: Automatically suggest RTK wrappers for high-verbosity commands to reduce token consumption.
+Automatically suggest and apply RTK (Rust Token Killer) wrappers for verbose commands, reducing token usage by ~73% on average.
 
 ## How It Works
 
 1. **Detect high-verbosity commands** in user requests
-2. **Suggest RTK wrapper** if applicable
+2. **Suggest RTK wrapper** with expected savings
 3. **Execute with RTK** when user confirms
-4. **Track savings** over session
+4. **Track savings** over session via `rtk gain`
+
+## Prerequisites
+
+```bash
+rtk --version  # Requires rtk 0.16.0+
+
+# Install if needed:
+brew install rtk-ai/tap/rtk    # macOS/Linux
+cargo install rtk               # All platforms
+```
 
 ## Supported Commands
 
-### Git (>70% reduction)
-- `git log` → `rtk git log` (92.3% reduction)
-- `git status` → `rtk git status` (76.0% reduction)
-- `find` → `rtk find` (76.3% reduction)
-
-### Medium-Value (50-70% reduction)
-- `git diff` → `rtk git diff` (55.9% reduction)
-- `cat <large-file>` → `rtk read <file>` (62.5% reduction)
-
-### JS/TS Stack (70-90% reduction)
-- `pnpm list` → `rtk pnpm list` (82% reduction)
-- `pnpm test` / `vitest run` → `rtk vitest run` (90% reduction)
-
-### Rust Toolchain (80-90% reduction)
-- `cargo test` → `rtk cargo test` (90% reduction)
-- `cargo build` → `rtk cargo build` (80% reduction)
-- `cargo clippy` → `rtk cargo clippy` (80% reduction)
-
-### Python & Go (90% reduction)
-- `pytest` → `rtk python pytest` (90% reduction)
-- `go test` → `rtk go test` (90% reduction)
-
-### GitHub CLI (79-87% reduction)
-- `gh pr view` → `rtk gh pr view` (87% reduction)
-- `gh pr checks` → `rtk gh pr checks` (79% reduction)
-
-### File Operations
-- `ls` → `rtk ls` (condensed output)
-- `grep` → `rtk grep` (filtered output)
-
-## Activation Examples
-
-**User**: "Show me the git history"
-**Skill**: Detects `git log` → Suggests `rtk git log` → Explains 92.3% token savings
-
-**User**: "Find all markdown files"
-**Skill**: Detects `find` → Suggests `rtk find "*.md" .` → Explains 76.3% savings
-
-## Installation Check
-
-Before first use, verify RTK is installed:
-```bash
-rtk --version  # Should output: rtk 0.16.0+
-```
-
-If not installed:
-```bash
-# Homebrew (macOS/Linux)
-brew install rtk-ai/tap/rtk
-
-# Cargo (all platforms)
-cargo install rtk
-```
+| Command | RTK Equivalent | Reduction |
+|---------|---------------|-----------|
+| `git log` | `rtk git log` | 92% (13,994 -> 1,076 chars) |
+| `git status` | `rtk git status` | 76% |
+| `git diff` | `rtk git diff` | 56% (15,815 -> 6,982 chars) |
+| `find` | `rtk find` | 76% |
+| `cat <large-file>` | `rtk read <file>` | 63% (163K -> 61K chars) |
+| `pnpm list` | `rtk pnpm list` | 82% |
+| `vitest run` / `pnpm test` | `rtk vitest run` | 90% |
+| `cargo test` | `rtk cargo test` | 90% |
+| `cargo build` | `rtk cargo build` | 80% |
+| `cargo clippy` | `rtk cargo clippy` | 80% |
+| `pytest` | `rtk python pytest` | 90% |
+| `go test` | `rtk go test` | 90% |
+| `gh pr view` | `rtk gh pr view` | 87% |
+| `gh pr checks` | `rtk gh pr checks` | 79% |
+| `ls` | `rtk ls` | condensed |
+| `grep` | `rtk grep` | filtered |
 
 ## Usage Pattern
 
 ```markdown
-# When user requests high-verbosity command:
+# When user requests a verbose command:
 
-1. Acknowledge request
-2. Suggest RTK optimization:
-   "I'll use `rtk git log` to reduce token usage by ~92%"
-3. Execute RTK command
-4. Track savings (optional):
-   "Saved ~13K tokens (baseline: 14K, RTK: 1K)"
+1. Acknowledge the request
+2. Suggest RTK: "I'll use `rtk git log` to reduce token usage by ~92%"
+3. Execute the RTK-wrapped command
+4. Report savings: "Saved ~13K tokens (baseline: 14K, RTK: 1K)"
 ```
 
+## Activation Examples
+
+**User**: "Show me the git history"
+**Action**: Detect `git log` -> execute `rtk git log` -> report 92% savings
+
+**User**: "Run the test suite"
+**Action**: Detect `cargo test` / `pytest` -> execute `rtk cargo test` -> report 90% savings
+
+## When to Skip RTK
+
+- **Small outputs** (<100 chars): Overhead not worth it
+- **Claude built-in tools**: Grep/Read tools are already optimized
+- **Interactive commands**: RTK is for batch/non-interactive output only
+- **Multiple piped commands**: Wrap the outermost command, not each step
+
+## Error Handling
+
+- If `rtk` is not found, fall back to the raw command and suggest installation
+- If RTK output is empty or malformed, re-run without RTK and report the issue
+- If RTK version is outdated, warn about potential breaking changes (rapid release cadence)
+
 ## Session Tracking
 
-Optional: Track cumulative savings across session:
-
 ```bash
-# At session end
-rtk gain  # Shows total token savings for session (SQLite-backed)
+rtk gain  # Shows cumulative token savings for the session (SQLite-backed)
 ```
 
-## Edge Cases
-
-- **Small outputs** (<100 chars): Skip RTK (overhead not worth it)
-- **Already using Claude tools**: Grep/Read tools are already optimized
-- **Multiple commands**: Batch with RTK wrapper once, not per command
-
-## Configuration
-
-Enable via CLAUDE.md:
-```markdown
-## Token Optimization
-
-Use RTK (Rust Token Killer) for high-verbosity commands:
-- git operations (log, status, diff)
-- package managers (pnpm, npm)
-- build tools (cargo, go)
-- test frameworks (vitest, pytest)
-- file finding and reading
-```
-
-## Metrics (Verified)
-
-Based on real-world testing:
-- `git log`: 13,994 chars → 1,076 chars (92.3% reduction)
-- `git status`: 100 chars → 24 chars (76.0% reduction)
-- `find`: 780 chars → 185 chars (76.3% reduction)
-- `git diff`: 15,815 chars → 6,982 chars (55.9% reduction)
-- `read file`: 163,587 chars → 61,339 chars (62.5% reduction)
-
-**Average: 72.6% token reduction**
-
-## Limitations
-
-- 446 stars on GitHub, actively maintained (30 releases in 23 days)
-- Not suitable for interactive commands
-- Rapid development cadence (check for breaking changes)
-
-## Recommendation
-
-**Use RTK for**: git workflows, file operations, test frameworks, build tools, package managers
-**Skip RTK for**: small outputs, quick exploration, interactive commands
-
 ## References
 
 - RTK GitHub: https://github.com/rtk-ai/rtk
-- RTK Website: https://www.rtk-ai.app/
 - Evaluation: `docs/resource-evaluations/rtk-evaluation.md`
 - CLAUDE.md template: `examples/claude-md/rtk-optimized.md`
diff --git a/examples/skills/skill-creator/SKILL.md b/examples/skills/skill-creator/SKILL.md
index fe697c0..6bd9aca 100644
--- a/examples/skills/skill-creator/SKILL.md
+++ b/examples/skills/skill-creator/SKILL.md
@@ -1,23 +1,21 @@
 ---
 name: skill-creator
-description: Create new Claude Code skills with proper structure, YAML frontmatter, and bundled resources. Generates skill templates following best practices for modular, self-contained capability packages.
+description: "Scaffold a new Claude Code skill with SKILL.md, frontmatter, and bundled resources. Use when creating a custom skill, standardizing skill structure across a team, or packaging a skill for distribution."
 tags: [meta, skill, generator, claude-code]
 ---
 
 # Skill Creator
 
-This skill helps you create new Claude Code skills with proper structure and best practices.
+Generate new Claude Code skills with correct directory structure, YAML frontmatter, and optional bundled resources.
 
-## When to Use This Skill
+## When to Use
 
-- Creating a new custom skill for your project
-- Standardizing skill structure across your team
+- Creating a new custom skill for a project
+- Standardizing skill structure across a team
 - Generating skill templates with scripts, references, and assets
 - Packaging skills for distribution
 
-## Skill Structure
-
-A Claude skill consists of:
+## Skill Directory Structure
 
 ```
 skill-name/
@@ -27,99 +25,71 @@ skill-name/
 └── assets/           # Optional: Templates, images, boilerplate (not loaded into context)
 ```
 
-## SKILL.md Format
+## Workflow
 
-Every skill requires a `SKILL.md` file with:
-
-```markdown
----
-name: skill-name
-description: One-line description of what the skill does and when to use it.
----
-
-# Skill Name
-
-Brief introduction explaining the skill's purpose.
-
-## When to Use This Skill
-
-- Trigger condition 1
-- Trigger condition 2
-- Trigger condition 3
-
-## What This Skill Does
-
-1. **Step 1**: Description
-2. **Step 2**: Description
-3. **Step 3**: Description
-
-## How to Use
-
-### Basic Usage
-[Examples of how to invoke the skill]
-
-### With Options
-[Advanced usage patterns]
-
-## Example
-
-**User**: "Example prompt"
-
-**Output**:
-[Example output]
-
-## Tips
-
-- Best practice 1
-- Best practice 2
-
-## Related Use Cases
-
-- Related task 1
-- Related task 2
-```
-
-## How to Use
-
-### Create a New Skill
+### 1. Create the Skill
 
 ```
 Create a new skill called "my-skill-name" in ~/.claude/skills/
 ```
 
-### Create with Specific Purpose
+Or with a specific purpose:
 
 ```
 Create a skill for generating release notes from git commits,
 with templates for CHANGELOG.md and Slack announcements
 ```
 
-### Initialize Skill Structure
-
-Run the initialization script:
+Or via the initialization script:
 
 ```bash
 python3 ~/.claude/skills/skill-creator/scripts/init_skill.py <skill-name> --path <output-directory>
 ```
 
-### Package Skill for Distribution
+### 2. Generated SKILL.md Template
+
+The created SKILL.md follows this structure:
+
+```markdown
+---
+name: skill-name
+description: "What the skill does. Use when [trigger conditions]."
+---
+
+# Skill Name
+
+## When to Use
+- Trigger condition 1
+- Trigger condition 2
+
+## What This Skill Does
+1. **Step 1**: Description
+2. **Step 2**: Description
+
+## How to Use
+[Usage examples]
+
+## Example
+**User**: "Example prompt"
+**Output**: [Example output]
+```
+
+### 3. Validate the Skill
+
+After creation, verify:
+
+1. **Frontmatter**: `name` is kebab-case, 1-64 chars; `description` is a quoted string with "Use when" clause
+2. **Content**: Has "When to Use" section with trigger conditions and at least one usage example
+3. **Structure**: SKILL.md is under 5000 words; references and assets are in correct subdirectories
+4. **Test**: Invoke the skill with a real use case and confirm expected output
+
+### 4. Package for Distribution (Optional)
 
 ```bash
 python3 ~/.claude/skills/skill-creator/scripts/package_skill.py <path/to/skill-folder> [output-directory]
 ```
 
-## Design Principles
-
-### Progressive Disclosure
-
-Context loads hierarchically to optimize token usage:
-1. **Metadata** (~100 words): Always present via skill description
-2. **SKILL.md** (<5k words): Loaded when skill is triggered
-3. **Bundled resources**: Loaded as needed during execution
-
-### Organizational Patterns
-
-Choose the pattern that fits your skill:
+## Organizational Patterns
 
 | Pattern | Best For | Structure |
 |---------|----------|-----------|
@@ -128,59 +98,22 @@ Choose the pattern that fits your skill:
 | **Reference/Guidelines** | Standards, specs | Rules and examples |
 | **Capabilities-Based** | Interrelated features | Feature descriptions |
 
-### Naming Conventions
-
-- Use `kebab-case` for skill names: `release-notes-generator`
-- Use descriptive names that indicate purpose
-- Keep names concise but meaningful
-
-## Bundled Resources
-
-### scripts/
-
-Executable code for deterministic, repeatable tasks:
-- `init_skill.py` - Initialize new skill structure
-- `package_skill.py` - Package skill for distribution
-
-### references/
-
-Documentation loaded contextually:
-- API documentation
-- Style guides
-- Domain knowledge
-
-### assets/
-
-Templates and resources (not auto-loaded):
-- Output templates
-- Boilerplate code
-- Images and fonts
-
 ## Example: Creating a Release Notes Skill
 
-**User**: "Create a skill for generating release notes with 3 output formats: CHANGELOG.md, PR body, and Slack message"
+**User**: "Create a skill for generating release notes with 3 output formats"
 
 **Steps**:
-1. Initialize structure: `init_skill.py release-notes-generator --path ~/.claude/skills/`
-2. Add templates to `assets/`:
-   - `changelog-template.md`
-   - `pr-release-template.md`
-   - `slack-template.md`
-3. Add transformation rules to `references/`:
-   - `tech-to-product-mappings.md`
+1. Initialize: `init_skill.py release-notes-generator --path ~/.claude/skills/`
+2. Add templates to `assets/`: `changelog-template.md`, `pr-release-template.md`, `slack-template.md`
+3. Add rules to `references/`: `tech-to-product-mappings.md`
 4. Complete `SKILL.md` with usage instructions
-5. Package: `package_skill.py ~/.claude/skills/release-notes-generator`
+5. Validate: check frontmatter, test with a real commit range
+6. Package: `package_skill.py ~/.claude/skills/release-notes-generator`
 
 ## Tips
 
 - Keep SKILL.md under 5000 words for efficient context usage
-- Use references/ for domain knowledge that doesn't change often
-- Put templates in assets/ so they're not auto-loaded
-- Test your skill with real use cases before packaging
-- Include concrete examples in your SKILL.md
-
-## Related Use Cases
-
-- Creating project-specific automation skills
-- Building team-shared development workflows
-- Packaging reusable Claude capabilities
+- Use `references/` for domain knowledge that doesn't change often
+- Put templates in `assets/` so they're not auto-loaded into context
+- Always include a "Use when" clause in the description frontmatter
+- Test with real use cases before packaging
diff --git a/examples/skills/talk-pipeline/orchestrator/SKILL.md b/examples/skills/talk-pipeline/orchestrator/SKILL.md
index 931ac9b..c956c19 100644
--- a/examples/skills/talk-pipeline/orchestrator/SKILL.md
+++ b/examples/skills/talk-pipeline/orchestrator/SKILL.md
@@ -1,12 +1,8 @@
 ---
 name: talk-pipeline
-description: Orchestrator for the complete talk preparation pipeline (REX or Concept mode). Runs all 6 stages in sequence with human-in-the-loop checkpoints.
+description: "Orchestrates the complete talk preparation pipeline from raw material to revision sheets, running 6 stages in sequence with human-in-the-loop checkpoints for REX or Concept mode talks. Use when starting a new talk pipeline, resuming a pipeline from a specific stage, or running the full end-to-end preparation workflow."
 tags: [talk, pipeline, presentation, orchestrator]
-allowed-tools:
-  - Write
-  - Read
-  - AskUserQuestion
-  - Task
+allowed-tools: "Write, Read, AskUserQuestion, Task"
 ---
 
 # Talk Pipeline Orchestrator
diff --git a/examples/skills/talk-pipeline/stage-1-extract/SKILL.md b/examples/skills/talk-pipeline/stage-1-extract/SKILL.md
index e64ae1b..aeedafd 100644
--- a/examples/skills/talk-pipeline/stage-1-extract/SKILL.md
+++ b/examples/skills/talk-pipeline/stage-1-extract/SKILL.md
@@ -1,11 +1,8 @@
 ---
 name: talk-stage1-extract
-description: Stage 1 — Extract and structure source material into a talk summary. Auto-detects REX vs Concept type.
+description: "Extracts and structures source material (articles, transcripts, notes) into a talk summary with narrative arc, themes, metrics, and gaps. Auto-detects REX vs Concept type. Use when starting a new talk from any source material or auditing existing material before committing to a talk."
 tags: [talk, pipeline, presentation, stage-1]
-allowed-tools:
-  - Write
-  - Read
-  - AskUserQuestion
+allowed-tools: "Write, Read, AskUserQuestion"
 ---
 
 # Talk Stage 1: Extract
diff --git a/examples/skills/talk-pipeline/stage-2-research/SKILL.md b/examples/skills/talk-pipeline/stage-2-research/SKILL.md
index 2a97f44..3c19a7b 100644
--- a/examples/skills/talk-pipeline/stage-2-research/SKILL.md
+++ b/examples/skills/talk-pipeline/stage-2-research/SKILL.md
@@ -1,11 +1,8 @@
 ---
 name: talk-stage2-research
-description: Stage 2 (REX mode only) — Git archaeology, changelog analysis, verified factual timeline. Skip automatically in Concept mode.
+description: "Performs git archaeology, changelog analysis, and builds a verified factual timeline by cross-referencing git history with source material. REX mode only — skipped automatically in Concept mode. Use when building a REX talk and you need verified commit metrics, release timelines, and contributor data from a git repository."
 tags: [talk, pipeline, presentation, stage-2, git]
-allowed-tools:
-  - Write
-  - Read
-  - Bash
+allowed-tools: "Write, Read, Bash"
 ---
 
 # Talk Stage 2: Research (REX mode only)
diff --git a/examples/skills/talk-pipeline/stage-3-concepts/SKILL.md b/examples/skills/talk-pipeline/stage-3-concepts/SKILL.md
index e2a0af4..d2cad5a 100644
--- a/examples/skills/talk-pipeline/stage-3-concepts/SKILL.md
+++ b/examples/skills/talk-pipeline/stage-3-concepts/SKILL.md
@@ -1,10 +1,8 @@
 ---
 name: talk-stage3-concepts
-description: Stage 3 — Build a numbered, scored concept catalogue. Every concept gets HIGH / MEDIUM / LOW talk-potential rating.
+description: "Builds a numbered, categorized concept catalogue from the talk summary and timeline, scoring each concept HIGH / MEDIUM / LOW for talk potential with optional repo enrichment. Use when you need a structured inventory of concepts before choosing a talk angle, or when assessing which ideas have the strongest presentation potential."
 tags: [talk, pipeline, presentation, stage-3]
-allowed-tools:
-  - Write
-  - Read
+allowed-tools: "Write, Read"
 ---
 
 # Talk Stage 3: Concepts
diff --git a/examples/skills/talk-pipeline/stage-4-position/SKILL.md b/examples/skills/talk-pipeline/stage-4-position/SKILL.md
index c73b4bd..57f5a44 100644
--- a/examples/skills/talk-pipeline/stage-4-position/SKILL.md
+++ b/examples/skills/talk-pipeline/stage-4-position/SKILL.md
@@ -1,11 +1,8 @@
 ---
 name: talk-stage4-position
-description: Stage 4 — Strategic angles, titles, descriptions, peer feedback draft. Includes mandatory CHECKPOINT before script can start.
+description: "Generates 3-4 strategic talk angles with strength/weakness analysis, title options, CFP descriptions, and a peer feedback draft, then enforces a mandatory CHECKPOINT for user confirmation before scripting. Use when deciding how to frame a talk, preparing a CFP submission, or choosing between multiple narrative angles."
 tags: [talk, pipeline, presentation, stage-4, checkpoint]
-allowed-tools:
-  - Write
-  - Read
-  - AskUserQuestion
+allowed-tools: "Write, Read, AskUserQuestion"
 ---
 
 # Talk Stage 4: Position + CHECKPOINT
diff --git a/examples/skills/talk-pipeline/stage-5-script/SKILL.md b/examples/skills/talk-pipeline/stage-5-script/SKILL.md
index 645789e..7c4ff21 100644
--- a/examples/skills/talk-pipeline/stage-5-script/SKILL.md
+++ b/examples/skills/talk-pipeline/stage-5-script/SKILL.md
@@ -1,10 +1,8 @@
 ---
 name: talk-stage5-script
-description: Stage 5 — 5-act pitch with speaker notes, slide spec, and Kimi prompt for AI slide generation. Requires validated angle + title from Stage 4.
+description: "Produces a complete 5-act pitch with speaker notes, a slide-by-slide specification, and a ready-to-paste Kimi prompt for AI slide generation. Requires validated angle and title from Stage 4. Use when you have a confirmed talk angle and need the full script, slide spec, and AI-generated presentation prompt."
 tags: [talk, pipeline, presentation, stage-5, kimi]
-allowed-tools:
-  - Write
-  - Read
+allowed-tools: "Write, Read"
 ---
 
 # Talk Stage 5: Script
diff --git a/examples/skills/talk-pipeline/stage-6-revision/SKILL.md b/examples/skills/talk-pipeline/stage-6-revision/SKILL.md
index 3369702..0aad3f6 100644
--- a/examples/skills/talk-pipeline/stage-6-revision/SKILL.md
+++ b/examples/skills/talk-pipeline/stage-6-revision/SKILL.md
@@ -1,10 +1,8 @@
 ---
 name: talk-stage6-revision
-description: Stage 6 — Revision sheets for during and after the talk. Master concept table, Q&A cheat-sheet, glossary, external resources.
+description: "Produces revision sheets with quick navigation by act, a master concept-to-URL table, Q&A cheat-sheet with 6-10 anticipated questions, glossary, and external resources list. Use when preparing for a talk with Q&A, creating shareable reference material for attendees, or building a safety-net glossary for live delivery."
 tags: [talk, pipeline, presentation, stage-6]
-allowed-tools:
-  - Write
-  - Read
+allowed-tools: "Write, Read"
 ---
 
 # Talk Stage 6: Revision
diff --git a/examples/skills/voice-refine/SKILL.md b/examples/skills/voice-refine/SKILL.md
index 3ab0793..e92c805 100644
--- a/examples/skills/voice-refine/SKILL.md
+++ b/examples/skills/voice-refine/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: voice-refine
-description: Transform verbose voice input into optimized Claude prompts
+description: "Transform verbose voice input into structured, token-efficient Claude prompts. Use when cleaning up voice memos, dictation output, or speech-to-text transcriptions that contain filler words, repetitions, and unstructured thoughts."
 allowed-tools: Read
 context: inherit
 agent: specialist
@@ -85,39 +85,11 @@ dans le projet donc faut que ça matche avec ça...
 | Information retention | >95% |
 | Structure clarity | High |
 
-## Integration with Voice Tools
+## Filtering Rules
 
-### Wispr Flow
-1. Dictate with `Cmd+Shift+Space`
-2. Paste into Claude Code
-3. Run `/voice-refine`
+**Remove**: filler words ("euh", "um", "like", "basically"), repetitions, tangents, hedging ("maybe", "probably" unless relevant), politeness padding ("please", "could you").
 
-### Superwhisper
-1. Record with hotkey
-2. Text appears in active window
-3. Run `/voice-refine` to structure
-
-### macOS Dictation
-1. `Fn Fn` to start
-2. Speak naturally
-3. Run `/voice-refine` to clean up
-
-## What Gets Removed
-
-- Filler words: "euh", "um", "like", "you know", "basically"
-- Repetitions: same concept stated multiple ways
-- Tangents: off-topic thoughts
-- Hedging: "maybe", "I think", "probably" (unless relevant)
-- Politeness padding: "please", "could you", "I'd like"
-
-## What Gets Preserved
-
-- Technical requirements
-- Constraints and limitations
-- Context about existing code
-- Expected output format
-- Edge cases mentioned
-- Business logic rules
+**Preserve**: technical requirements, constraints, existing code context, expected output format, edge cases, business logic rules.
 
 ## See Also