gh-dashed-claude-marketplace-plugins-skill-reviewer/references/examples.md

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

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

# 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

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

# 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

# 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

---
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

---
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. For examples of quality checks, see examples.md.

Requirements

Requires pandas:

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

❌ Before: "You can optionally use this skill when you need to..."
✅ After: "Use for commit message generation from git diffs."

Pattern: Scope Creep

❌ Before: "Process PDFs, Word docs, Excel files, and images"
✅ After: "Process PDF files" (separate skills for other formats)