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

11
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,11 @@
{
"name": "skill-reviewer",
"description": "Review and ensure skills maintain high quality standards. Use when creating new skills, updating existing skills, or auditing skill quality. Checks for progressive disclosure, mental model shift, appropriate scope, and documentation clarity.",
"version": "1.1.0",
"author": {
"name": "Alberto Leal"
},
"skills": [
"./"
]
}

21
LICENSE.txt Normal file
View File

@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2025 Alberto Leal
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# skill-reviewer
Review and ensure skills maintain high quality standards. Use when creating new skills, updating existing skills, or auditing skill quality. Checks for progressive disclosure, mental model shift, appropriate scope, and documentation clarity.

204
SKILL.md Normal file
View File

@@ -0,0 +1,204 @@
---
name: skill-reviewer
description: Review and ensure skills maintain high quality standards. Use when creating new skills, updating existing skills, or auditing skill quality. Checks for progressive disclosure, mental model shift, appropriate scope, and documentation clarity.
---
# Skill Reviewer
Ensure skills maintain high quality standards through systematic review.
## When to Use
Use this skill when:
- Creating a new skill (before finalization)
- Updating an existing skill (after making changes)
- Auditing skill quality across your marketplace
- Reviewing team members' skill contributions
## Quick Review Process
### 1. Load the Skill
Read the skill's SKILL.md and check the directory structure:
```bash
ls -la path/to/skill/
cat path/to/skill/SKILL.md
```
### 2. Apply the 10-Point Checklist
Review against these core quality criteria:
1. **Progressive Disclosure** - Metadata/instructions/resources properly separated
2. **Mental Model Shift** - Describes skill as canonical approach, not "new feature"
3. **Degree of Freedom** - Matches instructions to declared autonomy level
4. **SKILL.md Conciseness** - Lean, actionable, purpose-driven
5. **Safety & Failure Handling** - Guardrails and recovery steps present
6. **Resource Hygiene** - References current, minimal, discoverable
7. **Consistency** - Terminology and flow clear and unambiguous
8. **Testing Guidance** - Verification steps or examples included
9. **Ownership (Optional)** - Known limitations documented; version/maintainer optional
10. **Tight Scope** - Focused purpose, no feature creep
### 3. Document Findings
Create a review report with:
- ✅ Criteria that pass
- ⚠️ Areas needing improvement
- 🔴 Critical issues requiring fixes
- 💡 Suggestions for enhancement
## Detailed Guidance
For in-depth review criteria and examples:
- **[Quality Checklist](references/quality-checklist.md)** - Comprehensive criteria with examples
- **[Progressive Disclosure](references/progressive-disclosure.md)** - Proper structure and information layering
- **[Mental Model Shift](references/mental-model-shift.md)** - Language and positioning guidance
- **[Common Pitfalls](references/common-pitfalls.md)** - What to avoid and how to fix
- **[Review Examples](references/examples.md)** - Sample reviews demonstrating the process
## Review Workflow
### For New Skills
1. **Structure Check**
- Verify SKILL.md exists with proper frontmatter
- Check references/ directory organization
- Confirm scripts/ are executable if present
2. **Content Review**
- Frontmatter: name (lowercase, hyphens), description (clear, comprehensive)
- Body: Concise instructions with examples
- Progressive disclosure: Core in SKILL.md, details in references/
3. **Quality Assessment**
- Apply 10-point checklist
- Verify mental model language
- Check for appropriate scope and freedom level
### For Updated Skills
1. **Change Assessment**
- Identify what changed (use git diff if available)
- Verify changes align with skill's purpose
- Check for scope creep or complexity additions
2. **Documentation Update**
- Ensure SKILL.md reflects new capabilities
- Update references/ if needed
- Maintain progressive disclosure pattern
3. **Regression Check**
- Verify existing examples still work
- Check that changes didn't break mental model
- Confirm scope remains focused
## Review Report Template
```markdown
# Skill Review: [skill-name]
**Date**: YYYY-MM-DD
**Reviewer**: [name]
**Type**: [New|Update|Audit]
## Summary
Brief overview of the skill and review findings.
## Checklist Results
✅ Progressive Disclosure
✅ Mental Model Shift
⚠️ Degree of Freedom - Instructions too prescriptive for declared high freedom
✅ SKILL.md Conciseness
🔴 Safety & Failure Handling - Missing error recovery steps
✅ Resource Hygiene
✅ Consistency
⚠️ Testing Guidance - Examples present but no verification steps
✅ Ownership
✅ Tight Scope
## Critical Issues
1. **Missing Failure Handling**: Add error recovery steps for [specific scenario]
## Improvements Needed
1. **Degree of Freedom Mismatch**: Reduce prescriptiveness in steps 3-5 to match high freedom declaration
2. **Testing**: Add quick verification example showing expected output
## Suggestions
- Consider moving detailed API reference to references/api-docs.md
- Example in section 4 could be more concise
## Conclusion
[Overall assessment and recommendation: Approve|Needs Revision|Reject]
```
## Best Practices
### Keep SKILL.md Lean
Move detailed content to references/:
- API documentation → `references/api-docs.md`
- Complex workflows → `references/workflows.md`
- Extensive examples → `references/examples.md`
- Configuration details → `references/configuration.md`
### Verify Progressive Disclosure
Check that information loads in stages:
1. **Metadata** (always): name + description only
2. **Instructions** (when triggered): SKILL.md body
3. **Resources** (as needed): references/ files
### Assess Mental Model
Language should reflect "this is the way":
- ❌ "New recommended approach"
- ❌ "Optional feature"
- ✅ "Use [tool] for [task]"
- ✅ "Standard workflow"
### Match Freedom to Instructions
- **High freedom**: Provide principles, let Claude decide specifics
- **Medium freedom**: Offer preferred patterns with parameters
- **Low freedom**: Specify exact steps for fragile operations
## Examples
For complete review examples with before/after comparisons:
- **[Review Examples](references/examples.md)** - Sample reviews of simple and complex skills
For detailed examples of each quality criterion:
- **[Quality Checklist](references/quality-checklist.md)** - Examples for each of the 10 criteria
## Quick Verification
After completing a review, verify the process worked correctly:
**Checklist**:
- [ ] All reference links in SKILL.md resolve correctly
- [ ] Review report follows the template format
- [ ] Critical issues (🔴) are clearly identified
- [ ] At least one improvement or suggestion provided
- [ ] Checklist results show ✅⚠️🔴 indicators
**Smoke test**: Review a simple skill (e.g., a single-file skill with <500 words) and verify you can:
1. Load the skill and identify its structure
2. Apply all 10 checklist criteria
3. Generate a complete review report
4. Identify at least one area for improvement
**Expected outcome**: A review report that provides actionable feedback and follows the template structure.
## Version
**Version**: 1.1.0
**Last Updated**: 2025-11-23
**Maintainer**: Alberto Leal (mail4alberto@gmail.com)
**Changelog**: See [changelogs/skill-reviewer.md](../../changelogs/skill-reviewer.md)

