Audit the quality and compatibility of Claude Code skills. As the orchestrator, delegate structural/quality checks to existing tools, while focusing on the compatibility audit itself.
Prerequisites
| Tool | Type | Required | Install |
|---|---|---|---|
| skill-creator | skill | Yes | Built-in on most AI coding agents (Claude Code, Cursor, etc.) |
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: Structural Validation (Delegated)
Run the validation script bundled with skill-reviewer, and summarize the results for YAML frontmatter, name format, description format, etc.:
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: name (hyphen-case, ≤64 characters), description (no angle brackets, ≤1024 characters).
Step 2: Content Quality (Delegated)
MUST execute: invoke the skill-creator skill to perform an in-depth quality review (token efficiency, progressive disclosure, anti-patterns, description benchmark testing, etc.).
If skill-creator is unavailable,MUST stop and guide the user to confirm, and must not skip it. Most AI coding agents have skill-creator built in:
- Claude Code:
document-skills:skill-creatororskill-creator:skill-creator - Other agents: check the corresponding skill management feature
This step cannot be skipped. An audit without skill-creator is incomplete.
Step 3: Compatibility Audit (Own Core)
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 (macOS-only commands, Windows incompatibilities, etc.).
3b. Cross-Agent Compatibility — Detect Claude Code-specific tool references and MCP dependencies.
3c. npx skills Ecosystem Compatibility — Validate marketplace.json registration, symlink availability, and cross-skill dependencies.
3d. Tool Reference Conventions — Check whether Claude Code tool terminology is preserved and fallback notes for other environments are provided. See the "Tool Reference Best Practices" section of the checklist for details.
3e. Prerequisites Declaration — Check whether SKILL.md declares external dependencies:
- If the skill uses external CLI tools (
git,gh,reminders-cli, etc.), MCP servers, or other skills, it MUST have a## Prerequisitessection - Prerequisites must be the first
##section in the body - The section MUST contain a 4-column table: Tool / Type / Required / Install
- The Type column MUST use standard values:
cli,mcp,skill,system - After the table, there MUST be a passive check note (blockquote) that explicitly requires directly guiding the user to complete installation and configuration when execution fails, rather than pointing to external documentation
- Tools that require configuration (such as MCP servers, CLIs requiring auth) SHOULD provide executable installation commands and configuration steps in the Install column, or reference documentation in the skill's bundled references/
- Skills without external dependencies do not need this section
See references/compatibility-checklist.md。
Step 4: Output Report
Output a unified report using the following format:
## Skill Review: {skill-name}
### 总览
| 维度 | 状态 | 方式 |
|------|------|------|
| 结构与元数据 | PASS / FAIL | validate.sh |
| 内容质量 | PASS / FAIL (N issues) | skill-creator |
| 平台兼容性 | PASS / FAIL (N issues) | 自查 |
| Agent 兼容性 | PASS / FAIL (N issues) | 自查 |
| npx skills 生态 | PASS / FAIL (N issues) | 自查 |
| Prerequisites 声明 | PASS / WARN / N/A | 自查 |
### Critical
- **[维度]** 问题描述
当前: ...
建议: ...
### High
...
### Medium / Low
...
Severity levels:
- Critical — Functionality unavailable or distribution failure, must be fixed
- High — Significantly affects the usable scope, recommended to fix
- Medium — Improvable item, does not affect core functionality
- Low — Suggestive improvement