zhongwei/gh-dashed-claude-marketplace-plugins-skill-reviewer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:17:56 +08:00
commit 7290dfdcfb
10 changed files with 2646 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

379
references/examples.md Normal file
View File

@@ -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)
```