Menu
Periodic self-audit of Claude Code configuration quality, effectiveness, and documentation currency
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when deciding how to manage, audit, sync, enable, disable, or troubleshoot skills and agents with the skillshare CLI across Claude Code, Codex, Gemini, OpenCode, Kiro, Goose, Pi, Antigravity, or project-local .skillshare setups. Especially use for questions about global vs project mode, disabled-by-default policies, .skillignore/.agentignore, target drift, broken symlinks, duplicate skills, sync dry-runs, or whether to use skillshare versus a runtime-native tool such as Codex skill-manager.
Use when creating git commits or reviewing commit messages. Ensures messages follow the Conventional Commits specification v1.0.0, which enables automated changelogs and semantic versioning. Invoked when the user wants to commit changes, craft a commit message, or validate an existing one.
Use when user references previous work phases, tasks, or discussions from prior sessions not present in current conversation context.
Use when designing or reviewing Python classes, deciding where logic belongs, or recognizing antipatterns like helper classes, utility bags, and god objects.
Use when crafting prompts that require factual accuracy, working with long documents, generating claims that need verification, or when outputs must be auditable and grounded in source material
Use when transitioning between work sessions and wanting to pick up where the previous session left off.
| name | self-audit |
| description | Periodic self-audit of Claude Code configuration quality, effectiveness, and documentation currency |
This skill enables Claude (primarily Kim) to run systematic audits of Claude Code configuration to identify inefficiencies, stale documentation, and improvement opportunities.
Weekly Self-Audit (Every Monday):
Monthly Documentation Refresh (First Monday of month):
Run audit immediately when:
Comprehensive configuration review:
Output: Structured report with findings and concrete recommendations.
Scan all Claude Code configurations:
# Global configuration
ls -la ~/.claude/agents/
ls -la ~/.claude/skills/
ls -la ~/.claude/conventions/
cat ~/.claude/CLAUDE.md
# Project configurations (if in project)
cat .claude/CLAUDE.md
ls -la .claude-sessions/ 2>/dev/null
Create inventory:
For each agent in ~/.claude/agents/:
Validate structure:
Check for inefficiencies:
Questions to ask:
For each skill in ~/.claude/skills/:
Validate utility:
Check for improvements:
Questions to ask:
Review conventions in ~/.claude/conventions/:
Check adoption:
Validate currency:
Global documentation:
cat ~/.claude/CLAUDE.md
Check:
Project documentation (if in project):
cat .claude/CLAUDE.md
cat CLAUDE.md
Check:
Calculate configuration overhead:
# Count lines in agent definitions
wc -l ~/.claude/agents/*.md
# Count lines in skills
find ~/.claude/skills -name "*.md" -exec wc -l {} +
# Estimate tokens (rough: 1 token ≈ 0.75 words, avg 6 chars/word)
# For accurate count, would need tokenizer
Identify token waste:
Calculate overhead:
Review improvements over time:
Context recovery incidents:
Token usage trends:
Task completion efficiency:
If metrics unavailable, note: "Recommend tracking these metrics going forward"
Check Claude Code documentation for updates:
# Use WebSearch or WebFetch
Search for:
Compare with current working knowledge:
If updates found:
Format:
# Self-Audit Report - [Date]
## Executive Summary
[2-3 sentences: Overall health, key findings, priority recommendations]
## Configuration Inventory
- Agents: [count]
- Skills: [count]
- Conventions: [count]
- Total estimated token overhead: ~[X] tokens
## Findings
### Agent Quality
- ✅ [Good practices found]
- ⚠️ [Issues identified]
- 💡 [Optimization opportunities]
### Skill Effectiveness
- ✅ [Working well]
- ⚠️ [Issues or underutilized skills]
- 💡 [Enhancement ideas]
### Convention Compliance
- ✅ [Conventions being followed]
- ⚠️ [Conventions ignored or stale]
- 💡 [New conventions needed]
### Documentation Currency
- ✅ [Current and accurate]
- ⚠️ [Stale or outdated]
- 💡 [Updates needed]
### Token Efficiency
- Current overhead: ~[X] tokens per session
- Identified waste: ~[Y] tokens
- Optimization potential: ~[Z]% reduction
### Effectiveness Metrics
- Context recovery incidents: [trend]
- Token usage trend: [improving/stable/degrading]
- Task completion efficiency: [assessment]
## Recommendations
### High Priority
1. [Specific actionable recommendation]
2. [Another high-priority fix]
### Medium Priority
1. [Improvement that would help]
2. [Another enhancement]
### Low Priority / Future
1. [Nice-to-have improvement]
2. [Long-term enhancement]
## Documentation Updates
[If monthly audit:]
- Checked Claude Code docs: [date]
- New features found: [list or "none"]
- Updates applied: [list or "none pending"]
## Next Audit
- Weekly audit: [next Monday date]
- Monthly audit: [first Monday of next month]
---
*Audit completed by: [agent name]*
*Audit duration: [X] minutes*
*Total findings: [count]*
Add audit findings to lessons-learned.md:
## [Date] - Self-Audit Findings
**Audit Type:** [Weekly/Monthly/Triggered]
**Key Discoveries:**
- [Pattern or issue discovered]
- [Optimization opportunity]
- [Effectiveness validation]
**Actions Taken:**
- [Fix implemented]
- [Documentation updated]
- [New convention/skill created]
**Impact:**
- [Measurable improvement]
- [Token savings]
- [Quality enhancement]
**Tags:** #self-audit #configuration-quality #continuous-improvement
# Self-Audit Report - 2025-12-23 (Weekly)
## Executive Summary
Configuration healthy overall. Identified one stale agent and token optimization opportunity in kim-v2 agent. No urgent issues.
## Configuration Inventory
- Agents: 6
- Skills: 8
- Conventions: 4
- Total estimated token overhead: ~4200 tokens
## Findings
### Agent Quality
- ✅ All agents have valid YAML frontmatter
- ✅ Tool assignments appropriate
- ⚠️ agent-persona-requirements-analyst.md hasn't been used in 3 weeks
- 💡 kim-v2.md is 450 lines - could trim 50 lines from examples
### Skill Effectiveness
- ✅ git-context-recovery used 3 times this week (working well)
- ✅ session-notes-writer triggered appropriately (no over-suggesting)
- ⚠️ developer-growth-analysis hasn't been used in 2 months
### Convention Compliance
- ✅ task-workflow convention followed in current project
- ✅ context-recovery convention being applied
### Documentation Currency
- ✅ Global CLAUDE.md accurate
- ⚠️ Project CLAUDE.md "Pending Work" has 2 completed items not marked
### Token Efficiency
- Current overhead: ~4200 tokens per session
- Identified waste: ~100 tokens (kim-v2 examples)
- Optimization potential: ~2% reduction
## Recommendations
### High Priority
1. Update project CLAUDE.md to mark completed items
2. Verify if agent-persona-requirements-analyst is still needed
### Medium Priority
1. Trim kim-v2 examples to save ~50 tokens
2. Review developer-growth-analysis skill (archive if unused)
## Next Audit
- Weekly audit: 2025-12-30
- Monthly audit: 2026-01-06
# Self-Audit Report - 2026-01-06 (Monthly)
## Executive Summary
Strong overall configuration. New Claude Code features available (extended context, improved tool calling). Identified 600 token optimization opportunity. Recommend adopting new features and retiring 1 deprecated skill.
## Configuration Inventory
- Agents: 6
- Skills: 8
- Conventions: 4
- Total estimated token overhead: ~4500 tokens
## Findings
### Agent Quality
- ✅ All agents current and well-structured
- ✅ Tool usage appropriate
- ⚠️ kim-v2.md references old WebSearch syntax (now deprecated)
- 💡 New tools available: PlanExecute, MultiRead (batch file reading)
### Skill Effectiveness
- ✅ git-context-recovery: 12 uses this month, 0 failures (excellent)
- ✅ session-notes-writer: Triggered 8 times, user satisfaction high
- ⚠️ create-agent-skills: Complex router skill rarely used
- 💡 Could simplify skill structure with new PlanExecute tool
### Convention Compliance
- ✅ All 4 conventions actively used
- ✅ No compliance gaps
- 💡 New convention opportunity: Multi-agent collaboration patterns
### Documentation Currency
- ✅ Global CLAUDE.md accurate
- ✅ Project CLAUDE.md files current
- ⚠️ 2 skills reference old docs.claude.com URLs (updated URLs available)
### Token Efficiency
- Current overhead: ~4500 tokens per session
- Identified waste: ~600 tokens
- kim-v2 examples: ~100 tokens
- Deprecated WebSearch syntax explanations: ~200 tokens
- create-agent-skills router overhead: ~300 tokens
- Optimization potential: ~13% reduction
### Effectiveness Metrics
- Context recovery incidents: Decreased 85% since git-context-recovery deployment
- Token usage trend: Stable (configuration overhead unchanged)
- Task completion efficiency: Improved ~20% (measured by git commits per session)
## Recommendations
### High Priority
1. **Update WebSearch usage in kim-v2.md** (deprecated syntax)
2. **Adopt new MultiRead tool** for batch file operations (token savings)
3. **Update skill doc URLs** to new Claude Code documentation structure
### Medium Priority
1. **Simplify create-agent-skills** using PlanExecute tool (save ~300 tokens)
2. **Trim kim-v2 examples** to essential patterns (~100 token savings)
3. **Consider multi-agent collaboration convention** (emerging pattern)
### Low Priority / Future
1. Explore extended context feature for larger agent definitions
2. Create effectiveness metrics dashboard (track trends automatically)
## Documentation Updates
- Checked Claude Code docs: 2026-01-06
- New features found:
- Extended context (now 300K tokens available)
- PlanExecute tool (structured multi-step execution)
- MultiRead tool (batch file reading)
- Improved tool calling (lower latency)
- Deprecated:
- Old WebSearch syntax (query parameter format changed)
- Some MCP server patterns (new architecture)
**Actions taken:**
- [X] Updated kim-v2.md WebSearch syntax
- [X] Updated skill documentation URLs
- [ ] Pending: Refactor create-agent-skills with PlanExecute
- [ ] Pending: Adopt MultiRead in file-heavy skills
## Next Audit
- Weekly audit: 2026-01-13
- Monthly audit: 2026-02-03
---
*Audit completed by: kim-v2*
*Audit duration: 18 minutes*
*Total findings: 11 (3 high, 5 medium, 3 low priority)*
DO:
DON'T:
To trigger audit:
After audit:
Every audit updates ~/.claude/knowledge/lessons-learned.md:
After audit completion:
Example entry:
## 2026-01-06 - Monthly Self-Audit
**Findings:**
- git-context-recovery reduced context recovery incidents by 85%
- Token optimization opportunity: 600 tokens (~13% of overhead)
- New Claude Code features available (PlanExecute, MultiRead)
**Actions:**
- Updated WebSearch syntax across agents
- Created action items for PlanExecute adoption
- Scheduled skill refactor to use new tools
**Impact:**
- Validated context recovery system effectiveness (high value)
- Identified next optimization target (skill complexity)
**Tags:** #self-audit #metrics #documentation-refresh
~/.claude/knowledge/lessons-learned.md - Audit schedule and checklist~/.claude/conventions/context-recovery.md - One system audited for effectivenesskim-v2 - Primary agent responsible for running auditsThis skill enables continuous improvement through systematic self-reflection and configuration optimization.