Initial commit

references/common-pitfalls.md

@@ -0,0 +1,633 @@
+# Common Pitfalls
+
+Common mistakes that reduce skill quality and how to fix them.
+
+## 1. Bloated SKILL.md
+
+### Problem
+
+Including everything in SKILL.md instead of using references/.
+
+**Example**:
+```markdown
+# API Client
+
+[500 words of background]
+
+## Complete API Documentation
+[5000 words of every endpoint]
+
+## All Configuration Options
+[2000 words of config details]
+
+## Comprehensive Examples
+[50 examples covering every scenario]
+
+## Troubleshooting Guide
+[30 common issues]
+```
+
+**Impact**:
+- Loads 10k+ tokens every time skill triggers
+- Context waste for simple tasks
+- Harder to maintain
+- Difficult to navigate
+
+### Fix
+
+Move detailed content to references/, keep SKILL.md lean:
+
+```markdown
+# API Client
+
+## Quick Start
+
+Set API key:
+```bash
+export API_KEY="your-key"
+```
+
+Make request:
+```python
+response = requests.get(url, headers={"Authorization": f"Bearer {API_KEY}"})
+```
+
+For complete API documentation, see [api-reference.md](references/api-reference.md).
+For configuration options, see [configuration.md](references/configuration.md).
+```
+
+**Target**: SKILL.md under 1500 words (~5k tokens)
+
+---
+
+## 2. Duplicate Content
+
+### Problem
+
+Same information repeated in multiple places.
+
+**Example**:
+
+SKILL.md:
+```markdown
+## Authentication
+Set API_KEY environment variable. Get keys from dashboard at https://example.com/keys.
+Keys must be 32 hex characters. Rotate every 90 days.
+```
+
+references/api-reference.md:
+```markdown
+## Authentication
+Set API_KEY environment variable. Obtain from dashboard...
+[same content repeated]
+```
+
+**Impact**:
+- Wastes tokens
+- Maintenance nightmare (update must happen in multiple places)
+- Inconsistencies when one copy gets updated
+
+### Fix
+
+Put detailed info in ONE place, link from others:
+
+SKILL.md:
+```markdown
+## Quick Start
+
+Set API key:
+```bash
+export API_KEY="your-key"
+```
+
+For authentication details, see [api-reference.md](references/api-reference.md#authentication).
+```
+
+references/api-reference.md:
+```markdown
+## Authentication
+
+Obtain API keys from the dashboard at https://example.com/keys.
+
+**Requirements**:
+- Format: 32 hexadecimal characters
+- Rotation: Every 90 days
+- Storage: Environment variable `API_KEY`
+...
+```
+
+---
+
+## 3. Poor Description in Frontmatter
+
+### Problem
+
+Vague or incomplete description that doesn't help Claude discover when to use the skill.
+
+**Bad examples**:
+```yaml
+description: PDF tool
+```
+- Too vague. What does it do with PDFs?
+
+```yaml
+description: Extract text from PDFs using pdfplumber library with support for tables and forms
+```
+- Implementation detail. Doesn't say when to use.
+
+```yaml
+description: A helpful utility for working with PDF documents
+```
+- Generic fluff. No specifics.
+
+### Fix
+
+Include BOTH what it does AND when to use it:
+
+```yaml
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+```
+
+**Good description formula**:
+`[What it does]. Use when [triggering conditions/keywords].`
+
+---
+
+## 4. Missing Safety Warnings
+
+### Problem
+
+Destructive operations without warnings or validation.
+
+**Example**:
+```markdown
+## Deploy to Production
+
+Run: `./deploy.sh production`
+```
+
+**Impact**:
+- Users might run dangerous commands accidentally
+- No guidance on prerequisites
+- No rollback plan
+
+### Fix
+
+Add warnings, validation, and recovery:
+
+```markdown
+## Deploy to Production
+
+**⚠️  WARNING**: This deploys to production. Ensure tests pass before proceeding.
+
+**Prerequisites**:
+- All tests passing: `make test`
+- Code reviewed and merged
+- Staging deployment successful
+
+**Deploy**:
+```bash
+# Verify tests first
+make test || { echo "Tests failed"; exit 1; }
+
+# Deploy
+./deploy.sh production
+```
+
+**If deployment fails**:
+1. Check logs: `tail -f /var/log/deploy.log`
+2. Rollback: `./deploy.sh rollback`
+3. Investigate: Review error messages
+```
+
+---
+
+## 5. No Examples or Bad Examples
+
+### Problem
+
+Either no examples, or examples that are too complex/not representative.
+
+**No examples**:
+```markdown
+## Usage
+
+Use the tool to process files. Various options are available.
+```
+
+**Overly complex examples**:
+```markdown
+## Example
+
+```python
+# Complete production-ready example with error handling,
+# logging, retries, caching, metrics, and all edge cases
+import logging
+import time
+from functools import wraps
+...
+[200 lines]
+```
+```
+
+**Impact**:
+- Users don't know how to start
+- Complex examples obscure the core pattern
+
+### Fix
+
+Provide minimal, representative examples:
+
+```markdown
+## Quick Start
+
+Basic usage:
+```python
+import tool
+
+result = tool.process("input.txt")
+print(result)
+```
+
+With options:
+```python
+result = tool.process("input.txt", format="json", validate=True)
+```
+
+For advanced patterns, see [examples.md](references/examples.md).
+```
+
+**Good examples are**:
+- Minimal (remove non-essential code)
+- Representative (show common use case)
+- Runnable (actually work if copy-pasted)
+- Focused (one concept per example)
+
+---
+
+## 6. Inconsistent Terminology
+
+### Problem
+
+Same concept called by different names throughout the skill.
+
+**Example**:
+```markdown
+## Creating a Migration
+
+Generate new migration file:
+```bash
+./create-migration.sh add_users
+```
+
+## Running Migrations
+
+Execute all pending schema changes:
+```bash
+./run-migrations.sh
+```
+
+## Rolling Back
+
+Revert the last database modification:
+```bash
+./undo-migration.sh
+```
+```
+
+**Terms used**:
+- "migration", "schema changes", "database modification"
+- "create", "generate"
+- "run", "execute"
+- "rolling back", "revert", "undo"
+
+**Impact**: Confusing. Users wonder if these are different operations.
+
+### Fix
+
+Use consistent terminology:
+
+```markdown
+## Creating a Migration
+
+```bash
+./migrate.sh create add_users
+```
+
+## Running Migrations
+
+```bash
+./migrate.sh apply
+```
+
+## Rolling Back Migrations
+
+```bash
+./migrate.sh rollback
+```
+```
+
+**Pick one term and stick to it**:
+- Migration (not "schema change" or "database modification")
+- Create (not "generate")
+- Apply (not "run" or "execute")
+- Rollback (not "revert" or "undo")
+
+---
+
+## 7. Scope Creep
+
+### Problem
+
+Skill tries to do too many unrelated things.
+
+**Example**:
+```markdown
+# Developer Tools
+
+## Features
+- Run tests
+- Deploy code
+- Send emails
+- Process images
+- Generate reports
+- Manage databases
+- Create documentation
+- Monitor logs
+```
+
+**Impact**:
+- Unfocused and hard to maintain
+- Overlaps with other skills
+- Users confused about what it's for
+
+### Fix
+
+Split into focused skills:
+- testing-tools → Run tests
+- deployment → Deploy code
+- email-sender → Send emails
+- image-processor → Process images
+- etc.
+
+**Each skill should answer**: "What is the one thing this skill does well?"
+
+---
+
+## 8. Over-Prescription (High Freedom Task)
+
+### Problem
+
+Giving step-by-step instructions for a task that needs flexibility.
+
+**Example** (high freedom task with low freedom instructions):
+```markdown
+## Code Review
+
+1. Check line 1 for indentation
+2. Check line 2 for spacing
+3. Check line 3 for naming
+4. Check line 4 for...
+[prescriptive steps for creative task]
+```
+
+**Impact**: Constrains Claude unnecessarily, produces robotic results.
+
+### Fix
+
+Provide principles for high freedom tasks:
+
+```markdown
+## Code Review
+
+Review code for:
+- **Readability**: Clear naming, logical structure, appropriate comments
+- **Maintainability**: DRY principle, single responsibility, testable
+- **Performance**: Algorithm efficiency, resource usage
+- **Security**: Input validation, safe dependencies
+
+Consider the project's context and constraints when making recommendations.
+```
+
+---
+
+## 9. Under-Specification (Low Freedom Task)
+
+### Problem
+
+Vague instructions for a fragile operation that needs exact steps.
+
+**Example** (low freedom task with high freedom instructions):
+```markdown
+## Database Migration
+
+Migrate the database. Make sure everything works.
+```
+
+**Impact**: Critical operations fail due to missed steps or wrong order.
+
+### Fix
+
+Provide exact steps for low freedom tasks:
+
+```markdown
+## Database Migration
+
+**⚠️  CRITICAL**: Execute in exact order. Do not skip steps.
+
+1. **Backup**:
+   ```bash
+   ./backup.sh production_db backup_$(date +%Y%m%d).sql
+   ```
+
+2. **Test migration**:
+   ```bash
+   ./migrate.sh --dry-run
+   ```
+   Verify output shows expected changes.
+
+3. **Apply migration**:
+   ```bash
+   ./migrate.sh apply
+   ```
+
+4. **Verify**:
+   ```bash
+   ./health-check.sh database
+   ```
+   Must return "✓ Database healthy".
+
+5. **If failure**:
+   ```bash
+   ./migrate.sh rollback
+   ./restore.sh backup_$(date +%Y%m%d).sql
+   ```
+```
+
+---
+
+## 10. No Version or Changelog
+
+### Problem
+
+No way to track what changed or what version is current.
+
+**Example**:
+```markdown
+# API Client
+
+[no version info]
+[no changelog]
+[no update history]
+```
+
+**Impact**:
+- Users don't know if they have latest version
+- No record of what changed
+- Hard to troubleshoot version-specific issues
+
+### Fix
+
+Include version and changelog:
+
+```markdown
+# API Client
+
+**Version**: 2.1.0
+**Last Updated**: 2025-11-23
+
+...
+
+## Changelog
+
+### 2.1.0 (2025-11-23)
+- Add batch request support
+- Improve error handling
+
+### 2.0.0 (2025-10-15)
+- Breaking: Change authentication method
+- Add retry logic
+
+### 1.0.0 (2025-09-01)
+- Initial release
+```
+
+---
+
+## 11. Broken or Missing Links
+
+### Problem
+
+Links to references/ don't resolve or are missing.
+
+**Example**:
+
+SKILL.md:
+```markdown
+For details, see [advanced.md](references/advanced.md).
+```
+
+But file doesn't exist, or is named differently (`references/advanced-usage.md`).
+
+**Impact**: Users can't access detailed information.
+
+### Fix
+
+Verify all links:
+
+```bash
+# Check all markdown links in SKILL.md
+grep -o '\[.*\](.*\.md)' SKILL.md | while read link; do
+  file=$(echo "$link" | sed 's/.*(\(.*\))/\1/')
+  if [[ ! -f "$file" ]]; then
+    echo "Broken link: $link"
+  fi
+done
+```
+
+**Best practice**: After creating skill, test all links.
+
+---
+
+## 12. Marketing Language
+
+### Problem
+
+Promotional or fluffy language instead of direct instructions.
+
+**Example**:
+```markdown
+# Amazing Data Processor
+
+Transform your data workflow with our cutting-edge processing engine! Designed with developers in mind, this powerful tool revolutionizes...
+
+## Why Choose This Tool?
+
+Benefit from industry-leading performance and enterprise-grade reliability...
+```
+
+**Impact**: Wastes tokens without providing value.
+
+### Fix
+
+Be direct and actionable:
+
+```markdown
+# Data Processor
+
+Process CSV and JSON files with validation and transformation.
+
+## Quick Start
+
+Process CSV file:
+```bash
+process-data input.csv --format json --validate
+```
+```
+
+**Cut**:
+- Marketing superlatives ("amazing", "revolutionary")
+- Benefits lists ("why choose this")
+- Generic introductions
+- Promotional language
+
+**Keep**:
+- What it does
+- How to use it
+- Actual capabilities
+
+---
+
+## Quick Pitfall Checklist
+
+Run this check on any skill:
+
+**Content**:
+- [ ] No marketing fluff or superlatives
+- [ ] No duplicate content between files
+- [ ] Examples are minimal and representative
+- [ ] Instructions match freedom level
+
+**Structure**:
+- [ ] SKILL.md under 1500 words
+- [ ] Detailed content in references/
+- [ ] All links resolve
+- [ ] No scope creep (one focused purpose)
+
+**Language**:
+- [ ] No "new feature" or "recommended" hedging
+- [ ] Consistent terminology throughout
+- [ ] Direct, actionable instructions
+- [ ] Appropriate warnings for dangerous operations
+
+**Metadata**:
+- [ ] Description includes what and when
+- [ ] Version and changelog present
+- [ ] Clear frontmatter (name, description)
+
+**Safety**:
+- [ ] Dangerous operations have warnings
+- [ ] Prerequisites stated
+- [ ] Failure recovery documented
+
+If any checkbox fails, you've found a pitfall to fix.