69
plugin.lock.json Normal file
View File

@@ -0,0 +1,69 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:dashed/claude-marketplace:plugins/skill-reviewer",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "7bf09b72a425bd330a5bc209a91b7ac49aa13542",
"treeHash": "a5659a043a901b9b4fea6f45af38e9e70425e31db5c3c182b6955ddff8876cfe",
"generatedAt": "2025-11-28T10:16:03.799888Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "skill-reviewer",
"description": "Review and ensure skills maintain high quality standards. Use when creating new skills, updating existing skills, or auditing skill quality. Checks for progressive disclosure, mental model shift, appropriate scope, and documentation clarity.",
"version": "1.1.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "e884276044f89ac9eec4b65eea3545940cd1fdeea602f8ff4002fe63b8bc1bbc"
},
{
"path": "SKILL.md",
"sha256": "32440daf6bbbf07083ad5f3e6d49cb8040ddbbdc0347a7e1244084e6856cc67d"
},
{
"path": "LICENSE.txt",
"sha256": "d6c7740af2fa2fbedf0157c872a1989bf21a0f5bc6f659f7178160fe581b9b57"
},
{
"path": "references/examples.md",
"sha256": "0e10fda7a3595c6d06151758d4ddc69684ed00a8d02b8db6813602b7970c79fa"
},
{
"path": "references/common-pitfalls.md",
"sha256": "5fe4906a20025d2c12623da98947e02949b49c6a29ad2ecef0ef08cbc69dd406"
},
{
"path": "references/quality-checklist.md",
"sha256": "11d43a9a39eef26748a1e627b885a1f22a4d675eda4f97c2a7d64c1966ede320"
},
{
"path": "references/progressive-disclosure.md",
"sha256": "8357466f1e674a0cc6e8a8067894f17bc0c87a503f2151616210b18f3a3e4a9d"
},
{
"path": "references/mental-model-shift.md",
"sha256": "12e361ce2b85edc2d7fbdcd9c1f07659e1ba67294e5138cf3c89d87e6f74662f"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "1acaed51fada8cf93def4d6549812322cecdfa2450597cd033bcd6db796a5334"
}
],
"dirSha256": "a5659a043a901b9b4fea6f45af38e9e70425e31db5c3c182b6955ddff8876cfe"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

633
references/common-pitfalls.md Normal file
View File

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

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

389
references/mental-model-shift.md Normal file
View File

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

336
references/progressive-disclosure.md Normal file
View File

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

601
references/quality-checklist.md Normal file
View File

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