commit 1df0ef2fbee188cd4947dc345c815ec0e2dfbfea Author: Zhongwei Li Date: Sun Nov 30 08:55:41 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..9d4a7cf --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "skill-review", + "description": "Comprehensive deep-dive documentation review process for claude-skills repository. Use this skill when investigating suspected issues in a skill, major package version updates detected (e.g., better-auth 1.x → 2.x), skill last verified >3 months ago, before marketplace submission, or when examples seem outdated. Performs systematic 9-phase audit: pre-review setup, standards compliance, official docs verification (Context7/WebFetch), code examples audit, cross-file consistency, dependency versi", + "version": "1.0.0", + "author": { + "name": "Claude Skills Maintainers", + "email": "maintainers@example.com" + }, + "skills": [ + "./" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..b4a7f73 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# skill-review + +Comprehensive deep-dive documentation review process for claude-skills repository. Use this skill when investigating suspected issues in a skill, major package version updates detected (e.g., better-auth 1.x → 2.x), skill last verified >3 months ago, before marketplace submission, or when examples seem outdated. Performs systematic 9-phase audit: pre-review setup, standards compliance, official docs verification (Context7/WebFetch), code examples audit, cross-file consistency, dependency versi diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..e7ac573 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,512 @@ +--- +name: skill-review +description: | + Comprehensive deep-dive documentation review process for sap-skills repository. Use this skill when investigating suspected issues in a skill, major package version updates detected, skill last verified >3 months ago, before marketplace submission, or when examples seem outdated. Performs systematic 14-phase audit: pre-review setup, standards compliance (exact YAML validation rules), official docs verification (Context7/WebFetch), code examples audit, cross-file consistency, dependency version checks, progressive disclosure architecture review, conciseness & degrees of freedom audit, anti-pattern detection, testing & evaluation review, security & MCP considerations, issue categorization by severity, fix implementation with minimal user questions, and post-fix verification. Enforces official Claude best practices including name validation (64 chars, lowercase/hyphens), description limits (1024 chars), SKILL.md line count (<500 lines), third-person writing style, progressive disclosure depth (one level), and multi-model testing verification. Prevents outdated documentation, incorrect API patterns, contradictory examples, version drift, broken links, YAML errors, schema inconsistencies, missing dependencies, Windows paths, inconsistent terminology, and over-explained content. Combines automated technical checks (YAML syntax, package versions, link validation, TODO markers) with AI-powered verification. Auto-fixes unambiguous issues, asks user only for architectural decisions or breaking change confirmations. Outputs severity-classified issue list (🔴 Critical / 🟡 High / 🟠 Medium / 🟢 Low) with evidence citations (GitHub URLs, official docs, changelogs) and detailed remediation plan. + + Keywords: skill review, skill audit, documentation review, version check, api verification, package updates, skill maintenance, quality assurance, standards compliance, breaking changes, github verification, official docs check, context7 verification, skill-review, audit-skill, review-documentation, check-skill-currency, verify-skill-accuracy, outdated skill, skill needs update, verify api methods, package version drift, stale documentation, contradictory examples, broken links check, yaml frontmatter validation, skill discovery test, production testing, sap skill review + +license: GPL-3.0 +metadata: + version: 1.3.0 + last_verified: 2025-11-21 + token_savings: ~80% + errors_prevented: 31+ + official_docs: [https://github.com/secondsky/sap-skills](https://github.com/secondsky/sap-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 sap-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**: Production-tested audit methodology on skill quality reviews. + +--- + +## 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 + +### 14-Phase Systematic Audit + +1. **Pre-Review Setup** (5-10 min) + - Install skill locally: `./scripts/install-skill.sh ` + - Check current version and last verified date + - Test skill discovery + +2. **Standards Compliance** (10-15 min) + - Validate YAML frontmatter with **exact rules**: + - `name`: Max 64 chars, pattern `^[a-z0-9-]+$`, NO "anthropic" or "claude" + - `description`: Max 1024 chars, NO XML tags (``), non-empty + - `license`: Present and valid (MIT, Apache-2.0, etc.) + - **SKILL.md line count**: Body should be <500 lines (optimal performance) + - Check keyword comprehensiveness + - Verify **third-person description style** (NOT "You should..." but "This skill should be used when...") + - Ensure gerund form naming (e.g., "processing-pdfs" not "pdf-processor") + - 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 ` + - Check for breaking changes in package updates + - Verify "Last Verified" date is recent + +7. **Progressive Disclosure Architecture Review** (10-15 min) + - Check reference depth: Resources should be **ONE LEVEL DEEP** from SKILL.md + - Verify files >100 lines have **Table of Contents** + - Assess 3-tier model compliance: + - Level 1 (Metadata): Always in context (~100 tokens) + - Level 2 (SKILL.md body): Loaded when triggered (<500 lines) + - Level 3 (Bundled resources): On-demand loading + - Flag deeply nested references (references → sub-references → ❌) + +8. **Conciseness & Degrees of Freedom Audit** (15-20 min) + - Identify **over-explained concepts** (Claude already knows this) + - Flag verbose sections that could be trimmed + - Assess **degrees of freedom** appropriateness: + - High freedom: Exploratory tasks, vague requirements + - Medium freedom: Conventional solutions, some flexibility + - Low freedom: Fragile tasks, exact patterns required + - Check for **defaults with escape hatches** (not endless options) + - Apply "context window is a public good" mindset + - Verify consistent terminology (same concept = same words throughout) + +9. **Anti-Pattern Detection** (10-15 min) + - ❌ Windows-style paths (`C:\path\file` → use forward slashes) + - ❌ Inconsistent terminology (endpoint/URL/path mixed usage) + - ❌ Time-sensitive information ("as of 2024" → use "old patterns" sections) + - ❌ Too many options without defaults (decision paralysis) + - ❌ Deeply nested references (>1 level) + - ❌ Vague phrases without examples + - ❌ Missing input/output examples for templates + - ❌ No feedback loops in complex workflows + +10. **Testing & Evaluation Review** (10-15 min) + - Check for **at least 3 test scenarios/evaluations** + - Verify **multi-model consideration** (Haiku/Sonnet/Opus may need different detail) + - Assess if skill solves **real problems** vs imagined ones + - Check for iterative development evidence (Claude A creates, Claude B tests) + - Verify production testing claims with evidence + +11. **Security & MCP Considerations** (5-10 min) + - Flag external URL fetches (potential risks) + - Check for skills from untrusted sources warnings + - Verify MCP tool references are **fully qualified** (ServerName:tool_name) + - Review script permissions and error handling + - Check "solve, don't punt" pattern (explicit error handling, not silent failures) + - **Marketplace schema compliance**: Only standard fields allowed (name, source, description, version, category, keywords, author, license, repository) - NO custom fields like `lastVerified` + +12. **Issue Categorization** (10-20 min) + - Classify by severity: 🔴 Critical / 🟡 High / 🟠 Medium / 🟢 Low + - Document with evidence (GitHub URL, docs link, npm changelog) + +13. **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 + +14. **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 ` 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 + +```bash +./scripts/review-skill.sh +``` + +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/ + Search for: [API method from skill] + ``` + +2. Or use WebFetch: + ``` + Fetch: [https://](https://) + Verify: [specific patterns] + ``` + +3. Check GitHub: + ``` + Visit: [https://github.com///commits/main](https://github.com///commits/main) + Check: Last commit, recent changes + Search issues: [keywords from skill] + ``` + +4. Find production examples: + ``` + WebSearch: " 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 + +```markdown +## Skill Review Report: + +**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](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 + +--- + +## 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 + +### Content & API Issues +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. **Contradictory examples** - Multiple conflicting patterns +6. **Incomplete bundled resources** - Listed files don't exist + +### Structure & Standards Issues +7. **YAML errors** - Invalid frontmatter syntax +8. **Name too long** - Exceeds 64 char limit +9. **Description too long** - Exceeds 1024 char limit +10. **Invalid name format** - Not lowercase/hyphens only +11. **Reserved words** - Contains "anthropic" or "claude" +12. **Second-person descriptions** - "You should..." instead of "This skill should be used when..." +13. **SKILL.md too long** - Body exceeds 500 lines (performance impact) + +### Architecture Issues +14. **Deeply nested references** - More than one level deep from SKILL.md +15. **Missing table of contents** - Files >100 lines without navigation +16. **Over-explained concepts** - Claude already knows this content + +### Quality & Testing Issues +17. **Missing keywords** - Poor discoverability +18. **Version drift** - Packages >90 days old +19. **Broken links** - 404 documentation URLs +20. **No test scenarios** - Missing evaluation cases +21. **No multi-model consideration** - Only tested with one model + +### Anti-Patterns +22. **Windows-style paths** - Backslashes instead of forward slashes +23. **Inconsistent terminology** - Same concept, different words +24. **Time-sensitive info** - "As of 2024" instead of version-based +25. **Too many options** - No defaults provided +26. **No feedback loops** - Complex workflows without validation steps + +### Security & MCP Issues +27. **Unqualified MCP references** - Missing ServerName:tool_name format +28. **Silent error handling** - "Punt" instead of "solve" +29. **Unvalidated external URLs** - Fetching from untrusted sources +30. **Missing permissions warnings** - Scripts without clear scope +31. **Non-standard marketplace fields** - Custom fields rejected by schema (e.g., lastVerified) + +--- + +## 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 14 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.3.0** (2025-11-21) +- Adapted for sap-skills repository +- Updated repository references +- Generalized examples for SAP skill development + +**v1.2.0** (2025-11-16) +- Added marketplace schema compliance check (no custom fields) +- 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 + +--- + +## Additional Resources + +- **Full Process Guide**: `planning/SKILL_REVIEW_PROCESS.md` +- **Repository**: [https://github.com/secondsky/sap-skills](https://github.com/secondsky/sap-skills) +- **Example Audit**: See process guide Appendix B (better-auth v2.0.0) + +--- + +**Last verified**: 2025-11-16 | **Version**: 1.2.0 diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..8b626da --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,49 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:secondsky/sap-skills:skills/skill-review", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "399c50a4dc5d9e25b1f08f8b4e2f1884eb19e69e", + "treeHash": "8511becf7325562f12247691e60d427f3adc56b483b87e53cf9b2ac1cc53d290", + "generatedAt": "2025-11-28T10:28:10.460370Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "skill-review", + "description": "Comprehensive deep-dive documentation review process for claude-skills repository. Use this skill when investigating suspected issues in a skill, major package version updates detected (e.g., better-auth 1.x → 2.x), skill last verified >3 months ago, before marketplace submission, or when examples seem outdated. Performs systematic 9-phase audit: pre-review setup, standards compliance, official docs verification (Context7/WebFetch), code examples audit, cross-file consistency, dependency versi", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "e07892294d39b2d0a42cc65c1b1eeed990a8af51c7c677abf7153674eb465e16" + }, + { + "path": "SKILL.md", + "sha256": "78558b6c1790207e7719498462768fa8b1b83f5298424493a17f925d179af1cd" + }, + { + "path": "references/audit-report-template.md", + "sha256": "67449dad69ea1cbef00373b7cbc0676e57deca0d6f3ac0032fac1f999dc31a44" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "beb6cba5e9c75753bb0882cb3a178df81b7d1f7f9694b9d9aa1f45254ad56519" + } + ], + "dirSha256": "8511becf7325562f12247691e60d427f3adc56b483b87e53cf9b2ac1cc53d290" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/references/audit-report-template.md b/references/audit-report-template.md new file mode 100644 index 0000000..deead1f --- /dev/null +++ b/references/audit-report-template.md @@ -0,0 +1,296 @@ +# 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] + +--- + +### Quick Validation Checks + +| Check | Rule | Status | Actual | +|-------|------|--------|--------| +| Name Length | Max 64 chars | ✅/❌ | [N chars] | +| Name Format | `^[a-z0-9-]+$` | ✅/❌ | [pattern] | +| Reserved Words | No "anthropic"/"claude" | ✅/❌ | [found/none] | +| Description Length | Max 1024 chars | ✅/❌ | [N chars] | +| Description XML Tags | No `` content | ✅/❌ | [found/none] | +| SKILL.md Lines | <500 lines | ✅/❌ | [N lines] | +| Third-Person Style | "This skill..." not "You should..." | ✅/❌ | [compliant/issues] | + +--- + +### Progressive Disclosure Score + +**Architecture Compliance**: [Good / Needs Work / Major Issues] + +- **Reference Depth**: ✅/❌ One level deep from SKILL.md +- **TOC for Long Files**: ✅/❌ Files >100 lines have table of contents +- **3-Tier Model**: + - Level 1 (Metadata): ✅/❌ Concise, always-loaded + - Level 2 (SKILL.md): ✅/❌ <500 lines, core content + - Level 3 (Resources): ✅/❌ On-demand loading +- **Nested References**: [N found] (should be 0) + +**Token Efficiency Notes**: +- [Observations about context usage] +- [Suggestions for optimization] + +--- + +### Conciseness Rating + +**Score**: [1-10] (10 = maximally concise) + +**Over-Explained Concepts** (Claude already knows): +- [Concept 1]: [Where found] +- [Concept 2]: [Where found] + +**Verbose Sections**: +- [Section]: Could reduce by [N] lines +- [Section]: Duplicates information from [other section] + +**Degrees of Freedom Assessment**: +- Task Fragility: [High / Medium / Low] +- Current Freedom Level: [High / Medium / Low] +- Appropriate: ✅/❌ + +**Terminology Consistency**: +- ✅/❌ Same concept uses same words throughout +- Inconsistencies found: [List if any] + +--- + +### Anti-Pattern Detection + +**Count**: [N] anti-patterns found + +- ❌/✅ Windows-style paths (`\` instead of `/`) +- ❌/✅ Inconsistent terminology +- ❌/✅ Time-sensitive information ("as of 2024") +- ❌/✅ Too many options without defaults +- ❌/✅ Deeply nested references (>1 level) +- ❌/✅ Vague phrases without examples +- ❌/✅ Missing input/output examples +- ❌/✅ No feedback loops in workflows + +**Specific Findings**: +1. [Anti-pattern]: [Location and fix] +2. [Anti-pattern]: [Location and fix] + +--- + +### Testing & Evaluation Review + +**Test Coverage**: [Excellent / Good / Needs Improvement / Missing] + +- **Test Scenarios**: [N] found (minimum 3 required) + 1. [Scenario 1] + 2. [Scenario 2] + 3. [Scenario 3] + +- **Multi-Model Consideration**: ✅/❌ + - Haiku: [Notes] + - Sonnet: [Notes] + - Opus: [Notes] + +- **Real Problem Validation**: ✅/❌ + - Skill solves actual user pain points: [Evidence] + - Not theoretical/imagined problems: [Assessment] + +- **Production Testing Evidence**: + - ✅/❌ Evidence provided + - Details: [What was tested, results] + +--- + +### Security & MCP Review + +- **External URL Fetches**: [N] found + - URLs: [List with risk assessment] + - Recommendation: [Keep / Remove / Add warning] + +- **MCP Tool References**: + - ✅/❌ All fully qualified (ServerName:tool_name) + - Issues: [List if any] + +- **Error Handling Quality**: + - ✅/❌ "Solve, don't punt" pattern followed + - Silent failures: [List if any] + +- **Script Security**: + - Permissions: [Assessment] + - Warnings: [Any missing warnings] + +--- + +### 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]