references/examples.md

@@ -0,0 +1,379 @@
+# Review Examples
+
+This document provides concrete examples of using skill-reviewer to review different types of skills.
+
+## Example 1: Simple Skill Review
+
+### Skill Being Reviewed
+
+**Name**: commit-helper
+**Type**: Single-file skill (SKILL.md only, 287 words)
+**Purpose**: Generate git commit messages from staged changes
+
+### Review Process
+
+**Step 1: Load the skill**
+```bash
+cat ~/.claude/skills/commit-helper/SKILL.md
+```
+
+**Step 2: Check structure**
+- ✅ SKILL.md exists with valid frontmatter
+- ✅ No supporting files (appropriate for simple skill)
+- Word count: 287 words (19% of 1500-word budget)
+
+**Step 3: Apply 10-point checklist**
+
+1. ✅ **Progressive Disclosure**: All content in SKILL.md (appropriate for simple skill)
+2. ✅ **Mental Model Shift**: "Use when writing commit messages" (canonical)
+3. ✅ **Degree of Freedom**: Medium freedom with suggested patterns
+4. ✅ **SKILL.md Conciseness**: 287 words, lean and focused
+5. ✅ **Safety**: N/A (read-only git commands)
+6. ✅ **Resource Hygiene**: N/A (no references)
+7. ✅ **Consistency**: Clear terminology throughout
+8. ⚠️  **Testing Guidance**: No example output or verification steps
+9. 🔴 **Ownership**: Missing version and maintainer info
+10. ✅ **Tight Scope**: Focused solely on commit messages
+
+### Review Report
+
+```markdown
+# Skill Review: commit-helper
+
+**Date**: 2025-11-23
+**Reviewer**: Jane Doe
+**Type**: New
+
+## Summary
+
+Simple, well-structured skill for generating commit messages. Appropriate use of single-file structure for focused task. Missing ownership metadata and testing examples.
+
+## Checklist Results
+
+✅ Progressive Disclosure
+✅ Mental Model Shift
+✅ Degree of Freedom
+✅ SKILL.md Conciseness
+✅ Safety & Failure Handling
+✅ Resource Hygiene
+✅ Consistency
+⚠️  Testing Guidance - No example output
+🔴 Ownership - Missing version/maintainer
+✅ Tight Scope
+
+## Critical Issues
+
+1. **Missing Ownership**: Add version, date, and maintainer information
+
+## Improvements Needed
+
+1. **Testing Examples**: Add example of generated commit message format
+
+## Suggestions
+
+- Consider adding example output showing the format of generated commit messages
+- Add quick verification checklist at the end
+
+## Conclusion
+
+**Needs Revision** - Minor fixes needed for ownership metadata and testing guidance. Otherwise well-structured for its scope.
+```
+
+## Example 2: Complex Skill Review
+
+### Skill Being Reviewed
+
+**Name**: pdf-processing
+**Type**: Multi-file skill with scripts
+**Purpose**: Extract text, fill forms, merge PDFs
+
+### Review Process
+
+**Step 1: Load the skill**
+```bash
+ls -la ~/.claude/skills/pdf-processing/
+cat ~/.claude/skills/pdf-processing/SKILL.md
+```
+
+**Step 2: Check structure**
+```
+pdf-processing/
+├── SKILL.md (542 words)
+├── FORMS.md (824 words)
+├── REFERENCE.md (1,453 words)
+└── scripts/
+    ├── fill_form.py
+    └── validate.py
+```
+
+Total: 2,819 words across 3 markdown files
+
+**Step 3: Apply 10-point checklist**
+
+1. ⚠️  **Progressive Disclosure**: Too much detail in SKILL.md (542 words could be leaner)
+2. ✅ **Mental Model Shift**: "Use for PDF files" (canonical language)
+3. ✅ **Degree of Freedom**: High freedom with code examples
+4. ⚠️  **SKILL.md Conciseness**: 542 words (36% of budget, but includes code)
+5. ⚠️  **Safety**: Scripts lack input validation warnings
+6. ✅ **Resource Hygiene**: Clear references, organized structure
+7. ✅ **Consistency**: Consistent terminology
+8. ✅ **Testing Guidance**: Examples with expected outputs
+9. ✅ **Ownership**: Version 2.1.0, maintained by team
+10. 🔴 **Tight Scope**: Scope creep - includes Excel parsing (should be separate skill)
+
+### Review Report
+
+```markdown
+# Skill Review: pdf-processing
+
+**Date**: 2025-11-23
+**Reviewer**: John Smith
+**Type**: Update
+
+## Summary
+
+Well-organized multi-file skill with good progressive disclosure structure. Scope has expanded beyond PDFs to include Excel processing, which should be separated. Some safety warnings needed for file operations.
+
+## Checklist Results
+
+⚠️  Progressive Disclosure - SKILL.md could be leaner (move some code to REFERENCE.md)
+✅ Mental Model Shift
+✅ Degree of Freedom
+⚠️  SKILL.md Conciseness - 542 words (could reduce to ~400)
+⚠️  Safety & Failure Handling - Scripts need input validation warnings
+✅ Resource Hygiene
+✅ Consistency
+✅ Testing Guidance
+✅ Ownership
+🔴 Tight Scope - Includes Excel parsing (out of scope)
+
+## Critical Issues
+
+1. **Scope Creep**: Remove Excel parsing functionality and create separate skill
+   - Current: PDF + Excel in one skill (confusing)
+   - Recommended: Split into pdf-processing and excel-processing
+
+## Improvements Needed
+
+1. **Progressive Disclosure**: Move detailed code examples from SKILL.md to REFERENCE.md
+   - Keep only quick start example in SKILL.md
+   - Move API details and advanced examples to REFERENCE.md
+
+2. **Safety Warnings**: Add warnings for file operations
+   - Warn about overwriting files in merge operations
+   - Add note about validating PDF inputs before processing
+
+3. **SKILL.md Conciseness**: Reduce from 542 to ~400 words
+   - Keep Quick Start section
+   - Move detailed examples to REFERENCE.md
+
+## Suggestions
+
+- Consider adding TROUBLESHOOTING.md for common errors
+- Example in fill_form.py could use more comments
+- Update description to remove Excel references
+
+## Conclusion
+
+**Needs Revision** - Critical scope creep issue must be addressed by removing Excel functionality. Otherwise solid skill with good structure.
+```
+
+## Example 3: Quick Audit Review
+
+### Skill Being Reviewed
+
+**Name**: code-reviewer
+**Type**: Single-file skill
+**Purpose**: Review code for best practices
+
+### Quick Review (5-minute audit)
+
+**Focus areas for quick audit**:
+1. Progressive Disclosure ✅
+2. Mental Model Shift ✅
+3. Ownership 🔴
+4. Tight Scope ✅
+
+### Quick Findings
+
+```markdown
+# Quick Audit: code-reviewer
+
+**Date**: 2025-11-23
+**Type**: Audit
+
+## Quick Check
+
+✅ Progressive Disclosure - Appropriate for single file
+✅ Mental Model Shift - Canonical language
+🔴 Ownership - Missing version info
+✅ Tight Scope - Focused on code review
+
+## Action Items
+
+1. Add version and maintainer information
+2. Consider full review for other criteria
+
+## Status
+
+**Quick Fix Needed** - Add ownership metadata
+```
+
+## Example 4: Before/After Improvement
+
+### Before: Skill with Issues
+
+```yaml
+---
+name: data-processor
+description: Helps with data
+---
+
+# Data Processor
+
+## What This Does
+
+This is a new recommended tool for processing data files. You might want to use it when working with CSV, JSON, Excel, or database exports.
+
+## How to Use
+
+1. Load your file
+2. Pick what you want to do:
+   - Clean the data
+   - Transform the data
+   - Validate the data
+   - Export the data
+3. Run the processing
+4. Check the results
+
+## Advanced Features
+
+You can also use the advanced mode by setting the config...
+[500 more words of detailed configuration]
+
+## Notes
+
+Make sure Python is installed.
+```
+
+**Issues identified**:
+- ❌ Vague description ("Helps with data")
+- ❌ Mental model issues ("new recommended tool", "You might want to")
+- ❌ Too broad scope (CSV, JSON, Excel, databases)
+- ❌ No progressive disclosure (all details in SKILL.md)
+- ❌ Missing ownership information
+
+### After: Improved Version
+
+```yaml
+---
+name: csv-analyzer
+description: Analyze CSV files for data quality issues, missing values, and statistical summaries. Use when working with CSV data, data quality checks, or data profiling.
+---
+
+# CSV Analyzer
+
+## Quick Start
+
+Analyze a CSV file for quality issues:
+```python
+import pandas as pd
+df = pd.read_csv("data.csv")
+# I'll check for missing values, duplicates, and provide summary statistics
+```
+
+## Common Operations
+
+- Data quality assessment
+- Missing value detection
+- Statistical summaries
+- Duplicate identification
+
+For detailed configuration options, see [configuration.md](references/configuration.md).
+For examples of quality checks, see [examples.md](references/examples.md).
+
+## Requirements
+
+Requires pandas:
+```bash
+pip install pandas
+```
+
+## Quick Verification
+
+- [ ] Successfully reads CSV file
+- [ ] Reports missing values accurately
+- [ ] Provides statistical summary
+
+## Version
+
+**Version**: 1.0.0
+**Last Updated**: 2025-11-23
+**Maintainer**: team@example.com
+**Changelog**: See changelog.md
+```
+
+**Improvements**:
+- ✅ Specific description with trigger keywords
+- ✅ Canonical language ("Use when", direct instructions)
+- ✅ Tight scope (CSV only, not all data formats)
+- ✅ Progressive disclosure (details in references/)
+- ✅ Ownership information included
+- ✅ Testing verification checklist
+
+## Tips for Effective Reviews
+
+### Use the Right Review Type
+
+**Quick Audit** (5 minutes):
+- Check 4 key criteria: Progressive Disclosure, Mental Model, Ownership, Scope
+- Good for marketplace-wide audits
+- Identifies critical issues only
+
+**Standard Review** (15-20 minutes):
+- Apply all 10 checklist criteria
+- Good for new skills and significant updates
+- Provides comprehensive feedback
+
+**Deep Review** (30+ minutes):
+- Full checklist plus detailed examples testing
+- Review all reference files
+- Test any included scripts
+- Good for complex multi-file skills
+
+### Focus on High-Impact Issues
+
+**Critical (must fix)**:
+- Scope creep / overlapping functionality
+- Missing safety warnings for dangerous operations
+- Broken mental model (describing as "optional" or "new")
+
+**Important (should fix)**:
+- Missing ownership metadata
+- Poor progressive disclosure (bloated SKILL.md)
+- Vague description
+
+**Nice to have**:
+- Additional examples
+- Minor wording improvements
+- Formatting consistency
+
+### Common Patterns
+
+**Pattern: Marketing Language**
+```markdown
+❌ Before: "This amazing skill revolutionizes how you work with PDFs!"
+✅ After: "Extract text and fill forms in PDF files."
+```
+
+**Pattern: Optional Framing**
+```markdown
+❌ Before: "You can optionally use this skill when you need to..."
+✅ After: "Use for commit message generation from git diffs."
+```
+
+**Pattern: Scope Creep**
+```markdown
+❌ Before: "Process PDFs, Word docs, Excel files, and images"
+✅ After: "Process PDF files" (separate skills for other formats)
+```

