Initial commit

2025-11-30 08:55:41 +08:00
commit 1df0ef2fbe
5 changed files with 872 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ 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": [
+    "./"
+  ]
+}
--- a/README.md
+++ 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
--- a/SKILL.md
+++ 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 <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
+
+### 14-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 with **exact rules**:
+     - `name`: Max 64 chars, pattern `^[a-z0-9-]+$`, NO "anthropic" or "claude"
+     - `description`: Max 1024 chars, NO XML tags (`<tag>`), 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 <skill-name>`
+   - 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 <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
+
+```bash
+./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>](https://<official-docs-url>)
+   Verify: [specific patterns]
+   ```
+
+3. Check GitHub:
+   ```
+   Visit: [https://github.com/<org>/<repo>/commits/main](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
+
+```markdown
+## 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](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
--- a/plugin.lock.json
+++ 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": []
+  }
+}
--- a/references/audit-report-template.md
+++ 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 `<tag>` 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]