255 lines
6.5 KiB
Markdown
255 lines
6.5 KiB
Markdown
# Skill Review Content
|
|
|
|
Review content quality (clarity, completeness, usefulness) of a skill's SKILL.md file.
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
/meta-claude:skill:review-content [skill-path]
|
|
```
|
|
|
|
## What This Does
|
|
|
|
Analyzes SKILL.md content for:
|
|
|
|
- **Clarity:** Instructions are clear, well-structured, and easy to follow
|
|
- **Completeness:** All necessary information is present and organized
|
|
- **Usefulness:** Content provides value for Claude's context
|
|
- **Examples:** Practical, accurate, and helpful examples are included
|
|
- **Actionability:** Instructions are specific and executable
|
|
|
|
## Instructions
|
|
|
|
Read and analyze the SKILL.md file at the provided path. Evaluate content across five quality dimensions:
|
|
|
|
### 1. Clarity Assessment
|
|
|
|
Check for:
|
|
|
|
- Clear, concise writing without unnecessary verbosity
|
|
- Logical structure with appropriate headings and sections
|
|
- Technical terms explained when necessary
|
|
- Consistent terminology throughout
|
|
- Proper markdown formatting (lists, code blocks, emphasis)
|
|
|
|
**Issues to flag:**
|
|
|
|
- Ambiguous or vague instructions
|
|
- Confusing organization or missing structure
|
|
- Unexplained jargon or acronyms
|
|
- Inconsistent terminology
|
|
- Poor markdown formatting
|
|
|
|
### 2. Completeness Assessment
|
|
|
|
Verify:
|
|
|
|
- Purpose and use cases clearly stated
|
|
- All necessary context provided
|
|
- Prerequisites or dependencies documented
|
|
- Edge cases and error handling covered
|
|
- Table of contents (if content is long)
|
|
|
|
**Issues to flag:**
|
|
|
|
- Missing purpose statement or unclear use cases
|
|
- Incomplete workflows or partial instructions
|
|
- Undocumented dependencies
|
|
- No error handling guidance
|
|
- Long content without navigation aids
|
|
|
|
### 3. Examples Assessment
|
|
|
|
Evaluate:
|
|
|
|
- Examples are practical and relevant
|
|
- Code examples have correct syntax
|
|
- Examples demonstrate real use cases
|
|
- Sufficient variety to cover common scenarios
|
|
- Examples are accurate and tested
|
|
|
|
**Issues to flag:**
|
|
|
|
- Missing examples for key workflows
|
|
- Incorrect or broken code examples
|
|
- Trivial examples that don't demonstrate value
|
|
- Insufficient coverage of use cases
|
|
- Outdated or inaccurate examples
|
|
|
|
### 4. Actionability Assessment
|
|
|
|
Confirm:
|
|
|
|
- Instructions are specific and executable
|
|
- Clear steps for workflows
|
|
- Commands or code ready to use
|
|
- Expected outcomes documented
|
|
- Success criteria defined
|
|
|
|
**Issues to flag:**
|
|
|
|
- Vague instructions without concrete steps
|
|
- Missing command syntax or parameters
|
|
- No expected output examples
|
|
- Unclear success criteria
|
|
- Abstract guidance without implementation details
|
|
|
|
### 5. Usefulness for Claude
|
|
|
|
Assess:
|
|
|
|
- Description triggers skill appropriately
|
|
- Content enhances Claude's capabilities
|
|
- Follows progressive disclosure principle
|
|
- Avoids redundant general knowledge
|
|
- Provides specialized context Claude lacks
|
|
|
|
**Issues to flag:**
|
|
|
|
- Description too narrow or too broad
|
|
- Content duplicates Claude's general knowledge
|
|
- Excessive verbosity wasting tokens
|
|
- Missing specialized knowledge
|
|
- Poor description for skill triggering
|
|
|
|
## Scoring Guidelines
|
|
|
|
Each quality dimension receives PASS or FAIL based on these criteria:
|
|
|
|
**PASS if:**
|
|
|
|
- No issues flagged in that dimension, OR
|
|
- Only Tier 1 (auto-fixable) issues found
|
|
|
|
**FAIL if:**
|
|
|
|
- 2+ issues of any tier in that dimension, OR
|
|
- Any Tier 2 (guided fix) issue found, OR
|
|
- Any Tier 3 (complex) issue found
|
|
|
|
**Rationale:** A dimension with only simple auto-fixable issues should not fail
|
|
the review, but substantive problems should be flagged for remediation.
|
|
|
|
## Quality Report Format
|
|
|
|
Generate a structured report with the following sections:
|
|
|
|
```text
|
|
## Content Quality Review: <skill-name>
|
|
|
|
**Overall Status:** PASS | FAIL
|
|
|
|
### Summary
|
|
|
|
[1-2 sentence overview of quality assessment]
|
|
|
|
### Quality Scores
|
|
|
|
- Clarity: PASS | FAIL
|
|
- Completeness: PASS | FAIL
|
|
- Examples: PASS | FAIL
|
|
- Actionability: PASS | FAIL
|
|
- Usefulness: PASS | FAIL
|
|
|
|
### Issues Found
|
|
|
|
#### Tier 1 (Simple - Auto-fixable)
|
|
[Issues that can be automatically corrected]
|
|
- [ ] Issue description (e.g., "Missing blank lines around code blocks")
|
|
|
|
#### Tier 2 (Medium - Guided fixes)
|
|
[Issues requiring judgment but clear remediation]
|
|
- [ ] Issue description (e.g., "Add examples for error handling workflow")
|
|
|
|
#### Tier 3 (Complex - Manual review)
|
|
[Issues requiring significant rework or design decisions]
|
|
- [ ] Issue description (e.g., "Restructure content for better progressive disclosure")
|
|
|
|
### Recommendations
|
|
|
|
[Specific, actionable suggestions for improvement]
|
|
|
|
### Strengths
|
|
|
|
[Positive aspects worth highlighting]
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
**If SKILL.md not found:**
|
|
|
|
```text
|
|
Error: SKILL.md not found at <skill-path>
|
|
```
|
|
|
|
Action: Verify path is correct or run `/meta-claude:skill:create` first
|
|
|
|
**If content passes review:**
|
|
|
|
- Report: "Content Quality Review: PASS"
|
|
- Highlight strengths
|
|
- Note minor suggestions if any
|
|
- Exit with success
|
|
|
|
**If content has issues:**
|
|
|
|
- Report: "Content Quality Review: FAIL"
|
|
- List all issues categorized by tier
|
|
- Provide specific recommendations
|
|
- Exit with failure
|
|
|
|
**Issue Categorization:**
|
|
|
|
- **Tier 1 (Auto-fix):** Formatting, spacing, markdown syntax
|
|
- **Tier 2 (Guided fix):** Missing sections, incomplete examples, unclear descriptions
|
|
- **Tier 3 (Complex):** Structural problems, fundamental clarity issues, major rewrites
|
|
|
|
## Pass Criteria
|
|
|
|
Content PASSES if:
|
|
|
|
- At least 4 of 5 quality dimensions pass
|
|
- No Tier 3 (complex) issues found
|
|
- Critical sections (description, purpose, examples) are adequate
|
|
|
|
Content FAILS if:
|
|
|
|
- 2 or more quality dimensions fail
|
|
- Any Tier 3 (complex) issues found
|
|
- Critical sections are missing or fundamentally flawed
|
|
|
|
## Examples
|
|
|
|
**High-quality skill:**
|
|
|
|
```bash
|
|
/meta-claude:skill:review-content @plugins/meta/meta-claude/skills/skill-creator
|
|
# Output: Content Quality Review: PASS
|
|
# - All quality dimensions passed
|
|
# - Clear structure with progressive disclosure
|
|
# - Comprehensive examples and actionable guidance
|
|
```
|
|
|
|
**Skill needing improvement:**
|
|
|
|
```bash
|
|
/meta-claude:skill:review-content @/path/to/draft-skill
|
|
# Output: Content Quality Review: FAIL
|
|
#
|
|
# Issues Found:
|
|
# Tier 2:
|
|
# - Add examples for error handling workflow
|
|
# - Clarify success criteria for validation step
|
|
# Tier 3:
|
|
# - Restructure content for better progressive disclosure
|
|
# - Description too broad, needs refinement for triggering
|
|
```
|
|
|
|
## Notes
|
|
|
|
- This review focuses on **content quality**, not technical compliance
|
|
- Technical validation (frontmatter, naming) is handled by `/meta-claude:skill:review-compliance`
|
|
- Be constructive: highlight strengths and provide actionable suggestions
|
|
- Content quality is subjective: use judgment and consider the skill's purpose
|
|
- Focus on whether Claude can effectively use the skill, not perfection
|