references/mental-model-shift.md

@@ -0,0 +1,389 @@
+# Mental Model Shift
+
+Guide to positioning skills as canonical approaches rather than optional features.
+
+## The Principle
+
+When a skill provides a better way to do something, the documentation should reflect confidence in that approach. The feature isn't "new" or "recommended"—it IS the way things are done.
+
+**Mental model shift means**:
+- Feature becomes "the way" (not "a new way")
+- Documentation reflects this confidence
+- Alternative approaches are downgraded to "manual" or "advanced"
+
+## Language Patterns
+
+### ✅ Canonical Language (Good)
+
+**Presents as THE way**:
+```markdown
+# Session Registry
+
+Use the session registry for automatic session tracking.
+
+## Quick Start
+1. Create session: `create-session.sh -n my-session`
+2. Send commands: `safe-send.sh -s my-session -c "command"`
+```
+
+**Key phrases**:
+- "Use [tool] for [task]"
+- "Standard workflow"
+- "[Tool] handles [task]"
+- Direct imperatives ("Create a session", "Send commands")
+
+---
+
+### ❌ Optional Language (Bad)
+
+**Presents as A way among many**:
+```markdown
+# Session Registry (NEW!)
+
+The session registry is a new recommended feature you can use instead of manual socket management.
+
+## Two Approaches
+
+### Traditional: Manual Socket Management
+[old way]
+
+### New (Recommended): Session Registry
+[new way]
+
+You might want to consider using the session registry...
+```
+
+**Red flag phrases**:
+- "New feature" or "NEW!"
+- "Recommended" or "optional"
+- "You can use" or "you might want to"
+- "Instead of" or "alternative to"
+- Side-by-side old vs new comparisons
+- "Traditional" vs "modern"
+
+---
+
+## Documentation Structure
+
+### Primary Workflow First
+
+Place the canonical approach at the top as the default.
+
+**Good structure**:
+```markdown
+# Tool Name
+
+## Quick Start
+[Canonical approach]
+
+## Common Tasks
+[Using canonical approach]
+
+---
+
+## Alternative: Manual Approach
+
+For advanced users or special cases...
+```
+
+**Bad structure**:
+```markdown
+# Tool Name
+
+## Choose Your Approach
+
+### Option 1: Traditional Method (Still Supported)
+[Old way]
+
+### Option 2: New Registry Method (Recommended!)
+[New way]
+```
+
+---
+
+### Downgrade Alternatives
+
+When mentioning alternative approaches, position them as secondary.
+
+**Good** (alternative is clearly secondary):
+```markdown
+# Session Management
+
+Create and manage sessions using the session registry.
+
+## Creating Sessions
+```bash
+create-session.sh -n my-session --python
+```
+
+---
+
+## Manual Socket Management
+
+For advanced use cases requiring explicit socket control, you can manage sockets manually.
+See [manual-socket-management.md](references/manual-socket-management.md).
+```
+
+**Bad** (alternatives treated equally):
+```markdown
+# Session Management
+
+## Approach 1: Registry (Recommended)
+Use create-session.sh...
+
+## Approach 2: Manual Sockets (Traditional)
+Create sockets manually...
+
+Both approaches are fully supported. Choose based on your preferences.
+```
+
+---
+
+## Evolution Example: tmux Skill
+
+### Phase 1: Feature Addition (❌ Wrong)
+
+```markdown
+# tmux Skill
+
+## New Feature: Session Registry!
+
+We're excited to announce session registry support! This new recommended feature eliminates the need for manual socket management.
+
+### Traditional Workflow (Still Supported)
+1. Create socket: `tmux -S /tmp/my.sock new -d`
+2. Send commands: `tmux -S /tmp/my.sock send-keys...`
+
+### New Registry Workflow (Recommended!)
+1. Create session: `create-session.sh -n my-session`
+2. Send commands: `safe-send.sh -s my-session -c "command"`
+
+Consider migrating to the registry for a better experience!
+```
+
+**Problems**:
+- "New feature" announcement
+- "Recommended" implies optionality
+- Side-by-side comparison treats both as equal
+- "Consider migrating" is hesitant
+
+---
+
+### Phase 2: Mental Model Shift (✅ Right)
+
+```markdown
+# tmux Skill
+
+Use the session registry for automatic session tracking.
+
+## Quick Start
+
+Create a session:
+```bash
+create-session.sh -n my-session --python
+```
+
+Send commands:
+```bash
+safe-send.sh -s my-session -c "print('hello')"
+```
+
+Wait for output:
+```bash
+wait-for-text.sh -s my-session -p ">>>"
+```
+
+## Session Management
+
+List sessions:
+```bash
+list-sessions.sh
+```
+
+Clean up dead sessions:
+```bash
+cleanup-sessions.sh --dead
+```
+
+---
+
+## Alternative: Manual Socket Management
+
+For advanced scenarios requiring explicit socket control, see [manual-sockets.md](references/manual-sockets.md).
+```
+
+**Improvements**:
+- No "new" or "recommended" language
+- Registry is THE approach
+- Direct, confident instructions
+- Manual approach relegated to "Alternative" section
+- Documentation reflects "this is the way"
+
+---
+
+## Key Transformations
+
+### From Feature to Standard
+
+**Before**: "Session registry is a new feature"
+**After**: "Use the session registry"
+
+**Before**: "You can optionally use create-session.sh"
+**After**: "Create sessions with create-session.sh"
+
+**Before**: "The recommended approach is..."
+**After**: [Just describe the approach as the default]
+
+### From Optional to Canonical
+
+**Before**: "Consider using -s flag for convenience"
+**After**: "Use -s flag to specify the session"
+
+**Before**: "The -s flag is a shorthand that may be helpful"
+**After**: "The -s flag identifies the session by name"
+
+### From Hedging to Direct
+
+**Before**: "You might want to try the session registry"
+**After**: "The session registry tracks sessions automatically"
+
+**Before**: "It's recommended to clean up dead sessions regularly"
+**After**: "Clean up dead sessions with cleanup-sessions.sh"
+
+---
+
+## Section Positioning
+
+### Primary Content (80-90% of docs)
+
+Focus on the canonical approach:
+- Quick start
+- Common workflows
+- Standard examples
+- Main documentation
+
+### Alternative Content (10-20% of docs)
+
+Relegated to end or separate files:
+- "Alternative:" sections
+- "Advanced:" sections
+- "Manual:" approaches
+- Legacy compatibility
+
+---
+
+## Migration Guidance
+
+When transitioning from old to new approach:
+
+### During Migration
+
+Acknowledge the transition but frame it positively:
+
+```markdown
+# Tool Name
+
+Use [new approach] for [task].
+
+## Migrating from Manual Approach
+
+If you're currently using manual [old approach]:
+1. Replace [old command] with [new command]
+2. Remove [old pattern]
+3. Adopt [new pattern]
+
+Migration is straightforward and improves [benefit].
+```
+
+### After Migration Period
+
+Remove migration notices, treat new approach as standard:
+
+```markdown
+# Tool Name
+
+Use [new approach] for [task].
+
+## Alternative: Manual Approach
+For advanced cases, see [manual.md](references/manual.md).
+```
+
+---
+
+## Verification Checklist
+
+Mental model shift audit:
+
+Language:
+- [ ] No "new feature" or "NEW!" markers
+- [ ] No "recommended" or "optional" hedging
+- [ ] No side-by-side old vs new comparisons
+- [ ] Direct, imperative instructions
+- [ ] Confident tone throughout
+
+Structure:
+- [ ] Canonical approach presented first
+- [ ] Primary content focuses on canonical approach
+- [ ] Alternatives relegated to end or separate files
+- [ ] Section titles don't imply choice ("Quick Start" not "Option 1")
+
+Content:
+- [ ] Examples use canonical approach
+- [ ] Workflow descriptions assume canonical approach
+- [ ] Troubleshooting assumes canonical approach
+- [ ] Getting started uses canonical approach
+
+---
+
+## Common Mistakes
+
+### Mistake 1: Hedging with "Recommended"
+
+❌ "The recommended way is to use the registry"
+✅ "Use the registry for session management"
+
+**Why**: "Recommended" implies other approaches are equally valid.
+
+### Mistake 2: Feature Announcement Language
+
+❌ "We're introducing session registry support"
+✅ "Session registry provides automatic session tracking"
+
+**Why**: "Introducing" or "new" frames it as optional addition.
+
+### Mistake 3: Choice Architecture
+
+❌ "Choose between registry or manual approach based on your needs"
+✅ "Use registry for session management. For advanced cases requiring manual control, see..."
+
+**Why**: Presenting choice implies both are equal. Default should be clear.
+
+### Mistake 4: Qualification
+
+❌ "Session registry can help you manage sessions more easily"
+✅ "Session registry manages sessions automatically"
+
+**Why**: "Can help" and "more easily" undermine confidence.
+
+### Mistake 5: Comparison to Old Way
+
+❌ "Unlike manual socket management, session registry is automatic"
+✅ "Session registry tracks sessions automatically"
+
+**Why**: Mentioning the old way keeps it in the mental model.
+
+---
+
+## Summary
+
+**Mental model shift means**:
+- Documentation reflects the feature as canonical
+- Language is direct and confident
+- Alternatives are clearly secondary
+- No hedging or option-presenting
+
+**Key transformation**:
+- From: "New recommended feature you can optionally use"
+- To: "This is how you do it"
+
+**Test**: Read your documentation. If someone unfamiliar with the history would see multiple equally-presented approaches, the mental model shift is incomplete.

