skill-review
Audit claude-skills repository documentation with systematic 9-phase review: standards compliance, official docs verification via Context7/WebFetch, code examples accuracy, cross-file consistency, and version drift detection. Auto-fixes unambiguous issues with severity classification.Use when: investigating skill issues, major package updates detected (e.g., v1.x → v2.x), skill not verified >90 days, before marketplace submission, or troubleshooting outdated API patterns, contradictory examples, broken links, version drift.
When & Why to Use This Skill
The Skill Review skill is a comprehensive auditing tool designed to maintain the integrity and quality of Claude skill repositories. It performs a systematic 9-phase review process that includes standards compliance checks, official documentation verification via WebFetch, and rigorous code example accuracy testing. By detecting version drift and auto-fixing unambiguous issues with severity classification, it ensures that agentic skills remain functional, up-to-date, and fully compliant with official API patterns, making it an essential tool for developers preparing skills for production or marketplace submission.
Use Cases
- Marketplace Submission Readiness: Perform a full 9-phase audit to ensure a skill meets all documentation standards and functional requirements before public release.
- Version Drift & Dependency Management: Automatically detect when major package updates (e.g., v1.x to v2.x) break existing code examples and verify them against live official documentation.
- Automated Quality Assurance: Identify and auto-fix critical issues such as non-existent API imports, invalid configurations, or broken links within the repository.
- Cross-File Consistency Checks: Ensure that SKILL.md, README.md, and bundled resources remain synchronized and free of contradictory instructions or outdated patterns.
- Troubleshooting Stale Skills: Investigate and resolve issues in skills that haven't been verified for over 90 days by cross-referencing current npm versions and production repository evidence.
| name | skill-review |
|---|---|
| description | | |
| Audit claude-skills repository documentation with systematic 9-phase review | standards compliance, official docs verification via Context7/WebFetch, code examples accuracy, cross-file consistency, and version drift detection. Auto-fixes unambiguous issues with severity classification. |
| Use when | investigating skill issues, major package updates detected (e.g., v1.x → v2.x), skill not verified >90 days, before marketplace submission, or troubleshooting outdated API patterns, contradictory examples, broken links, version drift. |
Skill Review Skill
Process
Invoke: /review-skill <skill-name> or use this skill when detecting outdated patterns
Production evidence: better-auth audit (2025-11-08) - found 6 critical issues including non-existent API imports, removed 665 lines incorrect code, implemented v2.0.0
9-Phase Audit
- Pre-Review: Install skill, check version/date, test discovery
- Standards: Validate YAML, keywords, third-person style, directory structure
- Official Docs: WebFetch/Context7 verify API patterns, GitHub updates, npm versions, production repos
- Code Examples: Verify imports exist, API signatures match, schema consistency, templates work
- Cross-File Consistency: Compare SKILL.md vs README.md, bundled resources match files
- Dependencies: Run
./scripts/check-versions.sh, check breaking changes, verify "Last Verified" - Categorize: Severity (🔴 Critical / 🟡 High / 🟠 Medium / 🟢 Low) with evidence (GitHub/docs/npm)
- Fix: Auto-fix unambiguous, ask user for architectural, update all files, bump version
- Verify: Test discovery, templates work, no contradictions, commit with changelog
Automated (via ./scripts/review-skill.sh): YAML syntax, package versions, broken links, TODOs, file org, staleness
Manual (AI): API methods vs docs, GitHub issues, production comparisons, code correctness, schema consistency
Severity Classification
🔴 CRITICAL: Non-existent API/imports, invalid config, missing dependencies
🟡 HIGH: Contradictory examples, inconsistent patterns, outdated major versions
🟠 MEDIUM: Stale minors (>90d), missing docs sections, incomplete errors
🟢 LOW: Typos, formatting, missing optional metadata
Fix Decision
Auto-fix: Unambiguous (correct import from docs), clear evidence, no architectural impact
Ask user: Multiple valid approaches, breaking changes, architectural choices
Version Bumps
- Major (v1→v2): API patterns change
- Minor (v1.0→v1.1): New features, backward compatible
- Patch (v1.0.0→v1.0.1): Bug fixes only
Example: better-auth Audit (2025-11-08)
🔴 CRITICAL #1: Non-existent d1Adapter import from 'better-auth/adapters/d1'
- Evidence: Official docs show drizzleAdapter, GitHub has no d1Adapter export, 4 production repos use Drizzle/Kysely
- Fix: Replaced with
drizzleAdapterfrom'better-auth/adapters/drizzle'
Result: 3 files deleted (obsolete), 3 created (correct patterns), +1,266 lines, v1.0→v2.0, 3.5 hours
Issues Prevented (10)
- Fake API adapters - Non-existent imports
- Stale API methods - Changed signatures
- Schema inconsistency - Different table names
- Outdated scripts - Deprecated approaches
- Version drift - Packages >90 days old
- Contradictory examples - Multiple conflicting patterns
- Broken links - 404 URLs
- YAML errors - Invalid frontmatter
- Missing keywords - Poor discoverability
- Incomplete bundled resources - Listed files don't exist
Bundled Resources
Planning: planning/SKILL_REVIEW_PROCESS.md (complete 9-phase guide)
Scripts: scripts/review-skill.sh (automated validation)
Commands: .claude/commands/review-skill.md (slash command)
Last Verified: 2025-11-28 | Version: 1.0.0