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 <skill-name>

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:

• Pre-Review Setup - Install skill, test discovery, check version

• Standards Compliance - YAML frontmatter validation, line count check, third-person style

• Official Docs Verification - Context7 MCP / WebFetch API validation, GitHub checks, npm registry

• Code Examples Audit - Import statements, API signatures, schema consistency, template testing

• Cross-File Consistency - SKILL.md vs README vs references alignment

• Dependencies & Versions - Package currency checks, breaking changes detection

• Progressive Disclosure Review - Reference depth (ONE level), TOC presence, 3-tier model compliance

• Conciseness Audit - Over-explained concepts, verbosity assessment, degrees of freedom

• Anti-Pattern Detection - Windows paths, inconsistent terminology, time-sensitive info, nested references

• Testing & Evaluation - Test scenarios (minimum 3), multi-model consideration, real problem validation

• Security & MCP - External URLs, MCP tool qualification, error handling, script permissions

• 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

• Fix Implementation - Auto-fix unambiguous issues, ask user for architectural decisions

• 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:

• Run Automated Checks - Execute ./scripts/review-skill.sh <skill-name> for technical validation

• Execute Manual Verification - Use Context7 MCP / WebFetch for API validation, GitHub checks, production comparisons

• Categorize Issues - Classify by severity (🔴 Critical / 🟡 High / 🟠 Medium / 🟢 Low) with evidence

• Fix Issues - Auto-fix unambiguous issues, ask user for architectural decisions

• Version Bump - Major (breaking) / Minor (features) / Patch (bugs)

• 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:

• planning/SKILL_REVIEW_PROCESS.md

• Complete 14-phase manual guide

• scripts/review-skill.sh

• Automated validation script

• .claude/commands/review-skill.md

• Slash command definition

• 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:

• Fake API adapters - Non-existent imports (prevents broken code examples)

• SKILL.md too long - Body exceeds 500 lines (performance impact)

• Duplicate extraction - Creating reference files for content that already exists

• Skipping resource inventory - Starting condensation without Phase 12.5

• YAML errors - Invalid frontmatter syntax (prevents skill from loading)

• Version drift - Packages >90 days old (stale documentation)

• Schema inconsistency - Different patterns across files (user confusion)

• Windows-style paths - Backslashes instead of forward slashes

• Deeply nested references - More than one level deep from SKILL.md

• Second-person descriptions - "You should..." instead of "This skill should be used when..."

• Verbose descriptions - >200 chars contributing to 15k total budget exhaustion across all skills

Best Practices

• Always cite sources - GitHub URL, docs link, npm changelog

• No assumptions - Verify against current official docs

• Be systematic - Follow all 15 phases (including Phase 12.5)

• Inventory before condensation - Always complete Phase 12.5 before fixing

• Fix consistency - Update all files, not just one

• Document thoroughly - Detailed commit messages

• Test after fixes - Verify skill still works

• 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