backup materials and knowledge-base docs
This commit is contained in:
admin
@@ -0,0 +1,425 @@
|
||||
---
|
||||
name: skill-quality-reviewer
|
||||
description: This skill should be used when the user asks to "analyze skill quality", "evaluate this skill", "review skill quality", "check my skill", or "generate quality report". Evaluates local skills across description quality, content organization, writing style, and structural integrity.
|
||||
version: 0.1.0
|
||||
---
|
||||
|
||||
# Skill Quality Reviewer
|
||||
|
||||
## Overview
|
||||
|
||||
A meta-skill for evaluating the quality of Claude Skills. Perform comprehensive analysis across four key dimensions—description quality (25%), content organization (30%), writing style (20%), and structural integrity (25%)—to generate weighted scores, letter grades, and actionable improvement plans.
|
||||
|
||||
Use this skill to validate skills before sharing, identify improvement opportunities, or ensure compliance with skill development best practices.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
**Invoke this skill when:**
|
||||
- Analyzing a skill's quality before distribution
|
||||
- Reviewing skill documentation for best practices
|
||||
- Evaluating adherence to skill development standards
|
||||
- Generating improvement recommendations for existing skills
|
||||
- Validating skill structure and completeness
|
||||
|
||||
**Trigger phrases:**
|
||||
- "Analyze skill quality for ./my-skill"
|
||||
- "Evaluate this skill: ~/.claude/skills/api-helper"
|
||||
- "Review skill quality of git-workflow"
|
||||
- "Check my skill for best practices"
|
||||
- "Generate quality report for this skill"
|
||||
|
||||
## Review Modes
|
||||
|
||||
Use one of three review modes depending on the task:
|
||||
|
||||
1. **score-only**
|
||||
- fast first-pass grading for one skill.
|
||||
2. **remediation-backlog**
|
||||
- convert findings into P0 / P1 / P2 fix queues with concrete evidence.
|
||||
3. **batch-portfolio**
|
||||
- review multiple skills together, cluster repeated issues, and produce a prioritized shortlist.
|
||||
|
||||
Prefer `remediation-backlog` when the user asks what to fix next.
|
||||
Prefer `batch-portfolio` when auditing many skills at once.
|
||||
|
||||
## Analysis Workflow
|
||||
|
||||
### Step 1: Load the Skill
|
||||
|
||||
Accept skill path as input. Verify the path exists and contains `SKILL.md`. Read the complete skill directory structure.
|
||||
|
||||
```bash
|
||||
# Example invocation
|
||||
ls -la ~/.claude/skills/target-skill/
|
||||
```
|
||||
|
||||
**Validate:**
|
||||
- SKILL.md exists
|
||||
- Directory is readable
|
||||
- Path points to a valid skill
|
||||
|
||||
### Step 2: Parse YAML Frontmatter
|
||||
|
||||
Extract and validate the YAML frontmatter from SKILL.md.
|
||||
|
||||
**Required fields:**
|
||||
- `name` - Skill identifier
|
||||
- `description` - Trigger description with phrases
|
||||
|
||||
**Check for:**
|
||||
- Valid YAML syntax
|
||||
- No prohibited fields
|
||||
- Proper formatting
|
||||
|
||||
### Step 3: Evaluate Description Quality (25%)
|
||||
|
||||
Assess the quality and effectiveness of the frontmatter description.
|
||||
|
||||
**Scoring breakdown:**
|
||||
|
||||
| Criterion | Points | Evaluation |
|
||||
|-----------|--------|------------|
|
||||
| Trigger phrases clarity | 25 | 3-5 specific user phrases present |
|
||||
| Third-person format | 25 | Uses "This skill should be used when..." |
|
||||
| Description length | 25 | 100-300 characters optimal |
|
||||
| Specific scenarios | 25 | Concrete use cases, not vague |
|
||||
|
||||
**Red flags:**
|
||||
- Vague triggers like "helps with tasks"
|
||||
- Second-person descriptions ("Use this when you...")
|
||||
- Missing or generic descriptions
|
||||
- No actionable trigger phrases
|
||||
|
||||
**Reference:** `references/examples-good.md` for exemplary descriptions
|
||||
|
||||
### Step 4: Evaluate Content Organization (30%)
|
||||
|
||||
Assess adherence to progressive disclosure principles.
|
||||
|
||||
**Scoring breakdown:**
|
||||
|
||||
| Criterion | Points | Evaluation |
|
||||
|-----------|--------|------------|
|
||||
| Progressive disclosure | 30 | SKILL.md lean, details in references/ |
|
||||
| SKILL.md length | 25 | Under 5,000 words (1,500-2,000 ideal) |
|
||||
| References/ usage | 25 | Detailed content properly moved |
|
||||
| Logical organization | 20 | Clear sections, good flow |
|
||||
|
||||
**Check:**
|
||||
- SKILL.md body is concise and focused
|
||||
- Detailed content moved to `references/`
|
||||
- Examples and templates in appropriate directories
|
||||
- No information duplication across files
|
||||
|
||||
**Reference:** `references/scoring-criteria.md` for detailed rubrics
|
||||
|
||||
### Step 5: Evaluate Writing Style (20%)
|
||||
|
||||
Verify adherence to skill writing conventions.
|
||||
|
||||
**Scoring breakdown:**
|
||||
|
||||
| Criterion | Points | Evaluation |
|
||||
|-----------|--------|------------|
|
||||
| Imperative form | 40 | Verb-first instructions throughout |
|
||||
| No second person in body | 30 | Avoids conversational second person in the main workflow body |
|
||||
| Objective language | 30 | Factual, instructional tone |
|
||||
|
||||
**Check for:**
|
||||
- Imperative verbs: "Create the file", "Validate input", "Check structure"
|
||||
- Absence of: "You should", "You can", "You need to"
|
||||
- Objective, instructional language
|
||||
- Consistent style throughout
|
||||
|
||||
**Good examples:**
|
||||
```
|
||||
Create the skill directory structure.
|
||||
Validate the YAML frontmatter.
|
||||
Check for required fields.
|
||||
```
|
||||
|
||||
**Bad examples:**
|
||||
```
|
||||
You should create the directory.
|
||||
You need to validate the frontmatter.
|
||||
Check if the fields are there.
|
||||
```
|
||||
|
||||
### Step 6: Evaluate Structural Integrity (25%)
|
||||
|
||||
Verify the skill's physical structure and completeness.
|
||||
|
||||
**Scoring breakdown:**
|
||||
|
||||
| Criterion | Points | Evaluation |
|
||||
|-----------|--------|------------|
|
||||
| YAML frontmatter | 30 | All required fields present |
|
||||
| Directory structure | 30 | Proper organization |
|
||||
| Resource references | 40 | All referenced files exist |
|
||||
|
||||
**Validate:**
|
||||
- YAML frontmatter contains `name` and `description`
|
||||
- Directory structure follows conventions:
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md
|
||||
├── references/ (optional)
|
||||
├── examples/ (optional)
|
||||
└── scripts/ (optional)
|
||||
```
|
||||
- All files referenced in SKILL.md actually exist
|
||||
- Examples are complete and working
|
||||
- Scripts are executable
|
||||
|
||||
### Step 7: Calculate Weighted Score
|
||||
|
||||
Compute the overall quality score using weighted dimensions.
|
||||
|
||||
**Formula:**
|
||||
```
|
||||
Overall Score = (Description × 0.25) + (Organization × 0.30) +
|
||||
(Style × 0.20) + (Structure × 0.25)
|
||||
```
|
||||
|
||||
**Letter grade mapping:**
|
||||
|
||||
| Score Range | Grade | Meaning |
|
||||
|-------------|-------|---------|
|
||||
| 97-100 | A+ | Exemplary |
|
||||
| 93-96 | A | Excellent |
|
||||
| 90-92 | A- | Very Good |
|
||||
| 87-89 | B+ | Good |
|
||||
| 83-86 | B | Above Average |
|
||||
| 80-82 | B- | Solid |
|
||||
| 77-79 | C+ | Acceptable |
|
||||
| 73-76 | C | Satisfactory |
|
||||
| 70-72 | C- | Minimal Acceptable |
|
||||
| 67-69 | D+ | Below Standard |
|
||||
| 63-66 | D | Poor |
|
||||
| 60-62 | D- | Very Poor |
|
||||
| 0-59 | F | Fail |
|
||||
|
||||
### Step 8: Generate Reports
|
||||
|
||||
Create two output documents in the current working directory.
|
||||
|
||||
**1. Quality Report** (`quality-report-{skill-name}.md`)
|
||||
- Executive summary with overall score and grade
|
||||
- Dimension-by-dimension breakdown
|
||||
- Strengths and weaknesses for each dimension
|
||||
- Grade breakdown table
|
||||
- Link to improvement plan
|
||||
|
||||
**2. Improvement Plan** (`improvement-plan-{skill-name}.md`)
|
||||
- Prioritized improvement list (High/Medium/Low)
|
||||
- Specific file locations and line numbers for issues
|
||||
- Current vs. suggested content comparisons
|
||||
- Estimated impact on scores
|
||||
- Time estimates for fixes
|
||||
- Expected score improvement
|
||||
|
||||
## Output Templates
|
||||
|
||||
### Quality Report Template
|
||||
|
||||
```markdown
|
||||
# Skill Quality Report: {skill-name}
|
||||
|
||||
## Executive Summary
|
||||
- **Overall Score**: X/100 ({Grade})
|
||||
- **Evaluated**: {Date}
|
||||
- **Skill Path**: {path}
|
||||
|
||||
## Dimension Scores
|
||||
|
||||
### 1. Description Quality (25%)
|
||||
**Score**: X/100
|
||||
|
||||
**Strengths**:
|
||||
- ✅ {specific strength}
|
||||
|
||||
**Weaknesses**:
|
||||
- ❌ {specific weakness}
|
||||
|
||||
**Recommendations**:
|
||||
1. {actionable recommendation}
|
||||
|
||||
[Repeat for other dimensions...]
|
||||
|
||||
## Grade Breakdown
|
||||
| Dimension | Score | Weight | Contribution |
|
||||
|-----------|-------|--------|--------------|
|
||||
| Description | X/100 | 25% | X.X |
|
||||
| Organization | X/100 | 30% | X.X |
|
||||
| Style | X/100 | 20% | X.X |
|
||||
| Structure | X/100 | 25% | X.X |
|
||||
| **Overall** | **X/100** | **100%** | **X.X ({Grade})** |
|
||||
|
||||
## Next Steps
|
||||
See `improvement-plan-{skill-name}.md` for detailed improvement suggestions.
|
||||
```
|
||||
|
||||
### Improvement Plan Template
|
||||
|
||||
```markdown
|
||||
# Skill Improvement Plan: {skill-name}
|
||||
|
||||
## Priority Summary
|
||||
- **High Priority**: {count} items
|
||||
- **Medium Priority**: {count} items
|
||||
- **Low Priority**: {count} items
|
||||
|
||||
## High Priority Improvements
|
||||
|
||||
### 1. [Issue Title]
|
||||
**File**: SKILL.md:line:line
|
||||
**Dimension**: Description Quality
|
||||
**Impact**: +X points
|
||||
|
||||
**Current**:
|
||||
```yaml
|
||||
{current content}
|
||||
```
|
||||
|
||||
**Suggested**:
|
||||
```yaml
|
||||
{suggested content}
|
||||
```
|
||||
|
||||
**Reason**: {why this improves quality}
|
||||
|
||||
[Continue with all issues...]
|
||||
|
||||
## Quick Wins (Easy Fixes)
|
||||
1. {quick fix}
|
||||
2. {quick fix}
|
||||
|
||||
## Estimated Time to Complete
|
||||
- High Priority: X hours
|
||||
- Medium Priority: X hours
|
||||
- Low Priority: X hours
|
||||
- **Total**: X hours
|
||||
|
||||
## Expected Score Improvement
|
||||
- Current: X/100 ({Grade})
|
||||
- After High Priority: X/100 ({Grade})
|
||||
- After All: X/100 ({Grade})
|
||||
```
|
||||
|
||||
## Additional Resources
|
||||
|
||||
### Reference Files
|
||||
|
||||
For detailed evaluation criteria and examples, consult:
|
||||
|
||||
- **`references/scoring-criteria.md`** - Comprehensive scoring rubrics for each dimension
|
||||
- **`references/examples-good.md`** - Exemplary skills demonstrating best practices
|
||||
- **`references/examples-bad.md`** - Common anti-patterns to avoid
|
||||
|
||||
### Scripts
|
||||
|
||||
- **`scripts/extract-yaml.sh`** - Utility for extracting YAML frontmatter from SKILL.md
|
||||
- **`scripts/skill-audit.py`** - Lightweight integrity audit for missing references, word count, and sibling-path checks
|
||||
|
||||
### Related Skills
|
||||
|
||||
- **`skill-development`** - Comprehensive guide for creating skills
|
||||
- **`code-review-excellence`** - Best practices for code review
|
||||
|
||||
## Best Practices
|
||||
|
||||
### When Analyzing Skills
|
||||
|
||||
1. **Be objective and specific** - Base scores on observable criteria, not opinions
|
||||
2. **Provide actionable feedback** - Each recommendation should be concrete and implementable
|
||||
3. **Include examples** - Show current vs. suggested content for clarity
|
||||
4. **Estimate impact** - Help users understand which changes matter most
|
||||
5. **Be constructive** - Frame feedback as opportunities for improvement
|
||||
|
||||
### Common Quality Issues
|
||||
|
||||
**Description Quality:**
|
||||
- Vague or generic trigger phrases
|
||||
- Second-person descriptions
|
||||
- Missing concrete use cases
|
||||
|
||||
**Content Organization:**
|
||||
- SKILL.md too long (>5,000 words)
|
||||
- Detailed content not moved to references/
|
||||
- Poor information hierarchy
|
||||
|
||||
**Writing Style:**
|
||||
- Second-person language ("you", "your")
|
||||
- Mixed imperative and descriptive styles
|
||||
- Subjective or conversational tone
|
||||
|
||||
**Structural Integrity:**
|
||||
- Missing required YAML fields
|
||||
- Referenced files don't exist
|
||||
- Incomplete examples or broken scripts
|
||||
|
||||
### Grade Benchmarks
|
||||
|
||||
**A grade (90-100)**: Exemplary skills serving as templates for others
|
||||
- All dimensions score 85+
|
||||
- Clear, specific descriptions
|
||||
- Excellent progressive disclosure
|
||||
- Consistent imperative style
|
||||
- Complete, well-organized structure
|
||||
|
||||
**B grade (80-89)**: High-quality skills with minor improvements needed
|
||||
- Most dimensions score 75+
|
||||
- Good descriptions and organization
|
||||
- Generally follows best practices
|
||||
- May have minor style inconsistencies
|
||||
|
||||
**C grade (70-79)**: Acceptable skills requiring moderate improvements
|
||||
- Key areas meet minimum standards
|
||||
- Some weaknesses in organization or style
|
||||
- Functional but not exemplary
|
||||
|
||||
**D/F grade (below 70)**: Skills needing significant work
|
||||
- Multiple dimensions below 70
|
||||
- Major structural or style issues
|
||||
- Requires comprehensive revision
|
||||
|
||||
## Usage Examples
|
||||
|
||||
**Example 1: Analyze a local skill**
|
||||
```
|
||||
User: "Analyze skill quality for ~/.claude/skills/git-workflow"
|
||||
|
||||
[Claude executes the 8-step workflow and generates:]
|
||||
- quality-report-git-workflow.md
|
||||
- improvement-plan-git-workflow.md
|
||||
```
|
||||
|
||||
**Example 2: Review before sharing**
|
||||
```
|
||||
User: "Review my new skill before I publish it"
|
||||
|
||||
[Claude analyzes the skill and provides:]
|
||||
- Detailed quality assessment
|
||||
- Specific improvement recommendations
|
||||
- Expected score after implementing fixes
|
||||
```
|
||||
|
||||
**Example 3: Quality check for existing skill**
|
||||
```
|
||||
User: "Check skill quality of api-helper"
|
||||
|
||||
[Claude evaluates and reports:]
|
||||
- Current grade and score
|
||||
- Top improvement opportunities
|
||||
- Quick wins for easy score gains
|
||||
```
|
||||
|
||||
**Example 4: Batch portfolio review**
|
||||
```
|
||||
User: "Review all skills in ~/.claude/skills and tell me what to fix first"
|
||||
|
||||
[Claude evaluates and reports:]
|
||||
- portfolio matrix
|
||||
- grouped issue clusters
|
||||
- shortlist for second-pass remediation
|
||||
```
|
||||
@@ -0,0 +1,14 @@
|
||||
# Batch Review Template
|
||||
|
||||
## Portfolio Summary
|
||||
- Skills reviewed:
|
||||
- Highest-risk skills:
|
||||
- Common issue clusters:
|
||||
|
||||
## Priority Backlog
|
||||
### P0
|
||||
-
|
||||
### P1
|
||||
-
|
||||
### P2
|
||||
-
|
||||
@@ -0,0 +1,555 @@
|
||||
# Common Skill Anti-Patterns
|
||||
|
||||
Collection of common mistakes and anti-patterns to avoid when creating Claude Skills. Learn from these examples to improve your skills.
|
||||
|
||||
## Anti-Pattern 1: Vague Description (F Grade)
|
||||
|
||||
### The Problem
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: helper-skill
|
||||
description: Use this skill to help with various tasks and provide useful
|
||||
assistance for users.
|
||||
version: 1.0.0
|
||||
---
|
||||
```
|
||||
|
||||
**Why this fails:**
|
||||
- ❌ No specific trigger phrases
|
||||
- ❌ Second person ("Use this skill")
|
||||
- ❌ Vague and generic
|
||||
- ❌ No clue what it actually does
|
||||
- ❌ Users will never discover it
|
||||
|
||||
### Score Impact
|
||||
|
||||
| Dimension | Score | Why |
|
||||
|-----------|-------|-----|
|
||||
| Description Quality | 0/100 | No triggers, second person, vague |
|
||||
| Overall | F | Cannot even get started |
|
||||
|
||||
### The Fix
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: api-contract-manager
|
||||
description: This skill should be used when the user asks to "validate API
|
||||
contract", "check API compatibility", "version API schema", or "detect
|
||||
breaking changes". Manages API contracts through validation, versioning,
|
||||
and compatibility checking for OpenAPI 3.0 specifications.
|
||||
version: 1.0.0
|
||||
---
|
||||
```
|
||||
|
||||
**Improvement:** 0/100 → 90/100 in description quality
|
||||
|
||||
---
|
||||
|
||||
## Anti-Pattern 2: Second Person Throughout (D Grade)
|
||||
|
||||
### The Problem
|
||||
|
||||
```markdown
|
||||
# My Skill
|
||||
|
||||
## Overview
|
||||
You should use this skill when you need to process data files.
|
||||
|
||||
## How to Use
|
||||
First, you need to select your input file. You can choose from CSV,
|
||||
JSON, or XML formats. Then you should configure the processing options.
|
||||
|
||||
## Configuration
|
||||
You can set the following options:
|
||||
- You must specify the output format
|
||||
- You should choose a delimiter
|
||||
- You need to define the schema
|
||||
```
|
||||
|
||||
**Why this fails:**
|
||||
- ❌ "You should", "you need", "you can" throughout
|
||||
- ❌ Not imperative form
|
||||
- ❌ Conversational rather than instructional
|
||||
- ❌ Unprofessional tone
|
||||
|
||||
### Score Impact
|
||||
|
||||
| Dimension | Score | Why |
|
||||
|-----------|-------|-----|
|
||||
| Writing Style | 5/100 | Over 20 instances of "you" |
|
||||
| Overall | D | Major style issue |
|
||||
|
||||
### The Fix
|
||||
|
||||
```markdown
|
||||
# Data File Processor
|
||||
|
||||
## Overview
|
||||
Process data files in CSV, JSON, or XML formats with configurable
|
||||
schemas and output options.
|
||||
|
||||
## Usage
|
||||
Select the input file. Configure processing options. Specify output
|
||||
format and delimiter.
|
||||
|
||||
## Configuration
|
||||
Set the following options:
|
||||
- Output format (required)
|
||||
- Field delimiter
|
||||
- Data schema
|
||||
```
|
||||
|
||||
**Improvement:** 5/100 → 85/100 in writing style
|
||||
|
||||
---
|
||||
|
||||
## Anti-Pattern 3: Everything in One File (C Grade)
|
||||
|
||||
### The Problem
|
||||
|
||||
```
|
||||
my-skill/
|
||||
└── SKILL.md (12,000 words)
|
||||
```
|
||||
|
||||
**SKILL.md contains:**
|
||||
- Overview
|
||||
- Detailed API documentation (3,000 words)
|
||||
- 20 complete code examples (5,000 words)
|
||||
- Troubleshooting guide (2,000 words)
|
||||
- FAQ (1,000 words)
|
||||
- Changelog (1,000 words)
|
||||
|
||||
**Why this is problematic:**
|
||||
- ❌ SKILL.md is 12,000 words (should be <5,000)
|
||||
- ❌ Detailed content always loaded
|
||||
- ❌ Wastes tokens on rarely-used content
|
||||
- ❌ Difficult to navigate
|
||||
- ❌ Violates progressive disclosure
|
||||
|
||||
### Score Impact
|
||||
|
||||
| Dimension | Score | Why |
|
||||
|-----------|-------|-----|
|
||||
| Content Organization | 10/100 | No progressive disclosure |
|
||||
| Overall | C | Major organizational issue |
|
||||
|
||||
### The Fix
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md (1,800 words)
|
||||
├── references/
|
||||
│ ├── api-reference.md (3,000 words)
|
||||
│ ├── troubleshooting.md (2,000 words)
|
||||
│ └── faq.md (1,000 words)
|
||||
└── examples/
|
||||
├── basic-usage.md (1,000 words)
|
||||
├── advanced-usage.md (2,000 words)
|
||||
└── edge-cases.md (2,000 words)
|
||||
```
|
||||
|
||||
**SKILL.md now contains:**
|
||||
- Overview
|
||||
- Quick start
|
||||
- Basic operations
|
||||
- Links to detailed references
|
||||
|
||||
**Improvement:** 10/100 → 85/100 in content organization
|
||||
|
||||
---
|
||||
|
||||
## Anti-Pattern 4: Missing Required Fields (F Grade)
|
||||
|
||||
### The Problem
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: my-skill
|
||||
# Missing description!
|
||||
version: 1.0.0
|
||||
author: Someone
|
||||
tags: [utility, helper]
|
||||
---
|
||||
```
|
||||
|
||||
**Why this fails:**
|
||||
- ❌ Missing required `description` field
|
||||
- ❌ Skill will never trigger
|
||||
- ❌ Has unnecessary fields (author, tags)
|
||||
- ❌ Cannot be discovered
|
||||
|
||||
### Score Impact
|
||||
|
||||
| Dimension | Score | Why |
|
||||
|-----------|-------|-----|
|
||||
| Structural Integrity | 0/100 | Missing required field |
|
||||
| Description Quality | 0/100 | No description to evaluate |
|
||||
| Overall | F | Fundamentally broken |
|
||||
|
||||
### The Fix
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: data-validator
|
||||
description: This skill should be used when the user asks to "validate data",
|
||||
"check data format", "verify data schema", or "sanitize input". Validate and
|
||||
sanitize data files against JSON schemas with support for custom validation
|
||||
rules.
|
||||
version: 1.0.0
|
||||
---
|
||||
```
|
||||
|
||||
**Improvement:** F → B- (80) overall
|
||||
|
||||
---
|
||||
|
||||
## Anti-Pattern 5: Broken References (D Grade)
|
||||
|
||||
### The Problem
|
||||
|
||||
**SKILL.md says:**
|
||||
```markdown
|
||||
## Additional Resources
|
||||
|
||||
See `references/api-guide.md` for complete API documentation.
|
||||
Check `examples/complete-example.py` for a working example.
|
||||
```
|
||||
|
||||
**Actual directory structure:**
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md
|
||||
├── references/
|
||||
│ └── setup-guide.md # No api-guide.md!
|
||||
└── examples/
|
||||
└── basic-example.py # No complete-example.py!
|
||||
```
|
||||
|
||||
**Why this fails:**
|
||||
- ❌ Referenced files don't exist
|
||||
- ❌ Users get errors when trying to follow references
|
||||
- ❌ Incomplete skill structure
|
||||
|
||||
### Score Impact
|
||||
|
||||
| Dimension | Score | Why |
|
||||
|-----------|-------|-----|
|
||||
| Structural Integrity | 15/100 | Multiple broken references |
|
||||
| Overall | D | Structural issues |
|
||||
|
||||
### The Fix
|
||||
|
||||
Option 1: Create the referenced files
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md
|
||||
├── references/
|
||||
│ ├── api-guide.md # Created!
|
||||
│ └── setup-guide.md
|
||||
└── examples/
|
||||
├── complete-example.py # Created!
|
||||
└── basic-example.py
|
||||
```
|
||||
|
||||
Option 2: Update SKILL.md to match actual files
|
||||
```markdown
|
||||
## Additional Resources
|
||||
|
||||
See `references/setup-guide.md` for setup instructions.
|
||||
Check `examples/basic-example.py` for a working example.
|
||||
```
|
||||
|
||||
**Improvement:** 15/100 → 90/100 in structural integrity
|
||||
|
||||
---
|
||||
|
||||
## Anti-Pattern 6: Inconsistent Style (C Grade)
|
||||
|
||||
### The Problem
|
||||
|
||||
```markdown
|
||||
## Workflow
|
||||
|
||||
### Step 1: Prepare
|
||||
First you should create the directory structure.
|
||||
|
||||
### Step 2: Configure
|
||||
Configure the settings file. You need to specify the endpoint.
|
||||
|
||||
### Step 3: Deploy
|
||||
Deploy the application. Check the logs to verify.
|
||||
```
|
||||
|
||||
**Why this fails:**
|
||||
- ❌ Mixes imperative ("Configure", "Deploy") with second person ("you should")
|
||||
- ❌ Inconsistent throughout
|
||||
- ❌ Confusing to read
|
||||
|
||||
### Score Impact
|
||||
|
||||
| Dimension | Score | Why |
|
||||
|-----------|-------|-----|
|
||||
| Writing Style | 30/100 | Inconsistent style |
|
||||
| Overall | C | Style issues |
|
||||
|
||||
### The Fix
|
||||
|
||||
```markdown
|
||||
## Workflow
|
||||
|
||||
### Step 1: Prepare
|
||||
Create the directory structure.
|
||||
|
||||
### Step 2: Configure
|
||||
Specify the endpoint in the settings file.
|
||||
|
||||
### Step 3: Deploy
|
||||
Deploy the application. Verify by checking the logs.
|
||||
```
|
||||
|
||||
**Improvement:** 30/100 → 85/100 in writing style
|
||||
|
||||
---
|
||||
|
||||
## Anti-Pattern 7: Overly Long Description (B Grade)
|
||||
|
||||
### The Problem
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: file-processor
|
||||
description: This skill should be used when the user asks to "process files",
|
||||
"convert file formats", "validate file structure", "check file integrity",
|
||||
"transform file data", "merge multiple files", "split large files", "compress
|
||||
file size", "encrypt file contents", "decrypt file contents", "archive files",
|
||||
"extract archives", "generate file checksums", "verify file signatures", or
|
||||
"optimize file storage". This comprehensive file processing utility supports
|
||||
over 50 different file formats including PDF, DOCX, XLSX, CSV, JSON, XML,
|
||||
HTML, TXT, and many more. It provides advanced features like batch processing,
|
||||
parallel execution, error recovery, automatic backup creation, detailed logging,
|
||||
progress tracking, and notification support. Ideal for data migration tasks,
|
||||
content management workflows, archival operations, and file system maintenance.
|
||||
version: 1.0.0
|
||||
---
|
||||
```
|
||||
|
||||
**Why this is problematic:**
|
||||
- ❌ 900+ characters (way too long)
|
||||
- ❌ Lists too many trigger phrases (dilutes effectiveness)
|
||||
- ❌ Becomes unreadable
|
||||
- ❌ Loses focus
|
||||
|
||||
### Score Impact
|
||||
|
||||
| Dimension | Score | Why |
|
||||
|-----------|-------|-----|
|
||||
| Description Quality | 15/100 | Too long, unfocused |
|
||||
| Overall | B | Description issue |
|
||||
|
||||
### The Fix
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: file-processor
|
||||
description: This skill should be used when the user asks to "process files",
|
||||
"convert file formats", "validate file structure", "merge files", or
|
||||
"compress files". Supports common formats (PDF, DOCX, CSV, JSON) with
|
||||
batch processing and error recovery.
|
||||
version: 1.0.0
|
||||
---
|
||||
```
|
||||
|
||||
**Improvement:** 15/100 → 85/100 in description quality
|
||||
|
||||
---
|
||||
|
||||
## Anti-Pattern 8: No Examples (C Grade)
|
||||
|
||||
### The Problem
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md (2,000 words of theory)
|
||||
└── references/
|
||||
└── detailed-guide.md (3,000 words more theory)
|
||||
```
|
||||
|
||||
**SKILL.md describes concepts but never shows:**
|
||||
- How to actually use the skill
|
||||
- What input looks like
|
||||
- What output looks like
|
||||
- Concrete usage patterns
|
||||
|
||||
**Why this fails:**
|
||||
- ❌ Users can't visualize usage
|
||||
- ❌ No working code to copy
|
||||
- ❌ Theory without practice
|
||||
|
||||
### Score Impact
|
||||
|
||||
| Dimension | Score | Why |
|
||||
|-----------|-------|-----|
|
||||
| Structural Integrity | 50/100 | No examples despite theory |
|
||||
| Overall | C | Missing practical component |
|
||||
|
||||
### The Fix
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md (2,000 words)
|
||||
├── references/
|
||||
│ └── detailed-guide.md
|
||||
└── examples/
|
||||
├── basic-usage.sh (working example)
|
||||
├── advanced-usage.sh (working example)
|
||||
└── input-output-examples.md (before/after)
|
||||
```
|
||||
|
||||
**Improvement:** 50/100 → 85/100 in structural integrity
|
||||
|
||||
---
|
||||
|
||||
## Anti-Pattern 9: Subjective Language (D Grade)
|
||||
|
||||
### The Problem
|
||||
|
||||
```markdown
|
||||
## Overview
|
||||
|
||||
This is a really great skill that I think you'll find super useful.
|
||||
It's awesome for handling difficult tasks. The best part is how
|
||||
easy it is to use - you'll love it!
|
||||
|
||||
## Features
|
||||
|
||||
- Amazing performance
|
||||
- Incredible flexibility
|
||||
- Fantastic user experience
|
||||
```
|
||||
|
||||
**Why this fails:**
|
||||
- ❌ Highly subjective ("really great", "super useful")
|
||||
- ❌ Marketing language, not instructional
|
||||
- ❌ First person ("I think")
|
||||
- ❌ Unprofessional tone
|
||||
- ❌ No concrete information
|
||||
|
||||
### Score Impact
|
||||
|
||||
| Dimension | Score | Why |
|
||||
|-----------|-------|-----|
|
||||
| Writing Style | 20/100 | Subjective, unprofessional |
|
||||
| Overall | D | Style issues |
|
||||
|
||||
### The Fix
|
||||
|
||||
```markdown
|
||||
## Overview
|
||||
|
||||
Handle complex data processing tasks with configurable validation
|
||||
and error recovery. Supports CSV, JSON, and XML formats with
|
||||
batch processing capabilities.
|
||||
|
||||
## Features
|
||||
|
||||
- Processes 10,000+ records per second
|
||||
- Configurable validation rules
|
||||
- Automatic error recovery
|
||||
- Detailed logging
|
||||
```
|
||||
|
||||
**Improvement:** 20/100 → 80/100 in writing style
|
||||
|
||||
---
|
||||
|
||||
## Anti-Pattern 10: Invalid YAML (F Grade)
|
||||
|
||||
### The Problem
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: my-skill
|
||||
description: This skill should be used when the user asks to "validate data"
|
||||
or "check schemas". It's designed for: data validation, schema checking, and
|
||||
format verification.
|
||||
version: 1.0.0
|
||||
---
|
||||
```
|
||||
|
||||
**Error:** Colon after "for" creates invalid YAML syntax
|
||||
|
||||
**Why this fails:**
|
||||
- ❌ YAML cannot be parsed
|
||||
- ❌ Skill fails to load
|
||||
- ❌ Completely non-functional
|
||||
|
||||
### Score Impact
|
||||
|
||||
| Dimension | Score | Why |
|
||||
|-----------|-------|-----|
|
||||
| Structural Integrity | 0/100 | Invalid YAML |
|
||||
| Overall | F | Cannot load |
|
||||
|
||||
### The Fix
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: data-validator
|
||||
description: This skill should be used when the user asks to "validate data",
|
||||
"check schemas", or "verify formats". Performs data validation, schema
|
||||
checking, and format verification.
|
||||
version: 1.0.0
|
||||
---
|
||||
```
|
||||
|
||||
**Improvement:** F → B (83) overall
|
||||
|
||||
---
|
||||
|
||||
## Quick Anti-Pattern Checklist
|
||||
|
||||
### Description Quality
|
||||
- [ ] Not vague like "helps with tasks"
|
||||
- [ ] Has 3-5 specific trigger phrases
|
||||
- [ ] Uses third person, not second person
|
||||
- [ ] Is 100-300 characters long
|
||||
- [ ] Mentions concrete use cases
|
||||
|
||||
### Content Organization
|
||||
- [ ] SKILL.md under 5,000 words
|
||||
- [ ] Detailed content in references/
|
||||
- [ ] Examples in examples/ directory
|
||||
- [ ] Progressive disclosure followed
|
||||
|
||||
### Writing Style
|
||||
- [ ] No "you", "your", "you're" in body
|
||||
- [ ] Uses imperative verbs (Create, Check, Run)
|
||||
- [ ] Objective and factual
|
||||
- [ ] No marketing language
|
||||
|
||||
### Structural Integrity
|
||||
- [ ] YAML has name and description
|
||||
- [ ] All referenced files exist
|
||||
- [ ] Examples are complete
|
||||
- [ ] Scripts are executable
|
||||
|
||||
---
|
||||
|
||||
## Learn From Mistakes
|
||||
|
||||
Each anti-pattern above represents real issues found in actual skills. Avoid these common mistakes:
|
||||
|
||||
1. **Vague descriptions** → Be specific with trigger phrases
|
||||
2. **Second person** → Use imperative form
|
||||
3. **No progressive disclosure** → Move details to references/
|
||||
4. **Missing fields** → Include name and description
|
||||
5. **Broken references** → Verify all files exist
|
||||
6. **Inconsistent style** → Stick to imperative form
|
||||
7. **Too long description** → Keep under 300 characters
|
||||
8. **No examples** → Include working code
|
||||
9. **Subjective language** → Be factual and objective
|
||||
10. **Invalid YAML** → Validate YAML syntax
|
||||
|
||||
Use `examples-good.md` as a reference for what to do right.
|
||||
@@ -0,0 +1,385 @@
|
||||
# Exemplary Skill Examples
|
||||
|
||||
Collection of high-quality skill examples demonstrating best practices across all quality dimensions. Study these when creating or improving skills.
|
||||
|
||||
## Example 1: hook-development (A+ Grade)
|
||||
|
||||
An exemplary skill demonstrating excellent description quality, progressive disclosure, and writing style.
|
||||
|
||||
### Frontmatter (Description Quality)
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: hook-development
|
||||
description: This skill should be used when the user asks to "create a hook",
|
||||
"add a PreToolUse hook", "validate tool use", "implement prompt-based hooks",
|
||||
"use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous
|
||||
commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop,
|
||||
SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides
|
||||
comprehensive guidance for creating and implementing Claude Code plugin hooks
|
||||
with focus on advanced prompt-based hooks API.
|
||||
version: 0.1.0
|
||||
---
|
||||
```
|
||||
|
||||
**Why this is excellent:**
|
||||
- ✅ 8+ specific trigger phrases covering diverse scenarios
|
||||
- ✅ Third-person format throughout
|
||||
- ✅ Includes specific hook events for precision
|
||||
- ✅ Mentions key concepts (prompt-based hooks API)
|
||||
- ✅ Length is appropriate (~400 characters, acceptable for complex skill)
|
||||
|
||||
### Progressive Disclosure (Content Organization)
|
||||
|
||||
**SKILL.md structure:**
|
||||
- Overview (50 words)
|
||||
- Core concepts (200 words)
|
||||
- Hook events reference (300 words)
|
||||
- Development workflow (500 words)
|
||||
- Best practices (400 words)
|
||||
- **Total: ~1,650 words** - excellent length
|
||||
|
||||
**References/ directory:**
|
||||
```
|
||||
references/
|
||||
├── prompt-based-hooks.md (800 words) - Detailed guide
|
||||
├── hook-patterns.md (1,200 words) - Common patterns
|
||||
└── migration-guide.md (900 words) - Migration info
|
||||
```
|
||||
|
||||
**Why this is excellent:**
|
||||
- ✅ SKILL.md is concise and focused
|
||||
- ✅ Detailed content moved to 3 reference files
|
||||
- ✅ Clear progressive disclosure
|
||||
- ✅ Each reference file has specific purpose
|
||||
|
||||
### Writing Style (Imperative Form)
|
||||
|
||||
**Example from SKILL.md:**
|
||||
```markdown
|
||||
## Hook Development Workflow
|
||||
|
||||
### Step 1: Define the Hook Event
|
||||
Identify which event the hook should trigger on. Review available events
|
||||
in the Hook Events Reference section.
|
||||
|
||||
### Step 2: Create hooks.json
|
||||
Create a hooks.json file in the plugin's .claude-plugin/ directory.
|
||||
Specify the event type and command to execute.
|
||||
|
||||
### Step 3: Implement the Hook Script
|
||||
Write the hook script. Ensure it is executable. Follow the prompt-based
|
||||
hooks API for complex hooks.
|
||||
|
||||
### Step 4: Test the Hook
|
||||
Test the hook locally. Verify it triggers on the correct event.
|
||||
Check output and error handling.
|
||||
```
|
||||
|
||||
**Why this is excellent:**
|
||||
- ✅ Every instruction uses imperative form
|
||||
- ✅ No "you", "your", "should"
|
||||
- ✅ Clear, actionable steps
|
||||
- ✅ Consistent style throughout
|
||||
|
||||
---
|
||||
|
||||
## Example 2: agent-development (A Grade)
|
||||
|
||||
Strong skill with good description and organization.
|
||||
|
||||
### Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: agent-development
|
||||
description: This skill should be used when the user asks to "create an agent",
|
||||
"add an agent", "write a subagent", "agent frontmatter", "when to use description",
|
||||
"agent examples", "agent tools", "agent colors", "autonomous agent", or needs
|
||||
guidance on agent structure, system prompts, triggering conditions, or agent
|
||||
development best practices for Claude Code plugins.
|
||||
version: 0.1.0
|
||||
---
|
||||
```
|
||||
|
||||
**Strengths:**
|
||||
- ✅ Multiple specific trigger phrases
|
||||
- ✅ Covers agent creation scenarios
|
||||
- ✅ Mentions specific agent attributes
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
agent-development/
|
||||
├── SKILL.md (1,438 words)
|
||||
├── references/
|
||||
│ ├── agent-generation-prompt.md (500 words)
|
||||
│ └── agent-anatomy.md (400 words)
|
||||
└── examples/
|
||||
├── task-agent.md (complete example)
|
||||
├── review-agent.md (complete example)
|
||||
└── interactive-agent.md (complete example)
|
||||
```
|
||||
|
||||
**Strengths:**
|
||||
- ✅ Lean SKILL.md
|
||||
- ✅ Focused reference files
|
||||
- ✅ Complete working examples
|
||||
- ✅ Clear organization
|
||||
|
||||
---
|
||||
|
||||
## Example 3: mcp-integration (A- Grade)
|
||||
|
||||
Comprehensive skill with excellent progressive disclosure.
|
||||
|
||||
### Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: mcp-integration
|
||||
description: This skill should be used when the user asks to "add MCP server",
|
||||
"integrate MCP", "configure MCP in plugin", "use .mcp.json", "set up Model
|
||||
Context Protocol", "connect external service", mentions "${CLAUDE_PLUGIN_ROOT}
|
||||
with MCP", or discusses MCP server types (SSE, stdio, HTTP, WebSocket). Provides
|
||||
comprehensive guidance for integrating Model Context Protocol servers into Claude
|
||||
Code plugins for external tool and service integration.
|
||||
version: 0.1.0
|
||||
---
|
||||
```
|
||||
|
||||
**Strengths:**
|
||||
- ✅ Specific MCP-related trigger phrases
|
||||
- ✅ Lists server types for precision
|
||||
- ✅ Mentions key configuration elements
|
||||
|
||||
### Progressive Disclosure
|
||||
|
||||
**SKILL.md**: ~1,800 words (core concepts, basic setup)
|
||||
|
||||
**References/**:
|
||||
- `mcp-server-types.md` - Detailed server type comparisons
|
||||
- `mcp-configuration.md` - Configuration examples
|
||||
- `mcp-best-practices.md` - Integration patterns
|
||||
- `mcp-troubleshooting.md` - Common issues
|
||||
|
||||
**Why this works:**
|
||||
- ✅ Main SKILL.md covers essentials
|
||||
- ✅ Each reference is 1,000-2,000 words
|
||||
- ✅ Loaded only when needed
|
||||
- ✅ Clear topic separation
|
||||
|
||||
---
|
||||
|
||||
## Excellent Description Examples
|
||||
|
||||
### Example: API-Contract Skill (Ideal Description)
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: api-contract-manager
|
||||
description: This skill should be used when the user asks to "validate API contract",
|
||||
"check API compatibility", "version API schema", "detect breaking changes", or
|
||||
"ensure API contract compliance". Manages API contracts through validation,
|
||||
versioning, and compatibility checking. Use when designing new endpoints or
|
||||
ensuring backward compatibility.
|
||||
version: 0.1.0
|
||||
---
|
||||
```
|
||||
|
||||
**Analysis:**
|
||||
- ✅ 5 specific trigger phrases
|
||||
- ✅ Third person throughout
|
||||
- ✅ 230 characters (ideal length)
|
||||
- ✅ Clear use cases
|
||||
- ✅ Mentions when to use (designing, compatibility)
|
||||
|
||||
### Example: PDF-Editor Skill (Ideal Description)
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: pdf-editor
|
||||
description: This skill should be used when the user asks to "rotate PDF", "merge
|
||||
PDF files", "split PDF pages", "compress PDF", or "crop PDF pages". Perform common
|
||||
PDF manipulation operations including rotation, merging, splitting, compression,
|
||||
and cropping. Works with local PDF files.
|
||||
version: 0.1.0
|
||||
---
|
||||
```
|
||||
|
||||
**Analysis:**
|
||||
- ✅ 5 specific operations as triggers
|
||||
- ✅ Lists all supported operations
|
||||
- ✅ Specifies working context (local files)
|
||||
- ✅ 180 characters (excellent length)
|
||||
|
||||
---
|
||||
|
||||
## Excellent Progressive Disclosure Examples
|
||||
|
||||
### Example: Frontend-Builder Skill
|
||||
|
||||
**SKILL.md** (1,800 words):
|
||||
- Overview
|
||||
- Quick Start (5 steps)
|
||||
- Basic Component Creation
|
||||
- Common Operations
|
||||
- Reference to detailed guides
|
||||
|
||||
**References/**:
|
||||
- `react-patterns.md` (2,500 words) - React specific patterns
|
||||
- `vue-patterns.md` (2,000 words) - Vue specific patterns
|
||||
- `styling-guide.md` (1,800 words) - CSS/styling approaches
|
||||
- `deployment.md` (1,500 words) - Build and deploy
|
||||
|
||||
**Examples/**:
|
||||
- `hello-world-react/` - Complete React example
|
||||
- `hello-world-vue/` - Complete Vue example
|
||||
- `component-library/` - Reusable components
|
||||
|
||||
**Why this works:**
|
||||
1. SKILL.md gets users started quickly
|
||||
2. Framework-specific details in references/
|
||||
3. Complete examples for copy-paste
|
||||
4. Progressive: overview → basics → details → examples
|
||||
|
||||
---
|
||||
|
||||
## Excellent Writing Style Examples
|
||||
|
||||
### Example: From Test-Driven Development Skill
|
||||
|
||||
```markdown
|
||||
## TDD Workflow
|
||||
|
||||
### Red: Write a Failing Test
|
||||
Start by writing a test that fails. This test defines the desired behavior.
|
||||
Run the test to confirm it fails.
|
||||
|
||||
### Green: Make the Test Pass
|
||||
Write the minimum code to make the test pass. Focus on making it work,
|
||||
not making it perfect. Run the test to confirm it passes.
|
||||
|
||||
### Refactor: Improve the Code
|
||||
Refactor the code while keeping tests green. Improve structure, readability,
|
||||
and maintainability. Run tests after each change.
|
||||
|
||||
### Repeat
|
||||
Continue the cycle for each feature. Write test, make it pass, refactor.
|
||||
```
|
||||
|
||||
**Analysis:**
|
||||
- ✅ Imperative form throughout
|
||||
- ✅ Clear, actionable instructions
|
||||
- ✅ No second person
|
||||
- ✅ Consistent style
|
||||
- ✅ Easy to follow
|
||||
|
||||
---
|
||||
|
||||
## Excellent Reference File Organization
|
||||
|
||||
### Example: Git-Workflow Skill References
|
||||
|
||||
```
|
||||
references/
|
||||
├── commit-conventions.md (1,500 words)
|
||||
│ ├── Commit message format
|
||||
│ ├── Type categories
|
||||
│ ├── Scope values
|
||||
│ └── Examples by type
|
||||
├── branch-strategy.md (1,800 words)
|
||||
│ ├── Branch types
|
||||
│ ├── Merging policies
|
||||
│ ├── Release workflow
|
||||
│ └── Hotfix procedures
|
||||
└── troubleshooting.md (1,200 words)
|
||||
├── Common issues
|
||||
├── Recovery procedures
|
||||
└── Best practices
|
||||
```
|
||||
|
||||
**Each reference file:**
|
||||
- ✅ Focused on single topic
|
||||
- ✅ Self-contained
|
||||
- ✅ Cross-references others when needed
|
||||
- ✅ Loaded only when relevant
|
||||
|
||||
---
|
||||
|
||||
## Key Takeaways from Excellent Skills
|
||||
|
||||
### 1. Description Quality
|
||||
|
||||
**Good descriptions:**
|
||||
- Have 5+ specific trigger phrases
|
||||
- Use third person consistently
|
||||
- Are 100-300 characters long
|
||||
- Include concrete use cases
|
||||
|
||||
**Example template:**
|
||||
```yaml
|
||||
description: This skill should be used when the user asks to "action 1",
|
||||
"action 2", "action 3", or "action 4". Brief description of what the skill
|
||||
does. When to use it.
|
||||
```
|
||||
|
||||
### 2. Progressive Disclosure
|
||||
|
||||
**Good organization:**
|
||||
- SKILL.md: 1,500-2,000 words (core only)
|
||||
- references/: 1,500-2,500 words per file (details)
|
||||
- examples/: Complete working code
|
||||
- scripts/: Utility tools
|
||||
|
||||
**Rule of thumb:** If a section exceeds 500 words and covers details,
|
||||
consider moving it to references/.
|
||||
|
||||
### 3. Writing Style
|
||||
|
||||
**Good style:**
|
||||
- Use imperative verbs: Create, Validate, Check, Run
|
||||
- Avoid: You should, You can, You need to
|
||||
- Be objective and factual
|
||||
- Keep instructions actionable
|
||||
|
||||
### 4. Structural Integrity
|
||||
|
||||
**Good structure:**
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md (required)
|
||||
├── references/ (optional, for details)
|
||||
├── examples/ (optional, for working code)
|
||||
└── scripts/ (optional, for utilities)
|
||||
```
|
||||
|
||||
**Validation checklist:**
|
||||
- [ ] YAML frontmatter has name and description
|
||||
- [ ] All referenced files exist
|
||||
- [ ] Examples are complete
|
||||
- [ ] Scripts are executable
|
||||
|
||||
---
|
||||
|
||||
## Study These Skills
|
||||
|
||||
For hands-on learning, study these high-quality skills in your environment:
|
||||
|
||||
```bash
|
||||
# Explore hook-development structure
|
||||
ls -la ~/.claude/plugins/cache/*/skills/hook-development/
|
||||
|
||||
# Read agent-development SKILL.md
|
||||
cat ~/.claude/skills/agent-development/SKILL.md
|
||||
|
||||
# Review mcp-integration references
|
||||
ls -la ~/.claude/skills/mcp-integration/references/
|
||||
```
|
||||
|
||||
Each demonstrates different strengths:
|
||||
- **hook-development**: Progressive disclosure, utilities
|
||||
- **agent-development**: Clean examples, focused content
|
||||
- **mcp-integration**: Comprehensive references, clear organization
|
||||
|
||||
Use these as templates when creating or improving your own skills.
|
||||
@@ -0,0 +1,569 @@
|
||||
# Skill Quality Scoring Criteria
|
||||
|
||||
Detailed evaluation rubrics for each quality dimension assessed by the skill-quality-reviewer.
|
||||
|
||||
## 1. Description Quality (25% Weight)
|
||||
|
||||
Assesses the effectiveness of the frontmatter description in triggering the skill appropriately.
|
||||
|
||||
### Scoring Breakdown
|
||||
|
||||
#### Trigger Phrases Clarity (0-25 points)
|
||||
|
||||
**25 points (Excellent):**
|
||||
- 5+ specific, concrete trigger phrases
|
||||
- Phrases cover diverse use cases
|
||||
- Each phrase is something a user would naturally say
|
||||
- Phrases include both specific tasks and general scenarios
|
||||
|
||||
**Example:**
|
||||
```yaml
|
||||
description: This skill should be used when the user asks to "create a hook",
|
||||
"add a PreToolUse hook", "validate tool use", "implement prompt-based hooks",
|
||||
"set up event-driven automation", or mentions hook events (PreToolUse, PostToolUse,
|
||||
Stop, SubagentStop).
|
||||
```
|
||||
|
||||
**20 points (Good):**
|
||||
- 3-4 specific trigger phrases
|
||||
- Good variety of scenarios
|
||||
- Most phrases are natural user language
|
||||
|
||||
**15 points (Acceptable):**
|
||||
- 2-3 trigger phrases
|
||||
- Some variety but may miss key scenarios
|
||||
- Phrases are reasonably specific
|
||||
|
||||
**10 points (Needs Work):**
|
||||
- 1-2 trigger phrases
|
||||
- Limited variety
|
||||
- Some phrases too generic
|
||||
|
||||
**5 points (Poor):**
|
||||
- Single vague trigger phrase
|
||||
- Missing common use cases
|
||||
|
||||
**0 points (Fail):**
|
||||
- No trigger phrases
|
||||
- Trigger phrases are meaningless
|
||||
|
||||
---
|
||||
|
||||
#### Third-Person Format (0-25 points)
|
||||
|
||||
**25 points (Excellent):**
|
||||
- Consistently uses "This skill should be used when..."
|
||||
- Never uses second person ("you", "your")
|
||||
- Professional, objective tone
|
||||
|
||||
**20 points (Good):**
|
||||
- Generally uses third person
|
||||
- Minor inconsistencies but overall correct
|
||||
|
||||
**10 points (Needs Work):**
|
||||
- Mix of third and second person
|
||||
- Inconsistent formatting
|
||||
|
||||
**0 points (Fail):**
|
||||
- Uses second person ("Use this when you want...")
|
||||
- First person references
|
||||
|
||||
---
|
||||
|
||||
#### Description Length (0-25 points)
|
||||
|
||||
**25 points (Excellent):**
|
||||
- 150-300 characters
|
||||
- Concise yet comprehensive
|
||||
- No unnecessary words
|
||||
|
||||
**20 points (Good):**
|
||||
- 100-150 or 300-400 characters
|
||||
- Slightly short or long but acceptable
|
||||
|
||||
**15 points (Acceptable):**
|
||||
- 80-100 or 400-500 characters
|
||||
- Beginning to be too concise or verbose
|
||||
|
||||
**10 points (Needs Work):**
|
||||
- 50-80 or 500-700 characters
|
||||
- Too brief or too verbose
|
||||
|
||||
**5 points (Poor):**
|
||||
- Under 50 or over 700 characters
|
||||
|
||||
**0 points (Fail):**
|
||||
- Effectively empty or extremely long
|
||||
|
||||
---
|
||||
|
||||
#### Specific Scenarios (0-25 points)
|
||||
|
||||
**25 points (Excellent):**
|
||||
- Multiple concrete scenarios mentioned
|
||||
- Clear scope boundaries (when NOT to use)
|
||||
- Specific domains or use cases identified
|
||||
|
||||
**Example:**
|
||||
```yaml
|
||||
description: ... Use when designing new API endpoints, validating existing
|
||||
contracts, or checking breaking changes. NOT for general API testing or
|
||||
documentation generation.
|
||||
```
|
||||
|
||||
**20 points (Good):**
|
||||
- Good scenario coverage
|
||||
- Clear use cases
|
||||
|
||||
**15 points (Acceptable):**
|
||||
- Basic scenario descriptions
|
||||
- Could be more specific
|
||||
|
||||
**10 points (Needs Work):**
|
||||
- Vague scenarios
|
||||
- Unclear when to use
|
||||
|
||||
**0 points (Fail):**
|
||||
- No scenarios mentioned
|
||||
- Purely generic description
|
||||
|
||||
---
|
||||
|
||||
## 2. Content Organization (30% Weight)
|
||||
|
||||
Evaluates adherence to progressive disclosure principles and effective content organization.
|
||||
|
||||
### Scoring Breakdown
|
||||
|
||||
#### Progressive Disclosure (0-30 points)
|
||||
|
||||
**30 points (Excellent):**
|
||||
- SKILL.md under 2,000 words
|
||||
- All detailed content in references/
|
||||
- Clear separation of overview and details
|
||||
- References/ properly organized with multiple files
|
||||
|
||||
**25 points (Good):**
|
||||
- SKILL.md 2,000-3,000 words
|
||||
- Most detailed content moved to references/
|
||||
- Good separation of concerns
|
||||
|
||||
**20 points (Acceptable):**
|
||||
- SKILL.md 3,000-5,000 words
|
||||
- Some detailed content still in SKILL.md
|
||||
- References/ used but could be better
|
||||
|
||||
**15 points (Needs Work):**
|
||||
- SKILL.md 5,000-7,000 words
|
||||
- Significant content should be moved
|
||||
- Limited use of references/
|
||||
|
||||
**10 points (Poor):**
|
||||
- SKILL.md over 7,000 words
|
||||
- Minimal or no references/ usage
|
||||
|
||||
**0 points (Fail):**
|
||||
- Everything in one large file
|
||||
- No progressive disclosure
|
||||
|
||||
---
|
||||
|
||||
#### SKILL.md Length Control (0-25 points)
|
||||
|
||||
**25 points (Excellent):**
|
||||
- 1,500-2,000 words (optimal)
|
||||
- Every word serves a purpose
|
||||
- No redundancy
|
||||
|
||||
**20 points (Good):**
|
||||
- 1,000-1,500 or 2,000-3,000 words
|
||||
- Generally concise
|
||||
|
||||
**15 points (Acceptable):**
|
||||
- 800-1,000 or 3,000-4,000 words
|
||||
- Some unnecessary content
|
||||
|
||||
**10 points (Needs Work):**
|
||||
- 500-800 or 4,000-5,000 words
|
||||
- Could be significantly trimmed
|
||||
|
||||
**5 points (Poor):**
|
||||
- Under 500 or over 5,000 words
|
||||
- Major length issues
|
||||
|
||||
---
|
||||
|
||||
#### References/ Usage (0-25 points)
|
||||
|
||||
**25 points (Excellent):**
|
||||
- 3+ well-organized reference files
|
||||
- Clear topics (patterns, advanced, examples, etc.)
|
||||
- Properly referenced in SKILL.md
|
||||
- Each file has clear purpose
|
||||
|
||||
**20 points (Good):**
|
||||
- 2-3 reference files
|
||||
- Good organization
|
||||
- Referenced in SKILL.md
|
||||
|
||||
**15 points (Acceptable):**
|
||||
- 1-2 reference files
|
||||
- Basic organization
|
||||
|
||||
**10 points (Needs Work):**
|
||||
- Single reference file or poorly organized
|
||||
- Not well referenced
|
||||
|
||||
**5 points (Poor):**
|
||||
- References/ exists but minimal content
|
||||
- Not referenced from SKILL.md
|
||||
|
||||
**0 points (Fail):**
|
||||
- No references/ directory when clearly needed
|
||||
|
||||
---
|
||||
|
||||
#### Logical Organization (0-20 points)
|
||||
|
||||
**20 points (Excellent):**
|
||||
- Clear section hierarchy
|
||||
- Logical flow from overview to details
|
||||
- Easy to navigate
|
||||
- Consistent structure
|
||||
|
||||
**15 points (Good):**
|
||||
- Generally well organized
|
||||
- Minor flow issues
|
||||
|
||||
**10 points (Acceptable):**
|
||||
- Basic organization present
|
||||
- Some structural confusion
|
||||
|
||||
**5 points (Needs Work):**
|
||||
- Poor organization
|
||||
- Difficult to follow
|
||||
|
||||
**0 points (Fail):**
|
||||
- No clear structure
|
||||
- Content randomly arranged
|
||||
|
||||
---
|
||||
|
||||
## 3. Writing Style (20% Weight)
|
||||
|
||||
Evaluates adherence to skill writing conventions and style consistency.
|
||||
|
||||
### Scoring Breakdown
|
||||
|
||||
#### Imperative Form Usage (0-40 points)
|
||||
|
||||
**40 points (Excellent):**
|
||||
- 95%+ of instructions use imperative form
|
||||
- Consistent throughout
|
||||
- Natural, readable instructions
|
||||
|
||||
**Good examples:**
|
||||
```
|
||||
Create the skill directory structure.
|
||||
Validate the YAML frontmatter.
|
||||
Check for required fields.
|
||||
Read the SKILL.md file.
|
||||
Generate the quality report.
|
||||
```
|
||||
|
||||
**30 points (Good):**
|
||||
- 80-95% imperative form
|
||||
- Generally consistent
|
||||
- Minor exceptions
|
||||
|
||||
**20 points (Acceptable):**
|
||||
- 60-80% imperative form
|
||||
- Inconsistent usage
|
||||
|
||||
**10 points (Needs Work):**
|
||||
- 40-60% imperative form
|
||||
- Significant inconsistency
|
||||
|
||||
**0 points (Fail):**
|
||||
- Less than 40% imperative form
|
||||
- Mostly descriptive or second-person
|
||||
|
||||
---
|
||||
|
||||
#### No Second Person (0-30 points)
|
||||
|
||||
**30 points (Excellent):**
|
||||
- Zero instances of "you", "your", "you're"
|
||||
- Clean imperative style throughout
|
||||
|
||||
**20 points (Good):**
|
||||
- 1-3 minor instances
|
||||
- Generally avoids second person
|
||||
|
||||
**10 points (Acceptable):**
|
||||
- 4-6 instances
|
||||
- Some second person creeping in
|
||||
|
||||
**5 points (Needs Work):**
|
||||
- 7-10 instances
|
||||
- Frequent second person
|
||||
|
||||
**0 points (Fail):**
|
||||
- 10+ instances
|
||||
- Heavily uses second person
|
||||
|
||||
---
|
||||
|
||||
#### Objective Language (0-30 points)
|
||||
|
||||
**30 points (Excellent):**
|
||||
- Factual, instructional tone
|
||||
- No subjective opinions
|
||||
- Professional language
|
||||
- Clear and direct
|
||||
|
||||
**20 points (Good):**
|
||||
- Generally objective
|
||||
- Minor subjectivity
|
||||
|
||||
**15 points (Acceptable):**
|
||||
- Mostly objective with some opinion
|
||||
- Generally professional
|
||||
|
||||
**10 points (Needs Work):**
|
||||
- Subjective language present
|
||||
- Conversational tone
|
||||
|
||||
**0 points (Fail):**
|
||||
- Highly subjective
|
||||
- Unprofessional or casual tone
|
||||
|
||||
---
|
||||
|
||||
## 4. Structural Integrity (25% Weight)
|
||||
|
||||
Evaluates the physical structure, completeness, and correctness of the skill.
|
||||
|
||||
### Scoring Breakdown
|
||||
|
||||
#### YAML Frontmatter (0-30 points)
|
||||
|
||||
**30 points (Excellent):**
|
||||
- All required fields present (name, description)
|
||||
- Optional fields used appropriately (version)
|
||||
- Valid YAML syntax
|
||||
- No prohibited fields
|
||||
- Well-formatted
|
||||
|
||||
**Example of excellent frontmatter:**
|
||||
```yaml
|
||||
---
|
||||
name: skill-quality-reviewer
|
||||
description: This skill should be used when the user asks to "analyze skill quality",
|
||||
"evaluate this skill", "review skill quality", or mentions quality review of Claude Skills.
|
||||
version: 0.1.0
|
||||
---
|
||||
```
|
||||
|
||||
**25 points (Good):**
|
||||
- All required fields present
|
||||
- Valid YAML
|
||||
- Minor formatting issues
|
||||
|
||||
**20 points (Acceptable):**
|
||||
- Required fields present
|
||||
- Valid YAML
|
||||
- Some missing recommended fields
|
||||
|
||||
**10 points (Needs Work):**
|
||||
- Missing some required fields
|
||||
- YAML issues present
|
||||
|
||||
**0 points (Fail):**
|
||||
- Missing required fields
|
||||
- Invalid YAML syntax
|
||||
- Cannot parse frontmatter
|
||||
|
||||
---
|
||||
|
||||
#### Directory Structure (0-30 points)
|
||||
|
||||
**30 points (Excellent):**
|
||||
- Proper skill structure:
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md
|
||||
├── references/
|
||||
├── examples/
|
||||
└── scripts/
|
||||
```
|
||||
- Each subdirectory has clear purpose
|
||||
- No unnecessary files
|
||||
- Clean naming conventions
|
||||
|
||||
**25 points (Good):**
|
||||
- Core structure correct
|
||||
- Minor organization issues
|
||||
|
||||
**20 points (Acceptable):**
|
||||
- Basic structure present
|
||||
- Some organizational issues
|
||||
|
||||
**10 points (Needs Work):**
|
||||
- Missing key directories
|
||||
- Poor organization
|
||||
|
||||
**0 points (Fail):**
|
||||
- No clear structure
|
||||
- Chaotic organization
|
||||
|
||||
---
|
||||
|
||||
#### Resource References (0-40 points)
|
||||
|
||||
**40 points (Excellent):**
|
||||
- All referenced files exist
|
||||
- References are accurate and specific
|
||||
- Examples are complete and working
|
||||
- Scripts are executable
|
||||
- No broken links or references
|
||||
|
||||
**Check method:**
|
||||
- Read SKILL.md
|
||||
- Extract all references to files (e.g., `references/patterns.md`)
|
||||
- Verify each file exists
|
||||
- Verify examples/ and scripts/ contents
|
||||
|
||||
**30 points (Good):**
|
||||
- All references exist
|
||||
- Minor issues with completeness
|
||||
|
||||
**20 points (Acceptable):**
|
||||
- Most references valid
|
||||
- Some broken or incomplete references
|
||||
|
||||
**10 points (Needs Work):**
|
||||
- Multiple broken references
|
||||
- Incomplete examples
|
||||
|
||||
**0 points (Fail):**
|
||||
- Many broken references
|
||||
- Examples don't work
|
||||
- Scripts not executable
|
||||
|
||||
---
|
||||
|
||||
## Grade Calculation
|
||||
|
||||
### Weighted Score Formula
|
||||
|
||||
```
|
||||
Overall Score = (Description Quality × 0.25) +
|
||||
(Content Organization × 0.30) +
|
||||
(Writing Style × 0.20) +
|
||||
(Structural Integrity × 0.25)
|
||||
```
|
||||
|
||||
### Letter Grade Mapping
|
||||
|
||||
| Score Range | Grade | Quality Level | Certification |
|
||||
|-------------|-------|---------------|--------------|
|
||||
| 97-100 | A+ | Exemplary | Certified |
|
||||
| 93-96 | A | Excellent | Certified |
|
||||
| 90-92 | A- | Very Good | Certified |
|
||||
| 87-89 | B+ | Good | Certified |
|
||||
| 83-86 | B | Above Average | Certified |
|
||||
| 80-82 | B- | Solid | Certified |
|
||||
| 77-79 | C+ | Acceptable | Review |
|
||||
| 73-76 | C | Satisfactory | Review |
|
||||
| 70-72 | C- | Minimal | Review |
|
||||
| 67-69 | D+ | Below Standard | Reject |
|
||||
| 63-66 | D | Poor | Reject |
|
||||
| 60-62 | D- | Very Poor | Reject |
|
||||
| 0-59 | F | Fail | Reject |
|
||||
|
||||
### Certification Thresholds
|
||||
|
||||
For "Certified" status (recommended for sharing):
|
||||
- Overall score: ≥80/100
|
||||
- Description Quality: ≥75/100
|
||||
- Content Organization: ≥75/100
|
||||
- Writing Style: ≥70/100
|
||||
- Structural Integrity: ≥80/100
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Scoring Guide
|
||||
|
||||
### Description Quality Quick Checks
|
||||
|
||||
- [ ] Description has 3-5 specific trigger phrases
|
||||
- [ ] Uses third person ("This skill should be used when...")
|
||||
- [ ] Length is 100-300 characters
|
||||
- [ ] Mentions concrete use cases
|
||||
|
||||
### Content Organization Quick Checks
|
||||
|
||||
- [ ] SKILL.md under 5,000 words (ideally 1,500-2,000)
|
||||
- [ ] Detailed content in references/
|
||||
- [ ] Examples in examples/ directory
|
||||
- [ ] Scripts in scripts/ directory
|
||||
|
||||
### Writing Style Quick Checks
|
||||
|
||||
- [ ] Instructions use verbs (Create, Validate, Check)
|
||||
- [ ] No "you", "your", "you're" in body
|
||||
- [ ] Objective, instructional tone
|
||||
- [ ] Consistent style throughout
|
||||
|
||||
### Structural Integrity Quick Checks
|
||||
|
||||
- [ ] YAML has name and description
|
||||
- [ ] All referenced files exist
|
||||
- [ ] Examples are complete
|
||||
- [ ] Scripts are executable
|
||||
|
||||
---
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Scenario 1: New Skill Submission
|
||||
|
||||
**Context:** Developer submits a new skill for review.
|
||||
|
||||
**Evaluation Focus:**
|
||||
- Description quality (is it clear when to use?)
|
||||
- Progressive disclosure (is content organized?)
|
||||
- Writing style (does it follow conventions?)
|
||||
|
||||
**Passing Criteria:** B- (80) or higher overall
|
||||
|
||||
---
|
||||
|
||||
### Scenario 2: Skill Quality Audit
|
||||
|
||||
**Context:** Periodic review of existing skills.
|
||||
|
||||
**Evaluation Focus:**
|
||||
- All dimensions equally
|
||||
- Identify improvement opportunities
|
||||
- Track quality over time
|
||||
|
||||
**Passing Criteria:** C (73) or higher overall
|
||||
|
||||
---
|
||||
|
||||
### Scenario 3: Pre-Publication Check
|
||||
|
||||
**Context:** Final check before sharing skill publicly.
|
||||
|
||||
**Evaluation Focus:**
|
||||
- Structural integrity (must be complete)
|
||||
- Description quality (must be discoverable)
|
||||
- No critical issues
|
||||
|
||||
**Passing Criteria:** B (83) or higher overall
|
||||
|
||||
---
|
||||
|
||||
This scoring criteria document provides the detailed rubrics used by skill-quality-reviewer to evaluate Claude Skills. Use this as a reference when interpreting quality reports or planning improvements.
|
||||
@@ -0,0 +1,28 @@
|
||||
#!/bin/bash
|
||||
# extract-yaml.sh - Extract YAML frontmatter from SKILL.md files
|
||||
# Part of skill-quality-reviewer
|
||||
|
||||
# Usage: ./extract-yaml.sh <path-to-skill>
|
||||
# Example: ./extract-yaml.sh ~/.claude/skills/git-workflow
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
# Check if path provided
|
||||
if [ $# -eq 0 ]; then
|
||||
echo "Usage: $0 <path-to-skill>"
|
||||
echo "Example: $0 ~/.claude/skills/git-workflow"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
SKILL_PATH="$1"
|
||||
SKILL_FILE="${SKILL_PATH}/SKILL.md"
|
||||
|
||||
# Check if SKILL.md exists
|
||||
if [ ! -f "$SKILL_FILE" ]; then
|
||||
echo "Error: SKILL.md not found at ${SKILL_FILE}"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Extract YAML frontmatter (between --- lines)
|
||||
# Using sed to extract content between first and second ---
|
||||
sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$SKILL_FILE"
|
||||
@@ -0,0 +1,39 @@
|
||||
#!/usr/bin/env python3
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import re
|
||||
from pathlib import Path
|
||||
|
||||
REF_RE = re.compile(r'(references/[^\s)`]+|examples/[^\s)`]+|scripts/[^\s)`]+|assets/[^\s)`]+)')
|
||||
|
||||
|
||||
def parse_args() -> argparse.Namespace:
|
||||
parser = argparse.ArgumentParser(description='Audit a skill for missing local references and rough size metrics.')
|
||||
parser.add_argument('skill_path', help='Path to the skill directory')
|
||||
return parser.parse_args()
|
||||
|
||||
|
||||
def main() -> int:
|
||||
args = parse_args()
|
||||
root = Path(args.skill_path).expanduser().resolve()
|
||||
skill_md = root / 'SKILL.md'
|
||||
if not skill_md.exists():
|
||||
print('missing SKILL.md')
|
||||
return 1
|
||||
text = skill_md.read_text(encoding='utf-8')
|
||||
words = len(re.findall(r'\w+', text))
|
||||
print(f'word_count={words}')
|
||||
refs = sorted(set(match.rstrip('*:.,') for match in REF_RE.findall(text)))
|
||||
missing = [ref for ref in refs if not (root / ref).exists()]
|
||||
if missing:
|
||||
print('missing_refs=')
|
||||
for ref in missing:
|
||||
print(f'- {ref}')
|
||||
else:
|
||||
print('missing_refs=0')
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
raise SystemExit(main())
|
||||
Reference in New Issue
Block a user