config-audit

Config Audit Skill

Purpose

Automated validation of Claude Code configuration against current best practices.

The mechanical part of this checklist is scripted — run it first:

python3 .claude/skills/config-audit/audit-config.py

Constants at the top of the script (essential MCP servers, security hooks, memory-file convention) are marked "customize for your project".

When to Use

• After making configuration changes
• Periodically (weekly/monthly) to check for updates
• When experiencing issues with Claude Code
• When new Claude Code features are released

Audit Checklist

1. Hooks Configuration

Hook Event	Best Practice	Check
SessionStart	✅ Required	Context loading, reminders, staleness
UserPromptSubmit	✅ Recommended	Prompt classification, workflow enforcement
PreToolUse	✅ Recommended	Security validation (Bash, Write/Edit)
PostToolUse	✅ Recommended	Auto-formatting, linting
Stop	✅ Recommended	Task completion evaluation
SubagentStop	Optional	Subagent completion notifications
PermissionRequest	Optional	Smart auto-approval

2. MCP Servers

Essential servers (customize — examples, not a mandate):

• Documentation: context7 (or your docs server)
• Search: exa / tavily (or your search server)
• Database: supabase (if using)
• Testing: playwright
• Memory: memory (knowledge graph)

Check for:

• Type consistency (http vs stdio)
• Environment variable expansion
• Timeout configuration
• Server health/availability

3. Skills Structure

Each skill should have:

---
name: skill-name
description: "Clear description with trigger keywords"
allowed-tools: Tool1, Tool2 # Restrict when possible
model: inherit # Or specific model
---

Check:

• Has clear description with trigger words
• Uses allowed-tools when appropriate
• Under 500 lines (use reference files for more)
• Has examples for complex skills

4. Agents Structure

Each agent should have:

---
name: agent-name
description: "When to use, trigger keywords"
tools: Tool1, Tool2
model: sonnet/opus/inherit
permissionMode: acceptEdits # or appropriate mode
---

Permission modes:

• default - Ask for each permission
• acceptEdits - Auto-approve edits (recommended for code agents)
• bypassPermissions - No restrictions (use carefully)

5. Settings Configuration

settings.json (shared):

• Hooks configuration
• No sensitive data

settings.local.json (personal):

• Permissions (allow/deny patterns)
• enabledMcpjsonServers
• Personal preferences

Check:

• Permissions use patterns, not specific commands
• No API keys in settings files
• Consistent with .mcp.json servers

6. Memory System

Example layout (customize — use whatever memory convention your project follows; the audit script's MEMORY_FILES constant should match it):

.claude/memory/
├── context.md    # Project context, tech stack
├── decisions.md  # Key decisions made
├── progress.md   # Current task status
└── memory.json   # MCP memory graph (auto-generated)

7. Security Checks

• No API keys in .claude/ files (use env vars)
• Dangerous commands blocked in PreToolUse
• Sensitive files protected by a PreToolUse validator
• .gitignore includes settings.local.json

Audit Process

Step 1: Read Configuration Files

# Files to check:
.claude/settings.json
.claude/settings.local.json
.mcp.json
.claude/hooks/*.py
.claude/hooks/*.sh

Step 2: Check Hook Coverage

Required: SessionStart, PreToolUse (Bash), PostToolUse (Write|Edit)
Recommended: UserPromptSubmit, Stop
Optional: SubagentStop, PermissionRequest

Step 3: Validate MCP Consistency

- All servers in .mcp.json listed in enabledMcpjsonServers
- No orphaned servers in enabledMcpjsonServers
- HTTP servers have proper URLs
- Stdio servers have valid commands

Step 4: Check Skills/Agents Quality

- Each has description with trigger keywords
- Critical skills have allowed-tools
- Code-modifying agents have permissionMode

Step 5: Compare with Latest Best Practices

Use WebSearch (or your search MCP) to check:
- Claude Code changelog
- New hook events
- New MCP capabilities
- Community best practices

Output Format

# 🔍 Claude Code Configuration Audit

**Date:** YYYY-MM-DD
**Version:** Claude Code X.X.X

## ✅ Compliant (X/Y)

- [x] Item that passes
- [x] Item that passes

## ⚠️ Warnings (X issues)

- [ ] Issue description → Recommendation

## 🔴 Critical (X issues)

- [ ] Issue description → Immediate action needed

## 🆕 New Features Available

- Feature name → How to enable

## 📈 Recommendations

1. Priority improvement
2. Nice-to-have improvement

## Next Audit

Schedule next audit for: [date]

Automation

To run periodic audits, add to your workflow:

1. Monthly: Full audit with web search for updates
2. After config changes: Quick validation
3. After Claude Code updates: Check new features

References

• Claude Code Docs: https://code.claude.com/docs/en/
• Hooks Guide: https://code.claude.com/docs/en/hooks
• Best Practices: https://anthropic.com/engineering/claude-code-best-practices