Skill Reviewer
Audit the quality and compatibility of Claude Code skills. As an orchestrator, it delegates existing tools to handle structure/quality checks, while focusing on compatibility audits itself.
Prerequisites
| Tool | Type | Required | Install |
|---|
| writing-skills | skill | No | npx skills add https://github.com/obra/superpowers --skill writing-skills
|
Do NOT proactively verify these tools on skill load. If a command fails due to a missing tool, directly guide the user through installation and configuration step by step.
Audit Process
Step 1: Structure Validation (Delegated)
Run the built-in validation script of skill-reviewer to compile results for YAML frontmatter, name format, description format, etc.:
bash
bash <skill-reviewer-dir>/scripts/validate.sh
If the script is unavailable (e.g., not installed via npx skills), manually check the YAML frontmatter of each SKILL.md file: name (hyphen-case, ≤64 characters), description (no angle brackets, ≤1024 characters).
Step 2: Content Quality (Delegated, Recommended)
Recommended Execution: If
is installed, invoke this skill for in-depth quality review (covering token efficiency, progressive disclosure, anti-patterns, TDD methodology, etc.).
If not installed, prompt the user to optionally install it using:
bash
npx skills add https://github.com/obra/superpowers --skill writing-skills
If this step is skipped, clearly inform the user to avoid silent omission.
Step 3: Compatibility Audit (Core Function)
Check all files of the target skill (SKILL.md + scripts/ + references/) item by item according to
references/compatibility-checklist.md
:
3a. Cross-Platform Compatibility — Scan for platform-locked patterns (e.g., macOS-only commands, Windows incompatibilities, etc.).
3b. Cross-Agent Compatibility — Detect references to Claude Code-exclusive tools and MCP dependencies.
3c. npx Skills Ecosystem Compatibility — Validate marketplace.json registration, symlink availability, and cross-skill dependencies.
3d. Tool Reference Standards — Check if Claude Code tool terminology is retained and fallback notes for other environments are provided. Refer to the "Tool Reference Best Practices" section in the checklist for details.
3e. Prerequisites Declaration — Check if SKILL.md declares external dependencies:
- If the skill uses external CLI tools (e.g., , , ), MCP servers, or other skills, it MUST include a section
- The Prerequisites section MUST be the first section in the body
- The section MUST include a 4-column table: Tool / Type / Required / Install
- The Type column MUST use standard values: , , ,
- A passive check note (blockquote) MUST follow the table, clearly stating that if execution fails, the user should be guided through installation and configuration step by step instead of directing them to external documentation
- For tools that require configuration (e.g., MCP servers, CLI tools requiring auth), the Install column SHOULD provide executable installation commands and configuration steps, or reference the documentation in the skill's built-in references/ directory
- Skills with no external dependencies do not need this section
For details, see
references/compatibility-checklist.md
.
Step 4: Output Report
Output a unified report using the following format:
markdown
## Skill Review: {skill-name}
### Overview
|------|------|------|
| Structure & Metadata | PASS / FAIL | validate.sh |
| Content Quality | Recommended to use writing-skills | Delegated |
| Platform Compatibility | PASS / FAIL (N issues) | Self-checked |
| Agent Compatibility | PASS / FAIL (N issues) | Self-checked |
| npx Skills Ecosystem | PASS / FAIL (N issues) | Self-checked |
| Prerequisites Declaration | PASS / WARN / N/A | Self-checked |
### Critical
- **[Dimension]** Issue description
Current: ...
Recommendation: ...
### High
...
### Medium / Low
...
Severity Levels:
- Critical — Functionality is unavailable or distribution fails; must be fixed
- High — Significantly affects usability scope; recommended to fix
- Medium — Improvement item; does not affect core functionality
- Low — Suggested improvement