Skill Review Skill

Overview

• 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

Quick Start

Invoke via Slash Command

/review-skill <skill-name>

/review-skill better-auth

Invoke via Skill (Proactive)

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

9-Phase Systematic Audit

1. Pre-Review Setup (5-10 min)
   • Install skill locally:

     ./scripts/install-skill.sh <skill-name>

   • Check current version and last verified date
   • Test skill discovery
2. Standards Compliance (10-15 min)
   • Validate YAML frontmatter (name, description, license)
   • Check keyword comprehensiveness
   • Verify third-person description style
   • Ensure directory structure matches spec
3. Official Documentation Verification (15-30 min)
   • Use Context7 MCP or WebFetch to verify API patterns
   • Check GitHub for recent updates and issues
   • Verify package versions against npm registry
   • Compare with production repositories
4. Code Examples & Templates Audit (20-40 min)
   • Verify import statements exist in current packages
   • Check API method signatures match official docs
   • Ensure schema consistency across files
   • Test templates build and run
5. Cross-File Consistency (15-25 min)
   • Compare SKILL.md vs README.md examples
   • Verify "Bundled Resources" section matches actual files
   • Ensure configuration examples consistent
6. Dependencies & Versions (10-15 min)
   • Run

     ./scripts/check-versions.sh <skill-name>

   • Check for breaking changes in package updates
   • Verify "Last Verified" date is recent
7. Issue Categorization (10-20 min)
   • Classify by severity: 🔴 Critical / 🟡 High / 🟠 Medium / 🟢 Low
   • Document with evidence (GitHub URL, docs link, npm changelog)
8. Fix Implementation (30 min - 4 hours)
   • Auto-fix unambiguous issues
   • Ask user only for architectural decisions
   • Update all affected files consistently
   • Bump version if breaking changes
9. Post-Fix Verification (10-15 min)
   • Test skill discovery
   • Verify templates work
   • Check no contradictions remain
   • Commit with detailed changelog

Automated Checks (via script)

./scripts/review-skill.sh <skill-name>

• ✅ YAML frontmatter syntax and required fields
• ✅ Package version currency (npm)
• ✅ Broken links (HTTP status)
• ✅ TODO markers in code
• ✅ File organization (expected directories exist)
• ✅ "Last Verified" date staleness

Manual Verification (AI-powered)

• 🔍 API method verification against official docs
• 🔍 GitHub activity and issue checks
• 🔍 Production repository comparisons
• 🔍 Code example correctness
• 🔍 Schema consistency validation

Process Workflow

Step 1: Run Automated Checks

./scripts/review-skill.sh <skill-name>

Step 2: Execute Manual Verification

1. Use Context7 MCP (if available):

   Use Context7 to fetch: /websites/<package-docs>
   Search for: [API method from skill]

2. Or use WebFetch:

   Fetch: https://<official-docs-url>
   Verify: [specific patterns]

3. Check GitHub:

   Visit: https://github.com/<org>/<repo>/commits/main
   Check: Last commit, recent changes
   Search issues: [keywords from skill]

4. Find production examples:

   WebSearch: "<package> cloudflare production github"
   Compare: Do real projects match our patterns?

• Verify all imports exist (check official docs)
• Check API method signatures match
• Ensure schema consistency across files
• Test templates actually work

Step 3: Categorize Issues

• Non-existent API methods/imports
• Invalid configuration
• Missing required dependencies

• Contradictory examples across files
• Inconsistent patterns
• Outdated major versions

• Stale minor versions (>90 days)
• Missing documentation sections
• Incomplete error lists

• Typos, formatting inconsistencies
• Missing optional metadata

Step 4: Fix Issues

• ✅ Fix is unambiguous (correct import from docs)
• ✅ Evidence is clear
• ✅ No architectural impact

• ❓ Multiple valid approaches
• ❓ Breaking change decision
• ❓ Architectural choice

I found [issue]. There are [N] approaches:

1. [Approach A] - [Pros/Cons]
2. [Approach B] - [Pros/Cons]

Recommendation: [Default based on evidence]

Which would you prefer?

Step 5: Version Bump Assessment

• Major: v1.0.0 → v2.0.0 (API patterns change)
• Minor: v1.0.0 → v1.1.0 (new features, backward compatible)
• Patch: v1.0.0 → v1.0.1 (bug fixes only)

Step 6: Generate Audit Report

## Skill Review Report: <skill-name>

**Date**: YYYY-MM-DD
**Trigger**: [Why review performed]
**Time Spent**: [Duration]

### Findings

🔴 CRITICAL (N): [List with evidence]
🟡 HIGH (N): [List with evidence]
🟠 MEDIUM (N): [List with evidence]
🟢 LOW (N): [List with evidence]

### Remediation

**Files Modified**: [List]
**Version Update**: [old] → [new]
**Breaking Changes**: Yes/No

### Verification

✅ Discovery test passed
✅ Templates work
✅ Committed: [hash]

### Recommendation

[Final assessment]

Example: better-auth Audit

Findings

references/cloudflare-worker-example.ts:17

d1Adapter

'better-auth/adapters/d1'

• Official docs: https://better-auth.com/docs/integrations/drizzle
• GitHub: No

  d1Adapter

  export in codebase
• Production: 4 repos use Drizzle/Kysely

drizzleAdapter

'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

1. planning/SKILL_REVIEW_PROCESS.md

   - Complete 9-phase manual guide

2. scripts/review-skill.sh

   - Automated validation script

3. .claude/commands/review-skill.md

   - Slash command definition

When Claude Should Invoke This Skill

• User mentions skill seems outdated
• Package major version mentioned
• User reports errors following skill
• Checking metadata shows >90 days since verification

• "review the X skill"
• "audit better-auth skill"
• "is cloudflare-worker-base up to date?"
• "check if tailwind-v4-shadcn needs updating"

Token Efficiency

• Trial-and-error verification
• Repeated doc lookups
• Inconsistent fixes across files
• Missing evidence citations

• Systematic process
• Clear decision trees
• Evidence-based fixes
• Comprehensive audit trail

Common Issues Prevented

1. Fake API adapters - Non-existent imports
2. Stale API methods - Changed signatures
3. Schema inconsistency - Different table names
4. Outdated scripts - Deprecated approaches
5. Version drift - Packages >90 days old
6. Contradictory examples - Multiple conflicting patterns
7. Broken links - 404 documentation URLs
8. YAML errors - Invalid frontmatter syntax
9. Missing keywords - Poor discoverability
10. Incomplete bundled resources - Listed files don't exist

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 9 phases
4. Fix consistency - Update all files, not just one
5. Document thoroughly - Detailed commit messages
6. Test after fixes - Verify skill still works

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

• 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/jezweb/claude-skills
• Example Audit: See process guide Appendix B (better-auth v2.0.0)