Skill Review Content

Review content quality (clarity, completeness, usefulness) of a skill's SKILL.md file.

Usage

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

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

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:

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

/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