gh-secondsky-sap-skills-skills-skill-review/references/audit-report-template.md

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:

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