skill-review

Original source / Raw SKILL.md

---
name: skill-review
description: |
  Audit claude-skills with systematic 9-phase review: standards compliance, official docs verification, code accuracy, cross-file consistency, and version drift detection.

  Use when investigating skill issues, major updates detected, skill not verified >90 days, or before marketplace submission.
user-invocable: true
allowed-tools:
  - Read
  - Bash
  - Glob
  - Grep
  - WebFetch
  - WebSearch
  - Edit
  - Write
---

# 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

1. **Pre-Review**: Install skill, check version/date, test discovery
2. **Standards**: Validate YAML, keywords, third-person style, directory structure
3. **Official Docs**: WebFetch/Context7 verify API patterns, GitHub updates, npm versions, production repos
4. **Code Examples**: Verify imports exist, API signatures match, schema consistency, templates work
5. **Cross-File Consistency**: Compare SKILL.md vs README.md, bundled resources match files
6. **Dependencies**: Run `./scripts/check-versions.sh`, check breaking changes, verify "Last Verified"
7. **Categorize**: Severity (🔴 Critical / 🟡 High / 🟠 Medium / 🟢 Low) with evidence (GitHub/docs/npm)
8. **Fix**: Auto-fix unambiguous, ask user for architectural, update all files, bump version
9. **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 `drizzleAdapter` from `'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)

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 URLs
8. **YAML errors** - Invalid frontmatter
9. **Missing keywords** - Poor discoverability
10. **Incomplete bundled resources** - Listed files don't exist

---

## Bundled Resources

**Planning**: `~/.claude/skills/../planning/SKILL_REVIEW_PROCESS.md` or repo `planning/SKILL_REVIEW_PROCESS.md` (complete 9-phase guide)

**Scripts**: Repo root `scripts/review-skill.sh` (automated validation)

**Commands**: Repo root `commands/review-skill.md` (slash command, symlinked to `~/.claude/commands/`)

**References**: `references/audit-report-template.md` (output template)

---

**Last Verified**: 2026-01-09 | **Version**: 1.0.1


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/audit-report-template.md

```markdown
# 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**:
```diff
- 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**:
```markdown
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]

```