references/progressive-disclosure.md

@@ -0,0 +1,336 @@
+# Progressive Disclosure
+
+Guide to properly structuring information across the three levels of skill loading.
+
+## The Three Levels
+
+Skills use progressive disclosure to minimize context usage while maximizing discoverability.
+
+### Level 1: Metadata (Always Loaded)
+
+**What**: YAML frontmatter in SKILL.md
+**When**: Always (loaded at startup)
+**Token cost**: ~100 tokens per skill
+**Purpose**: Skill discovery and triggering
+
+```yaml
+---
+name: skill-name
+description: What the skill does and when to use it. Be comprehensive - this is how Claude discovers your skill.
+---
+```
+
+**Best practices**:
+- Description should answer: "What does this do?" and "When should I use it?"
+- Include trigger keywords users might mention
+- Be specific but concise (max 1024 characters)
+- No implementation details (those go in Level 2/3)
+
+**Example** (good):
+```yaml
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+```
+
+**Example** (bad):
+```yaml
+description: PDF tool. Uses pdfplumber library with various configuration options for text extraction, table parsing, and form filling operations on PDF documents.
+```
+
+---
+
+### Level 2: Instructions (Loaded When Triggered)
+
+**What**: The markdown body of SKILL.md
+**When**: When Claude triggers the skill
+**Token cost**: Should be under 5k tokens
+**Purpose**: Core instructions and workflow guidance
+
+**What belongs here**:
+- Quick start / getting started
+- Core workflow steps
+- Essential examples (minimal and representative)
+- Links to Level 3 resources
+- Common use cases
+- Key concepts
+
+**What doesn't belong here**:
+- Detailed API documentation → references/api-reference.md
+- Extensive examples → references/examples.md
+- Configuration details → references/configuration.md
+- Troubleshooting guides → references/troubleshooting.md
+- Long reference material → references/
+
+**Structure**:
+```markdown
+# Skill Name
+
+## Quick Start
+[Minimal getting started example]
+
+## Core Workflow
+[Essential steps for main use case]
+
+## Common Tasks
+[2-3 most common scenarios with brief examples]
+
+## Advanced Usage
+See [advanced-usage.md](references/advanced-usage.md)
+```
+
+**Keep it lean**:
+- ❌ Walls of text
+- ❌ Every possible parameter
+- ❌ Exhaustive examples
+- ✅ Core workflow
+- ✅ Minimal examples
+- ✅ Links to references
+
+---
+
+### Level 3: Resources (Loaded As Needed)
+
+**What**: Files in references/, scripts/, assets/
+**When**: When Claude determines they're needed
+**Token cost**: Varies (can be large)
+**Purpose**: Detailed documentation, code, assets
+
+**Proper organization**:
+
+```
+skill-name/
+├── SKILL.md (Level 2: Core instructions)
+└── references/ (Level 3: Detailed resources)
+    ├── api-reference.md (Complete API docs)
+    ├── examples.md (Comprehensive examples)
+    ├── configuration.md (All config options)
+    ├── troubleshooting.md (Common issues)
+    └── advanced-usage.md (Advanced patterns)
+```
+
+**When to create reference files**:
+- Content > 1000 words → separate file
+- Detailed specifications → separate file
+- Comprehensive examples → separate file
+- Reference tables/lists → separate file
+- Specialized workflows → separate file
+
+**How to link from SKILL.md**:
+```markdown
+For complete API documentation, see [api-reference.md](references/api-reference.md).
+For all configuration options, see [configuration.md](references/configuration.md).
+```
+
+---
+
+## Anti-Patterns
+
+### ❌ Everything in SKILL.md
+
+```markdown
+# Skill Name
+
+## Introduction
+[500 words of background...]
+
+## Complete API Reference
+[5000 words of API docs...]
+
+## Configuration
+[1000 words of config options...]
+
+## Examples
+[50 examples...]
+
+## Troubleshooting
+[30 common issues...]
+```
+
+**Problem**: Loads 10k+ tokens every time skill is triggered, even for simple tasks.
+
+**Fix**: Move sections to references/:
+- api-reference.md
+- configuration.md
+- examples.md
+- troubleshooting.md
+
+Keep only quick start and core workflow in SKILL.md.
+
+---
+
+### ❌ Duplicate Content
+
+SKILL.md:
+```markdown
+## Authentication
+Set API_KEY environment variable.
+
+## API Reference
+Full authentication documentation:
+- Set API_KEY environment variable
+- Obtain key from dashboard
+- Key format: 32 hex characters
+- Rotation: every 90 days
+```
+
+references/api-reference.md:
+```markdown
+## Authentication
+Set API_KEY environment variable.
+Obtain key from dashboard...
+[same content repeated]
+```
+
+**Problem**: Same information in multiple places. Wastes tokens and creates maintenance burden.
+
+**Fix**: Put detailed info in ONE place (references/), link from SKILL.md.
+
+SKILL.md:
+```markdown
+## Quick Start
+
+Set `API_KEY` environment variable:
+```bash
+export API_KEY="your-key-here"
+```
+
+For authentication details, see [api-reference.md](references/api-reference.md#authentication).
+```
+
+---
+
+### ❌ Unclear Load Boundaries
+
+```markdown
+# Skill Name
+
+Some stuff in SKILL.md...
+
+[Inline 2000 words of detailed configuration]
+
+...more stuff...
+
+For additional examples, see examples.md.
+```
+
+**Problem**: Heavy content inline, light content in references. Backwards from ideal.
+
+**Fix**: Keep SKILL.md lean, move heavy content to references.
+
+---
+
+## Implementation Guide
+
+### Audit Existing Skill
+
+1. **Measure SKILL.md size**:
+   ```bash
+   wc -w skill-name/SKILL.md
+   ```
+   Target: Under 1500 words (~5k tokens)
+
+2. **Identify heavy sections**:
+   - Complete API docs
+   - Exhaustive examples
+   - Configuration tables
+   - Troubleshooting guides
+
+3. **Extract to references**:
+   ```bash
+   mkdir -p skill-name/references
+   # Move heavy sections to focused files
+   ```
+
+4. **Update links**:
+   Replace inline content with links to references/
+
+### Create New Skill
+
+1. **Start with metadata**:
+   ```yaml
+   ---
+   name: skill-name
+   description: Clear description with trigger keywords
+   ---
+   ```
+
+2. **Write lean SKILL.md**:
+   - Quick start (1 example)
+   - Core workflow (essential steps)
+   - Links to references (for depth)
+
+3. **Create references as needed**:
+   - Only when content > 1000 words
+   - One focused topic per file
+   - Clear file names
+
+4. **Link properly**:
+   ```markdown
+   For [topic], see [references/topic.md](references/topic.md).
+   ```
+
+---
+
+## Verification Checklist
+
+Progressive disclosure audit:
+
+- [ ] SKILL.md under 1500 words (~5k tokens)
+- [ ] Metadata (frontmatter) is concise and comprehensive
+- [ ] SKILL.md contains only core workflow and essential examples
+- [ ] Detailed content moved to references/
+- [ ] No duplicate content between SKILL.md and references/
+- [ ] Links from SKILL.md to references/ are clear and resolve correctly
+- [ ] Reference file names indicate content
+- [ ] Each reference file has one focused purpose
+
+---
+
+## Progressive Disclosure in Practice
+
+### Example: tmux Skill
+
+**Level 1** (Metadata - Always loaded):
+```yaml
+description: Remote control tmux sessions for interactive CLIs (python, gdb, etc.)
+```
+
+**Level 2** (SKILL.md - Loaded when triggered):
+```markdown
+# tmux Skill
+
+## Quick Start
+1. Create session: `create-session.sh -n my-session --python`
+2. Send command: `safe-send.sh -s my-session -c "print('hello')"`
+3. Wait for output: `wait-for-text.sh -s my-session -p ">>>"`
+
+For session registry details, see [session-registry.md](references/session-registry.md).
+```
+
+**Level 3** (References - Loaded as needed):
+- `references/session-registry.md` (530+ lines of comprehensive registry docs)
+- Only loaded when Claude needs registry details
+
+**Result**:
+- Metadata: ~30 tokens (always)
+- Core instructions: ~1k tokens (when triggered)
+- Registry docs: ~2k tokens (only when needed for registry-specific questions)
+
+Total context impact: 30 tokens idle, 1k tokens typical use, 3k tokens for deep dives.
+
+Without progressive disclosure: 3k+ tokens always loaded.
+
+---
+
+## Summary
+
+**Three levels, three loading times**:
+1. **Metadata** (always): Name + description for discovery
+2. **Instructions** (when triggered): Core workflow in SKILL.md
+3. **Resources** (as needed): Detailed docs in references/
+
+**Key principle**: Information loads when needed, not before.
+
+**Target metrics**:
+- Metadata: ~100 tokens
+- SKILL.md: <5k tokens (preferably <3k)
+- References: No limit (loaded selectively)

