Skill Review

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

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)

The skill runs ./scripts/review-skill.sh <skill-name> which checks:

• ✅ 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)

Claude performs:

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

Interpret output to identify technical issues.

Step 2: Execute Manual Verification

For Phase 3: Official Documentation 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?

For Phase 4: Code Examples Audit:

• 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

🔴 CRITICAL - Breaks functionality:

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

🟡 HIGH - Causes confusion:

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

🟠 MEDIUM - Reduces quality:

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

🟢 LOW - Polish issues:

• Typos, formatting inconsistencies
• Missing optional metadata

Step 4: Fix Issues

Auto-fix when:

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

Ask user when:

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

Format for questions:

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

If breaking changes:

• 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

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

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

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

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

---

Last verified: 2025-11-08 | Version: 1.0.0

Skill Review Skill

Comprehensive deep-dive documentation review for claude-skills repository.

Version: 1.0.0 | Last Verified: 2025-11-08

---

Quick Example

User: "Review the better-auth skill"

Claude (invokes skill-review): 1. Runs automated checks (./scripts/review-skill.sh) 2. Verifies against official docs (Context7/WebFetch) 3. Finds 6 issue categories (2 critical, 3 high, 1 medium) 4. Fixes automatically where clear 5. Reports findings with evidence citations

Result: better-auth v2.0.0 with correct D1 patterns

---

What It Does

Automated Checks ✅

• YAML frontmatter validity (syntax, required fields)
• Package version currency (vs npm registry)
• Broken links (HTTP status codes)
• TODO markers in code
• File organization (expected directories exist)
• "Last Verified" date staleness (>90 days)

Manual Verification 🔍

• API method correctness (vs official docs)
• GitHub maintenance status (commits, issues)
• Production repository patterns (real usage)
• Code example accuracy (imports, signatures)
• Schema consistency across files

Issue Classification 🎯

• 🔴 CRITICAL: Breaks functionality (fake imports, invalid config)
• 🟡 HIGH: Causes confusion (contradictory examples, outdated major versions)
• 🟠 MEDIUM: Reduces quality (stale versions, missing sections)
• 🟢 LOW: Polish issues (typos, formatting)

---

Usage

Slash Command (Explicit)

/review-skill <skill-name>

Examples:

• /review-skill better-auth
• /review-skill cloudflare-worker-base

Skill Invocation (Proactive)

Claude can suggest reviews when it notices:

• "X skill seems outdated"
• "Package Y just released v2.0"
• "Skill last verified 6 months ago"

Trigger phrases:

• "review this skill"
• "audit the better-auth skill"
• "check if cloudflare-worker-base needs updates"
• "is tailwind-v4-shadcn current?"

---

Installation

./scripts/install-skill.sh skill-review

Verify:

ls ~/.claude/skills/skill-review

---

9-Phase Process

1. Pre-Review Setup - Install, version check, discovery test 2. Standards Compliance - YAML, keywords, description 3. Official Docs Verification - Context7, GitHub, npm 4. Code Examples Audit - Imports, APIs, schemas 5. Cross-File Consistency - SKILL.md vs README vs references 6. Dependencies & Versions - Currency, breaking changes 7. Issue Categorization - Severity classification 8. Fix Implementation - Auto-fix or ask user 9. Post-Fix Verification - Test, commit

Detailed guide: planning/SKILL_REVIEW_PROCESS.md

---

Output Example

═══════════════════════════════════════════════
  SKILL REVIEW REPORT: better-auth
═══════════════════════════════════════════════

🔴 CRITICAL (2):
  - Non-existent API: d1Adapter (line 17)
  - Schema inconsistency: users vs user tables

🟡 HIGH (3):
  - Package outdated: v1.2.0 → v1.3.34
  - Contradictory examples in 3 files
  - Setup script uses deprecated pattern

🟠 MEDIUM (1):
  - Last verified 85 days ago

═══════════════════════════════════════════════
RECOMMENDATION: Comprehensive review required
Estimated effort: 3-4 hours
Breaking changes: Yes (v2.0.0 bump)
═══════════════════════════════════════════════

---

When to Use

Required

• Major package version updates (e.g., better-auth 1.x → 2.x)
• User reports errors following skill
• Before marketplace submission

Recommended

• Skill last verified >90 days ago
• After framework breaking changes
• When adding new features to skill
• Quarterly maintenance

On-Demand

• Suspected issues
• Investigating user feedback
• Quality assurance before release

---

Auto-Trigger Keywords

Claude recognizes these phrases and may suggest review:

• "review this skill"
• "review the X skill"
• "audit [skill-name]"
• "check if X needs updates"
• "is X skill current?"
• "verify X documentation"
• "X skill seems outdated"

---

Example Audit: better-auth v2.0.0

Trigger: User reported D1 integration issues

Findings:

• 6 issues found (2 critical, 3 high, 1 medium)
• Main problem: Documented fake d1Adapter() API
• Required: Complete refactor with v2.0.0 bump

Remediation:

• Deleted: 3 files (665 lines of incorrect code)
• Created: 3 files (correct Drizzle/Kysely patterns)
• Updated: 2 files (SKILL.md, README.md)
• Lines changed: +1,266 net

Time: 3.5 hours

Result: Skill upgraded with correct patterns, all users unblocked

Evidence:

• GitHub: https://github.com/better-auth/better-auth
• Docs: https://better-auth.com/docs/integrations/drizzle
• Production: 4 repos verified using Drizzle/Kysely

---

Token Efficiency

Without skill: ~25,000 tokens

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

With skill: ~5,000 tokens

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

Savings: ~80% (20,000 tokens)

---

Common Issues Prevented

---

Scripts & Commands

Review script (automated checks):

./scripts/review-skill.sh <skill-name>
./scripts/review-skill.sh <skill-name> --quick  # Fast check

Slash command (full process):

/review-skill <skill-name>

Skill invocation (proactive):

"Review the better-auth skill"

---

Resources

Full Process Guide: planning/SKILL_REVIEW_PROCESS.md (~3,500 words)

Slash Command: .claude/commands/review-skill.md

Review Script: scripts/review-skill.sh

Repository: https://github.com/jezweb/claude-skills

Example Audit: See process guide Appendix B

---

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

---

Contributing

Found an issue with the review process? Suggestions for improvement?

1. Open issue: https://github.com/jezweb/claude-skills/issues 2. Describe: What phase could be improved? 3. Provide: Example where current process fell short

---

Version History

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

---

License

MIT License - See LICENSE file in repository root

---

Maintained by: claude-skills project Last verified: 2025-11-08 Production status: ✅ Tested (better-auth v2.0.0)

Skill Review Audit Report Template

Use this template to document skill audit findings.

---

Skill Review Report: [SKILL-NAME]

Date: YYYY-MM-DD Audit Type: Deep review / Quick check Trigger: [Why review was performed] Time Spent: [Duration] Auditor: Claude (Sonnet 4.5) / Human

---

Executive Summary

Status: ✅ PASS / ⚠️ WARN / ❌ FAIL

Findings:

• 🔴 Critical: [N] issues
• 🟡 High: [N] issues
• 🟠 Medium: [N] issues
• 🟢 Low: [N] issues

Action Required: [None / Minor fixes / Comprehensive refactor]

Version Bump: [None / Patch / Minor / Major]

---

Detailed Findings

Issue #1: [Short Description]

Severity: 🔴 CRITICAL / 🟡 HIGH / 🟠 MEDIUM / 🟢 LOW

Location: file.ts:123 or SKILL.md section

Problem: [Clear description of what's wrong]

Evidence:

• Official docs: [URL]
• GitHub issue: [URL] (if applicable)
• npm: npm view package version output
• Production example: [GitHub repo URL]

Impact: [What happens if not fixed]

Fix:

- old code
+ new code

Breaking Change: Yes / No

---

[Repeat for each issue]

---

Remediation Summary

Files Deleted ([N]):

• path/to/file.ts (reason)

Files Created ([N]):

• path/to/file.ts (purpose)

Files Modified ([N]):

• path/to/file.ts (changes)

Lines Changed:

• Removed: [N] lines
• Added: [N] lines
• Net: [±N] lines

---

Version Update

Version: [old] → [new]

Reason: [Breaking changes / New features / Bug fixes]

Migration Path: [If breaking changes, how to upgrade]

Changelog:

v[new] (YYYY-MM-DD)
[BREAKING if applicable]: [Summary]

Critical:
- [List critical fixes]

High:
- [List high-priority fixes]

Medium:
- [List medium fixes]

Low:
- [List low fixes]

Migration: [How to upgrade if breaking]

---

Post-Fix Verification

Discovery Test:

• ✅ / ❌ Skill recognized by Claude
• ✅ / ❌ Metadata loads correctly

Template Test (if applicable):

• ✅ / ❌ Templates build successfully
• ✅ / ❌ No TypeScript errors
• ✅ / ❌ Dependencies resolve

Consistency Check:

• ✅ / ❌ SKILL.md vs README.md match
• ✅ / ❌ No contradictions in references/
• ✅ / ❌ Bundled Resources list accurate

Code Quality:

• ✅ / ❌ No TODO markers
• ✅ / ❌ No broken links
• ✅ / ❌ All imports valid

Commit:

• Hash: [git hash]
• Pushed: ✅ / ❌

---

Lessons Learned

1. [Key takeaway #1] 2. [Key takeaway #2] 3. [Key takeaway #3]

---

Recommendations

Immediate:

• [Action items that must be done now]

Future:

• [Improvements for next review cycle]

Process:

• [Suggestions for improving review process]

---

Appendix

Automation Output (./scripts/review-skill.sh):

[Paste relevant script output]

Manual Verification Notes:

• [Additional observations]
• [Edge cases discovered]
• [Questions for maintainer]

---

Audit Complete: YYYY-MM-DD Result: [Summary of final state]