Initial commit
This commit is contained in:
Zhongwei Li
254
commands/skill/review-content.md
Normal file
254
commands/skill/review-content.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user