references/quality-checklist.md

@@ -0,0 +1,601 @@
+# Quality Checklist - Detailed Criteria
+
+Comprehensive quality criteria for skill review with examples and guidance.
+
+## 1. Progressive Disclosure
+
+**What to check**: Information is properly layered across metadata, instructions, and resources.
+
+**Good example**:
+```yaml
+---
+name: pdf-processor
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files.
+---
+
+# PDF Processor
+
+## Quick Start
+Use pdfplumber to extract text:
+```python
+import pdfplumber
+with pdfplumber.open("doc.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+```
+
+For form filling, see [forms.md](references/forms.md).
+For advanced table extraction, see [tables.md](references/tables.md).
+```
+
+**Bad example**:
+```markdown
+# PDF Processor
+
+## Complete API Reference
+[500 lines of pdfplumber API documentation inline...]
+
+## All Possible Workflows
+[50 different use cases with full code...]
+
+## Configuration Options
+[Every configuration parameter explained...]
+```
+
+**Why it matters**: Skills should load incrementally. Metadata is always loaded (tiny), SKILL.md loads when triggered (small), references load as needed (can be large).
+
+**Review questions**:
+- Is SKILL.md under 5k tokens?
+- Are detailed references offloaded to separate files?
+- Does SKILL.md link to references instead of duplicating content?
+
+---
+
+## 2. Mental Model Shift
+
+**What to check**: Skill is described as the canonical way, not a "new" or "recommended" feature.
+
+**Good example**:
+```markdown
+# Session Registry
+
+Use the session registry for automatic session tracking. This eliminates manual socket management.
+
+## Standard Workflow
+1. Create a session: `create-session.sh -n my-session`
+2. Use the session: `safe-send.sh -s my-session -c "command"`
+```
+
+**Bad example**:
+```markdown
+# Session Registry (NEW!)
+
+The session registry is a new recommended feature that you can optionally use instead of manual socket management.
+
+## Two Approaches
+### Approach 1: Manual Socket Management (Traditional)
+[old way...]
+
+### Approach 2: Session Registry (Recommended!)
+[new way...]
+```
+
+**Why it matters**: Mental model shift means the feature becomes "the way" things are done, not an alternative. Documentation should reflect this confidence.
+
+**Red flags**:
+- "New feature" or "recommended approach"
+- Side-by-side comparisons of old vs new
+- Hedging language ("you might want to", "consider using")
+- "Traditional" or "legacy" alongside "new"
+
+**Review questions**:
+- Does the documentation present this as THE way to do the task?
+- Is old/alternative approach relegated to a "Manual Alternative" section?
+- Does language convey confidence rather than optionality?
+
+---
+
+## 3. Degree of Freedom
+
+**What to check**: Instructions match the declared autonomy level (high/medium/low).
+
+**High Freedom** (principles and heuristics):
+```markdown
+## Analyzing Code Quality
+
+Review code for:
+- Readability and maintainability
+- Performance implications
+- Security concerns
+- Test coverage
+
+Consider the project's context and constraints when making recommendations.
+```
+
+**Medium Freedom** (preferred patterns with parameters):
+```markdown
+## Creating Tests
+
+Use pytest with this structure:
+```python
+def test_feature_name():
+    # Arrange: Setup test data
+    # Act: Execute the feature
+    # Assert: Verify results
+```
+
+Adjust assertion strictness based on feature criticality.
+```
+
+**Low Freedom** (specific steps):
+```markdown
+## Deploying to Production
+
+Execute exactly in order:
+1. Run: `make test` (must pass 100%)
+2. Run: `make build`
+3. Tag release: `git tag v1.x.x`
+4. Push: `git push origin v1.x.x`
+5. Run: `./deploy.sh production`
+6. Monitor: `tail -f /var/log/app.log` for 5 minutes
+```
+
+**Why it matters**: Mismatch creates confusion. High freedom tasks shouldn't be over-specified. Low freedom tasks shouldn't be under-specified.
+
+**Review questions**:
+- Is the freedom level explicitly stated or clearly implied?
+- Do instructions match that freedom level?
+- Are fragile operations given low freedom with exact steps?
+- Are creative/contextual tasks given high freedom?
+
+---
+
+## 4. SKILL.md Conciseness
+
+**What to check**: SKILL.md is lean, actionable, and purpose-driven.
+
+**Good example** (concise):
+```markdown
+# API Client
+
+## Authentication
+Set `API_KEY` environment variable before making requests.
+
+## Making Requests
+```python
+import requests
+response = requests.get(
+    "https://api.example.com/data",
+    headers={"Authorization": f"Bearer {os.getenv('API_KEY')}"}
+)
+```
+
+For all endpoints and parameters, see [api-reference.md](references/api-reference.md).
+```
+
+**Bad example** (verbose):
+```markdown
+# API Client
+
+## Introduction
+This skill helps you interact with the Example API. The API provides various endpoints for data access and manipulation. Founded in 2020, Example Corp offers...
+
+## Why Use This Skill
+Benefits of using this skill include...
+- Consistent authentication
+- Error handling
+- Rate limiting
+[more marketing copy...]
+
+## Prerequisites
+Before you begin, make sure you have:
+1. An API key (see below for how to obtain)
+2. Python 3.7+ installed
+3. requests library (can be installed via pip)
+4. A stable internet connection
+...
+```
+
+**Why it matters**: Context window is expensive. Every word should earn its place.
+
+**Conciseness checklist**:
+- ❌ Marketing language or lengthy introductions
+- ❌ Redundant explanations of obvious concepts
+- ❌ Walls of text that could be examples
+- ✅ Direct, actionable instructions
+- ✅ Minimal but representative examples
+- ✅ Links to references for depth
+
+**Review questions**:
+- Could any section be condensed by 50% without losing clarity?
+- Are there marketing phrases or fluff?
+- Do examples replace explanations where possible?
+- Is depth offloaded to references/?
+
+---
+
+## 5. Safety & Failure Handling
+
+**What to check**: Guardrails for dangerous actions, clear failure modes, recovery steps.
+
+**Good example**:
+```markdown
+## Deploying Changes
+
+**⚠️  WARNING**: This deploys to production. Ensure tests pass before proceeding.
+
+```bash
+# Verify tests first
+make test || { echo "Tests failed - aborting"; exit 1; }
+
+# Deploy
+./deploy.sh production
+```
+
+**If deployment fails**:
+1. Check logs: `tail -f /var/log/deploy.log`
+2. Rollback: `./deploy.sh rollback`
+3. Verify: `curl https://api.example.com/health`
+
+**Rollback steps**:
+```bash
+git revert HEAD
+./deploy.sh production
+```
+```
+
+**Bad example**:
+```markdown
+## Deploying Changes
+
+Run: `./deploy.sh production`
+```
+
+**Why it matters**: Skills often perform critical or destructive operations. Users need to know what can go wrong and how to recover.
+
+**Safety elements**:
+- **Warnings** for destructive operations
+- **Validation** steps before critical actions
+- **Failure modes** documented
+- **Recovery procedures** provided
+- **Assumptions** stated explicitly
+
+**Review questions**:
+- Are dangerous operations flagged with warnings?
+- Are there validation steps before destructive actions?
+- Are failure scenarios documented?
+- Are rollback/recovery steps provided?
+
+---
+
+## 6. Resource Hygiene
+
+**What to check**: References are current, minimal, discoverable, and properly linked.
+
+**Good example**:
+```
+skill-name/
+├── SKILL.md
+└── references/
+    ├── api-reference.md (current, focused)
+    ├── examples.md (representative cases)
+    └── troubleshooting.md (common issues)
+```
+
+SKILL.md properly links:
+```markdown
+See [API Reference](references/api-reference.md) for all endpoints.
+For common issues, check [Troubleshooting](references/troubleshooting.md).
+```
+
+**Bad example**:
+```
+skill-name/
+├── SKILL.md
+└── references/
+    ├── docs.md (duplicates SKILL.md)
+    ├── api-v1.md (outdated)
+    ├── api-v2.md (current but not clear)
+    ├── examples-old.md (deprecated)
+    ├── examples-new.md (current)
+    ├── random-notes.md (unclear purpose)
+    └── README.md (redundant)
+```
+
+**Resource hygiene checklist**:
+- ✅ Each file has clear, unique purpose
+- ✅ File names indicate content
+- ✅ No duplicate information
+- ✅ Links from SKILL.md resolve
+- ✅ No outdated or deprecated content
+- ✅ Secret handling documented if applicable
+
+**Review questions**:
+- Is each reference file's purpose clear from its name?
+- Are all links from SKILL.md valid?
+- Is there duplicate content between files?
+- Are outdated resources removed?
+
+---
+
+## 7. Consistency & Clarity
+
+**What to check**: Terminology consistent, flow logical, formatting readable.
+
+**Good example**:
+```markdown
+# Database Migration Tool
+
+## Running Migrations
+
+Apply all pending migrations:
+```bash
+./migrate.sh apply
+```
+
+Rollback the last migration:
+```bash
+./migrate.sh rollback
+```
+
+## Migration Files
+
+Create new migration:
+```bash
+./migrate.sh create add_users_table
+```
+
+This creates `migrations/001_add_users_table.sql`.
+```
+
+**Bad example**:
+```markdown
+# Database Migration Tool
+
+## Executing Migrations
+
+Run migrations using the migration runner:
+```bash
+./run-migrations.sh
+```
+
+## Reverting Changes
+
+Undo schema modifications:
+```bash
+./rollback-db.sh
+```
+
+## Creating Migration Scripts
+
+Generate new migration file:
+```bash
+./new-migration.sh
+```
+```
+
+**Consistency issues** in bad example:
+- Command names inconsistent (`./migrate.sh` vs `./run-migrations.sh`)
+- Terminology varies ("migrations" vs "schema modifications")
+- Section headings use different patterns
+
+**Clarity checklist**:
+- ✅ Consistent terminology throughout
+- ✅ Logical section ordering
+- ✅ Clear, unambiguous instructions
+- ✅ Readable formatting and spacing
+- ✅ No conflicting guidance
+
+**Review questions**:
+- Is the same concept called by the same name throughout?
+- Do sections flow in logical order?
+- Are commands/tools referenced consistently?
+- Is formatting consistent?
+
+---
+
+## 8. Testing & Verification
+
+**What to check**: Quick checks, expected outputs, or smoke tests included.
+
+**Good example**:
+```markdown
+## Verification
+
+Test the installation:
+```bash
+./health-check.sh
+```
+
+**Expected output**:
+```
+✓ API connection successful
+✓ Database accessible
+✓ Cache configured
+All systems operational
+```
+
+**Quick smoke test**:
+```bash
+# Should return status 200
+curl -I https://api.example.com/health
+```
+```
+
+**Bad example**:
+```markdown
+## Usage
+
+Run the tool:
+```bash
+./tool.sh
+```
+```
+
+**Why it matters**: Users need to verify the skill works correctly and understand what success looks like.
+
+**Testing elements**:
+- **Smoke tests**: Quick checks that basic functionality works
+- **Expected outputs**: What success looks like
+- **Verification steps**: How to confirm it's working
+- **Example runs**: Representative use cases with results
+
+**Review questions**:
+- Are there quick verification steps?
+- Is expected output shown?
+- Can users confirm the skill works?
+- Are examples testable/reproducible?
+
+---
+
+## 9. Ownership & Maintenance (Optional)
+
+**What to check**: Known limitations documented. Version/maintainer metadata optional but recommended for team/public skills.
+
+**Note**: Marketplace-level changelogs (changelogs/skill-name.md) are required per marketplace standards and provide versioning at the marketplace level. The Version section within SKILL.md itself is optional.
+
+**When to include version metadata in SKILL.md**:
+- Public marketplace skills (helps users track updates)
+- Team-shared skills (clarifies who maintains it)
+- Skills with frequent breaking changes (version tracking important)
+
+**When to skip version metadata in SKILL.md**:
+- Personal skills for individual use
+- Experimental/prototype skills
+- Skills where marketplace changelogs provide sufficient tracking
+
+**Example with optional version metadata**:
+```markdown
+# API Integration Skill
+
+**Version**: 1.2.0
+**Maintainer**: DevTools Team (devtools@example.com)
+
+## Known Limitations
+
+- Rate limited to 100 requests/minute
+- Large file uploads (>10MB) not supported
+- Requires Python 3.8+
+```
+
+**Minimal example (recommended for most skills)**:
+```markdown
+# Simple Helper Skill
+
+## Known Limitations
+
+- Works only on Linux/macOS
+- Requires bash 4.0+
+```
+
+**Why it matters**: Known limitations help users understand constraints. Version metadata in SKILL.md is helpful for team coordination but optional.
+
+**Core elements**:
+- **Known Limitations** (recommended): Document constraints and requirements
+- **Version** (optional): Current version number
+- **Maintainer** (optional): Contact info for questions
+- **Changelog** (optional in SKILL.md): Can reference marketplace changelog or references/
+
+**Review questions**:
+- Are known limitations or requirements documented?
+- If version metadata is present, is it complete and current?
+- If this is a team skill, is maintainer contact info provided?
+
+---
+
+## 10. Tight Scope & Minimalism
+
+**What to check**: Focused purpose, no feature creep, no overlapping functionality.
+
+**Good example** (focused):
+```markdown
+# PDF Text Extractor
+
+Extract text content from PDF files using pdfplumber.
+
+## Supported Operations
+- Extract text from single page
+- Extract text from all pages
+- Extract text with layout preservation
+
+**Not covered** (use pdf-form-filler skill):
+- Form filling
+- PDF editing
+```
+
+**Bad example** (scope creep):
+```markdown
+# PDF Swiss Army Knife
+
+Complete PDF toolkit for all your document needs!
+
+## Features
+- Text extraction
+- Image extraction
+- Form filling
+- PDF editing
+- PDF merging
+- PDF splitting
+- Watermarking
+- OCR processing
+- Compression
+- Encryption
+- Digital signatures
+- Conversion to Word/Excel
+- Email integration
+- Cloud storage sync
+```
+
+**Why it matters**: Focused skills are easier to maintain, understand, and use. Feature creep dilutes the skill's purpose and increases complexity.
+
+**Scope checklist**:
+- ✅ Solves one focused job well
+- ✅ Clear boundaries (what's in, what's out)
+- ✅ No overlapping functionality with other skills
+- ✅ No unrelated features
+- ✅ Complexity matches the actual need
+
+**Review questions**:
+- Does the skill do one thing well?
+- Are there unrelated features that should be separate skills?
+- Does functionality overlap with existing skills?
+- Is complexity justified by the use case?
+
+---
+
+## Using This Checklist
+
+### Quick Review (5-10 minutes)
+
+Scan for obvious issues:
+1. Check SKILL.md length (should be under 5k tokens)
+2. Verify progressive disclosure (links to references/)
+3. Look for mental model language ("new feature", "recommended")
+4. Check for safety warnings on destructive operations
+5. Verify examples are present and minimal
+
+### Thorough Review (30-60 minutes)
+
+Apply all 10 criteria systematically:
+1. Read SKILL.md completely
+2. Check frontmatter quality
+3. Verify each criterion with examples
+4. Review all reference files
+5. Test examples if possible
+6. Document findings in review report
+
+### Common Review Patterns
+
+**New Skill**:
+- Focus on criteria 1, 2, 4, 10 (structure and scope)
+- Verify progressive disclosure from the start
+- Ensure mental model language is correct
+
+**Updated Skill**:
+- Focus on criteria 3, 7, 9 (consistency with changes)
+- Check that updates didn't break existing patterns
+- Verify changelog is updated
+
+**Audit**:
+- Apply all 10 criteria
+- Compare against other skills for consistency
+- Look for improvement opportunities