# skill-review > Comprehensive 15-phase skill audit for claude-skills repository. Use for skill updates, marketplace verification, package currency checks, or encountering standards compliance, dependency, API validation errors. - Author: Eddie - Repository: secondsky/claude-skills - Version: 20260118192629 - Stars: 63 - Forks: 0 - Last Updated: 2026-02-06 - Source: https://github.com/secondsky/claude-skills - Web: https://mule.run/skillshub/@@secondsky/claude-skills~skill-review:20260118192629 --- --- name: skill-review description: Comprehensive 15-phase skill audit for claude-skills repository. Use for skill updates, marketplace verification, package currency checks, or encountering standards compliance, dependency, API validation errors. license: MIT metadata: version: 1.4.0 last_verified: 2025-12-14 production_tested: better-auth v2.0.0 audit (2025-11-08) token_savings: ~80% errors_prevented: 40+ official_docs: https://github.com/secondsky/claude-skills triggers: - "review this skill" - "review the X skill" - "audit the skill" - "check if X needs updates" - "is X skill current" - "verify X documentation" - "X skill seems outdated" allowed-tools: - Read - Bash - Glob - Grep - WebFetch - WebSearch - Edit - Write --- # Skill Review Skill ## Overview The skill-review skill provides a comprehensive, systematic process for auditing skills in the claude-skills repository. It combines automated technical validation with AI-powered verification to ensure skills remain accurate, current, and high-quality. **Use this skill when**: - Investigating suspected issues in a skill - Major package version updates released (e.g., better-auth 1.x → 2.x) - Skill last verified >90 days ago - Before submitting skill to marketplace - User reports errors following skill instructions - Examples seem outdated or contradictory **Production evidence**: Successfully audited better-auth skill (2025-11-08), found 6 critical/high issues including non-existent API imports, removed 665 lines of incorrect code, implemented v2.0.0 with correct patterns. --- ## Quick Start ### Invoke via Slash Command ``` /review-skill ``` **Example**: ``` /review-skill better-auth ``` ### Invoke via Skill (Proactive) When Claude notices potential issues, it can suggest: ``` User: "I'm having trouble with better-auth and D1" Claude: "I notice the better-auth skill was last verified 6 months ago. Would you like me to review it? Better-auth recently released v1.3 with D1 changes." ``` --- ## What This Skill Does **For complete audit methodology**: Load `references/audit-methodology.md` when performing skill audits - includes detailed descriptions of all 15 phases, official Claude best practices enforced, error prevention catalog, verification methods, and production testing evidence. **15-Phase Systematic Audit Overview:** 1. **Pre-Review Setup** - Install skill, test discovery, check version 2. **Standards Compliance** - YAML frontmatter validation, line count check, third-person style 3. **Official Docs Verification** - Context7 MCP / WebFetch API validation, GitHub checks, npm registry 4. **Code Examples Audit** - Import statements, API signatures, schema consistency, template testing 5. **Cross-File Consistency** - SKILL.md vs README vs references alignment 6. **Dependencies & Versions** - Package currency checks, breaking changes detection 7. **Progressive Disclosure Review** - Reference depth (ONE level), TOC presence, 3-tier model compliance 8. **Conciseness Audit** - Over-explained concepts, verbosity assessment, degrees of freedom 9. **Anti-Pattern Detection** - Windows paths, inconsistent terminology, time-sensitive info, nested references 10. **Testing & Evaluation** - Test scenarios (minimum 3), multi-model consideration, real problem validation 11. **Security & MCP** - External URLs, MCP tool qualification, error handling, script permissions 12. **Issue Categorization** - Severity classification (🔴 Critical / 🟡 High / 🟠 Medium / 🟢 Low) with evidence 12.5. **Resource Inventory** ⚠️ MANDATORY - Inventory existing references, read all files, create coverage matrix BEFORE condensation 13. **Fix Implementation** - Auto-fix unambiguous issues, ask user for architectural decisions 14. **Post-Fix Verification** - Discovery test, template validation, consistency check, commit **Automated Checks** (`./scripts/review-skill.sh`): - ✅ YAML syntax, package versions, broken links, TODO markers, file organization, date staleness **Manual Verification** (AI-powered): - 🔍 API method validation, GitHub activity, production comparisons, code correctness, schema consistency --- ## Process Workflow **For complete workflow guide**: Load `references/audit-methodology.md` for detailed verification methods and `references/audit-report-template.md` for full report structure. **High-Level Workflow:** 1. **Run Automated Checks** - Execute `./scripts/review-skill.sh ` for technical validation 2. **Execute Manual Verification** - Use Context7 MCP / WebFetch for API validation, GitHub checks, production comparisons 3. **Categorize Issues** - Classify by severity (🔴 Critical / 🟡 High / 🟠 Medium / 🟢 Low) with evidence 4. **Fix Issues** - Auto-fix unambiguous issues, ask user for architectural decisions 5. **Version Bump** - Major (breaking) / Minor (features) / Patch (bugs) 6. **Generate Report** - Document findings, remediation, verification, recommendations --- ## Example: better-auth Audit ### Findings **Issue #1: Non-existent d1Adapter** 🔴 CRITICAL *Location*: `references/cloudflare-worker-example.ts:17` *Problem*: Imports `d1Adapter` from `'better-auth/adapters/d1'` which doesn't exist *Evidence*: - Official docs: https://better-auth.com/docs/integrations/drizzle - GitHub: No `d1Adapter` export in codebase - Production: 4 repos use Drizzle/Kysely *Fix*: Replace with `drizzleAdapter` from `'better-auth/adapters/drizzle'` ### Result - **Files deleted**: 3 (obsolete patterns) - **Files created**: 3 (correct patterns) - **Lines changed**: +1,266 net - **Version**: v1.0.0 → v2.0.0 - **Time**: 3.5 hours --- ## Bundled Resources This skill references: 1. **`planning/SKILL_REVIEW_PROCESS.md`** - Complete 14-phase manual guide 2. **`scripts/review-skill.sh`** - Automated validation script 3. **`.claude/commands/review-skill.md`** - Slash command definition 4. **`references/multi-skill-tracking.md`** - Template for tracking multiple concurrent skill reviews Load when: User asks to review 2+ skills simultaneously or wants progress tracking --- ## When to Load References Load reference files when working on specific aspects of skill audits: ### audit-methodology.md Load when: - **Process-based**: Need detailed description of all 15 audit phases (Pre-review Setup, Standards Compliance, Official Docs Verification, Code Examples Audit, Cross-File Consistency, Dependencies & Versions, Progressive Disclosure Review, Conciseness Audit, Anti-Pattern Detection, Testing & Evaluation, Security & MCP, Issue Categorization, Resource Inventory, Fix Implementation, Post-Fix Verification) - **Standards-based**: Verifying YAML frontmatter standards (name 64 chars, description 1024 chars), SKILL.md file standards (<500 lines), code quality standards, reference file standards - **Error-based**: Need complete error prevention catalog covering documentation issues (SKILL.md too long, YAML errors, version drift, schema inconsistency, Windows paths), technical issues (fake API adapters, non-existent imports, outdated dependencies), structure issues (duplicate extraction, skipping resource inventory, deeply nested references, second-person descriptions) - **Verification-based**: Understanding automated technical checks (YAML syntax, package versions, broken links, TODO markers, file organization, date staleness), AI-powered verification methods (API validation, GitHub checks, production comparisons, code correctness), output format (severity classification) - **Example-based**: Need production testing evidence (better-auth v2.0.0 audit with 6 critical/high issues, 665 lines removed, 1931 lines added) ### audit-report-template.md Load when: - **Reporting-based**: Need to document skill audit findings in standardized format - **Template-based**: Need complete report structure (executive summary, quick validation checks, progressive disclosure score, conciseness rating, anti-pattern detection, testing & evaluation review, security & MCP review, detailed findings, remediation summary, version update, post-fix verification, lessons learned, recommendations, appendix) - **Checklist-based**: Need specific validation checklists (7 quick validation checks: name length/format, reserved words, description length/XML, SKILL.md lines, third-person style; 8 anti-pattern checks; post-fix verification steps) - **Severity-based**: Need to categorize findings by severity (🔴 Critical / 🟡 High / 🟠 Medium / 🟢 Low) with detailed evidence citations ### multi-skill-tracking.md Load when: - **Batch-based**: Reviewing 2+ skills simultaneously and need centralized progress tracking across multiple skills - **Tracking-based**: Need to monitor progress across multiple skills, identify bottlenecks in audit workflow, ensure completeness across all 15 phases, document timestamps for each phase, prioritize work across skills, track blockers - **Template-based**: Need tracking document structure (quick status overview table, detailed phase tracking per skill with all 15 phases, issues found by severity, batch summary statistics, active blockers, lessons learned, recommendations) - **Workflow-based**: Need guidance on creating tracking doc, initializing skill entries, updating frequently during audits, referencing in commits - **Status-based**: Need status indicators (⏳ Pending, 🔄 In Progress, ✅ Complete, ⚠️ Blocked, ❌ Skipped) --- ## When Claude Should Invoke This Skill **Proactive triggers**: - User mentions skill seems outdated - Package major version mentioned - User reports errors following skill - Checking metadata shows >90 days since verification **Explicit triggers**: - "review the X skill" - "audit better-auth skill" - "is cloudflare-worker-base up to date?" - "check if tailwind-v4-shadcn needs updating" --- ## Token Efficiency **Without this skill**: ~25,000 tokens - Trial-and-error verification - Repeated doc lookups - Inconsistent fixes across files - Missing evidence citations **With this skill**: ~5,000 tokens - Systematic process - Clear decision trees - Evidence-based fixes - Comprehensive audit trail **Savings**: ~80% (20,000 tokens) --- ## Common Issues Prevented **For complete error catalog**: Load `references/audit-methodology.md` for all 36+ documented issues with detailed prevention strategies. **Top 10 Most Common Issues:** 1. **Fake API adapters** - Non-existent imports (prevents broken code examples) 2. **SKILL.md too long** - Body exceeds 500 lines (performance impact) 3. **Duplicate extraction** - Creating reference files for content that already exists 4. **Skipping resource inventory** - Starting condensation without Phase 12.5 5. **YAML errors** - Invalid frontmatter syntax (prevents skill from loading) 6. **Version drift** - Packages >90 days old (stale documentation) 7. **Schema inconsistency** - Different patterns across files (user confusion) 8. **Windows-style paths** - Backslashes instead of forward slashes 9. **Deeply nested references** - More than one level deep from SKILL.md 10. **Second-person descriptions** - "You should..." instead of "This skill should be used when..." 11. **Verbose descriptions** - >200 chars contributing to 15k total budget exhaustion across all skills --- ## Best Practices 1. **Always cite sources** - GitHub URL, docs link, npm changelog 2. **No assumptions** - Verify against current official docs 3. **Be systematic** - Follow all 15 phases (including Phase 12.5) 4. **Inventory before condensation** - Always complete Phase 12.5 before fixing 5. **Fix consistency** - Update all files, not just one 6. **Document thoroughly** - Detailed commit messages 7. **Test after fixes** - Verify skill still works 8. **Keep descriptions concise** - Aim for <100 chars to avoid system prompt budget issues --- ## Known Limitations - Link checking requires network access - Package version checks need npm installed - Context7 MCP availability varies by package - Production repo search may need GitHub API - Manual phases require human judgment --- ## Version History **v1.4.0** (2025-12-14) - CRITICAL: Added Phase 12.5 "Resource Inventory & Coverage Audit" (MANDATORY before condensation) - Added mandatory verification checklist before any condensation work - Expanded anti-patterns with 5 new duplication prevention rules - Added 6 new best practices for resource inventory workflow - Added coverage matrix template for tracking existing vs needed references - Errors prevented: 40+ (was 36+) New errors prevented: - Duplicate extraction (content already in references) - Skipping resource inventory phase - Coverage matrix omitted - Listing without reading reference files - Unnecessary file creation **v1.3.0** (2025-11-25) - Added anti-patterns section to Phase 13 (Fix Implementation) with explicit DO/DON'T guidance - Created multi-skill tracking template (`references/multi-skill-tracking.md`) for batch reviews - Added 5 critical anti-patterns to prevent destructive refactoring workflows - Errors prevented: 36+ (was 31+) **v1.2.0** (2025-11-16) - Added marketplace schema compliance check (no custom fields like lastVerified) - Errors prevented: 31+ (was 30+) **v1.1.0** (2025-11-16) - Enhanced with official Claude best practices documentation - 14-phase systematic audit process (was 9-phase) - Added exact YAML validation rules (name: 64 chars, description: 1024 chars) - Added SKILL.md line count check (<500 lines) - Added progressive disclosure architecture review - Added conciseness & degrees of freedom audit - Added anti-pattern detection (Windows paths, inconsistent terminology) - Added testing & evaluation review (multi-model, 3+ test scenarios) - Added security & MCP considerations **v1.0.0** (2025-11-08) - Initial release - 9-phase systematic audit process - Automated script + manual guide - Slash command + skill wrapper - Production-tested on better-auth v2.0.0 audit --- ## Additional Resources - **Full Process Guide**: `planning/SKILL_REVIEW_PROCESS.md` - **Repository**: https://github.com/secondsky/claude-skills - **Example Audit**: See process guide Appendix B (better-auth v2.0.0) --- **Last verified**: 2025-12-14 | **Version**: 1.4.0