# Agent Audit > Audits Claude Code agent configuration against latest best practices. Works on any project. Manual via /agent-audit. Use when this capability is needed. - Skill: `tomevault-io/agent-audit` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/agent-audit` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/agent-audit/raw - Safety review: pending (external: skill-scanner PASS, skillspector FAIL) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/agent-audit --- # Agent Configuration Audit Audit this project's Claude Code agent configuration against latest best practices. ## Gotchas 1. **Flagging intentional patterns as issues.** Read CLAUDE.md and `.claude/rules/` FIRST. What looks like a misconfiguration may be an intentional project convention documented there. Never report something as an issue if it's explained in the project's own docs. 2. **Recommending fields that don't exist.** Claude Code's supported frontmatter fields change between versions. ALWAYS verify against the latest docs (Phase 1 research) before flagging a "missing" field — it may not be supported yet, or may have been deprecated. 3. **Overwhelming output.** A full audit can produce 50+ findings. Prioritize ruthlessly — lead with HIGH severity, collapse LOW items into a summary table. Users stop reading after 10 findings. 4. **Ignoring user-level config.** Project-level `.claude/` is only half the picture. Always check `~/.claude/settings.json`, `~/.claude/rules/`, and `~/.claude/skills/` for conflicts or overrides that affect behavior. ## Argument Parsing Parse `$ARGUMENTS` to determine scope. Examples: | Invocation | Scope | |---|---| | `/agent-audit` | Full audit — all components | | `/agent-audit full` | Same as above | | `/agent-audit hooks` | Only hooks (settings.json hook config + .claude/hooks/ scripts) | | `/agent-audit permissions` | Only permission allowlists/denylists in settings.json | | `/agent-audit claudeignore` | Only .claudeignore | | `/agent-audit claude-md` | Only CLAUDE.md | | `/agent-audit memory` | Only MEMORY.md | | `/agent-audit skills` | Deep-dive ALL skills — skip general audit | | `/agent-audit skill:add-logs` | Deep-dive ONLY the `add-logs` skill — skip everything else | | `/agent-audit skill:agent-audit` | Deep-dive ONLY this skill (meta-audit) | | `/agent-audit agents` | Deep-dive ALL agents — skip general audit | | `/agent-audit agent:code-reviewer` | Deep-dive ONLY the `code-reviewer` agent — skip everything else | | `/agent-audit rules` | Audit rules files — quality + conflict detection | **Routing logic:** - If argument starts with `skill:` → extract skill name → jump directly to **Skill Deep-Dive** for that one skill only. Skip Phases 1-2. - If argument starts with `agent:` → extract agent name → jump directly to **Agent Deep-Dive** for that one agent only. Skip Phases 1-2. - If argument is `skills` → discover all skills → run **Skill Deep-Dive** for each. Skip Phase 2 general audit. - If argument is `agents` → discover all agents → run **Agent Deep-Dive** for each. Skip Phase 2 general audit. - If argument is `rules` → jump directly to **Rules Conflict Detection**. Skip Phases 1-2. - If argument is a component name (`hooks`, `permissions`, etc.) → run Phase 1 research scoped to that topic + Phase 2 checklist for that component only. - If empty or `full` → run everything. ## Phase 1: Research Latest Best Practices Use the Agent tool to launch **parallel research agents** (subagent_type: "general-purpose"). All agents MUST search the web for the **current year's** content: ### Agent 1: Official Claude Code Docs Fetch latest official Claude Code documentation for: - Hooks: events, matchers, exit codes - Settings: permissions, deny lists, sandbox, attribution - Memory: CLAUDE.md hierarchy, auto-memory, `.claude/rules/` - Skills: **valid frontmatter fields** (critical — verify which fields are actually supported vs silently ignored) - MCP, plugins, subagents ### Agent 2: Community Patterns & New Features Search for: - Claude Code changelog / release notes for current year - Community best practices and patterns - New features or deprecated settings **When scoped to a component** (e.g., `/agent-audit hooks`): only research that component's docs, not everything. ## Phase 2: General Audit Read and audit agent-related files. **Skip this phase entirely for `skills` or `skill:` arguments.** ### Files to Check Auto-discover — check for existence of each: ``` .claudeignore .claude/settings.json .claude/settings.local.json .claude/hooks/* .claude/commands/* .claude/skills/*/SKILL.md (surface-level only — name, description, size) .claude/agents/* (if exists) .claude/rules/* (if exists) .mcp.json (if exists) CLAUDE.md (or claude.md) openspec/ (if exists) .gitignore ``` ### Checklist **`.claudeignore`** - [ ] Excludes build artifacts (dist/, build/, node_modules/, .next/, etc.) - [ ] Excludes secrets (.env, .keys/, certificates, *.pem) - [ ] Excludes coverage and logs - [ ] Excludes .git/ - [ ] No over-exclusion of files Claude needs **`.claude/settings.json`** - [ ] Has `$schema` for validation (if supported) - [ ] Permission allowlists cover common safe commands - [ ] Permission denylists block destructive commands - [ ] Hooks are configured (PreToolUse protection, PostToolUse formatting) - [ ] No outdated or deprecated settings **Hooks** - [ ] Protect-files hook covers sensitive paths (if exists) - [ ] Hook scripts are executable (chmod +x) - [ ] Exit codes correct (0=allow, 2=block) - [ ] PostToolUse auto-format covers relevant extensions (if exists) - [ ] No missing hook events that would be beneficial **CLAUDE.md** - [ ] Size under 15KB (if over, recommend moving sections to `.claude/rules/`) - [ ] Contains project overview, commands, architecture, patterns - [ ] No stale information - [ ] No duplication with other config files **Commands & Skills (surface-level)** - [ ] All commands functional for current environment - [ ] Referenced templates and files exist - [ ] Each skill has frontmatter with `name` and `description` - [ ] Descriptions are concise **Memory (MEMORY.md if exists)** - [ ] Under 200 lines - [ ] Organized by topic - [ ] No stale information **.gitignore** - [ ] Includes `.claude/settings.local.json` ## Phase 3: Skill Deep-Dive **Triggered by:** `skills` (all), `skill:` (one), or during `full` audit if a skill looks problematic in surface-level check. ### Discovery 1. List all skills: `ls .claude/skills/*/SKILL.md` 2. If `skill:` — find the matching skill directory 3. Read each target skill's SKILL.md fully ### Complexity Assessment (for `skills` argument only) Before auditing each skill, assess if it needs a separate agent: **Use a separate agent when ANY of these are true:** - SKILL.md exceeds 100 lines - Skill contains inline commands (exclamation-backtick syntax) that need execution testing - Skill references external files or scripts - Skill has complex argument handling **Audit inline (no separate agent) when:** - SKILL.md is short and simple (under 100 lines) - No inline commands or external references - Straightforward instructions ### Skill Audit Checklist For EVERY skill being deep-dived, check ALL of the following: **Frontmatter** - [ ] Only uses supported fields (from Phase 1 research — verify against latest docs) - [ ] `name` is lowercase with hyphens - [ ] `description` is concise — long descriptions bloat every session's system prompt - [ ] No unsupported fields silently ignored **Content & Structure** - [ ] SKILL.md under 500 lines - [ ] Clear separation of conventions vs workflow - [ ] Examples provided for non-trivial behavior - [ ] Supporting files (if any) exist and are referenced **Technical Correctness** - [ ] Inline commands (exclamation-backtick syntax) are valid — execute them and verify output - [ ] Grep/filter patterns match current codebase naming conventions - [ ] Referenced file paths and directories exist - [ ] No hardcoded absolute paths - [ ] No project-specific assumptions that should be generalized (for user-level skills) **Codebase Alignment** - [ ] Conventions match CLAUDE.md and project rules - [ ] No contradictions with project patterns - [ ] File naming patterns reflect current state - [ ] Filter patterns cover all relevant file types **Invocation & UX** - [ ] Description clearly signals manual-only if intended - [ ] `$ARGUMENTS` handling documented - [ ] Output format specified (what user sees after skill runs) - [ ] Error cases handled (e.g., no files match, empty diff) **Security** - [ ] No secrets in skill content - [ ] Inline commands don't expose sensitive data - [ ] Doesn't bypass protect-files hook ### Skill Deep-Dive Report (per skill) ``` ### Skill: **Lines:** N | **Complexity:** low/medium/high | **Agent used:** yes/no **Checks Passed:** X/Y | Category | Check | Status | Detail | |----------|-------|--------|--------| | Frontmatter | Supported fields only | PASS/FAIL | ... | | Frontmatter | Description concise | PASS/FAIL | ... | | Technical | Inline commands valid | PASS/FAIL | ... | | Technical | Patterns match codebase | PASS/FAIL | ... | | Alignment | Matches CLAUDE.md | PASS/FAIL | ... | | Security | No secrets exposed | PASS/FAIL | ... | ``` ## Phase 3b: Agent Deep-Dive **Triggered by:** `agents` (all), `agent:` (one), or during `full` audit. ### Discovery 1. List all agents: `ls .claude/agents/*.md` 2. If `agent:` — find the matching agent file 3. Read each target agent file fully ### Agent Audit Checklist For EVERY agent being deep-dived, check ALL of the following: **Frontmatter** - [ ] Has `name` and `description` - [ ] `model` is appropriate for the agent's complexity (sonnet for fast tasks, opus for complex) - [ ] Description examples match the project's domain and conventions **Codebase Alignment** - [ ] Tech stack references match actual project - [ ] Review dimensions are relevant to this project's stack - [ ] Convention checklist matches CLAUDE.md and project rules - [ ] Architecture checks reflect actual patterns - [ ] No references to frameworks, libraries, or patterns not used in this project **Content Quality** - [ ] Clear review process / workflow steps - [ ] Output format specified - [ ] Edge cases handled - [ ] Guidelines are actionable and specific **Security** - [ ] No secrets in agent content - [ ] No instructions that could bypass safety measures ### Agent Deep-Dive Report (per agent) ``` ### Agent: **Lines:** N | **Model:** sonnet/opus **Checks Passed:** X/Y | Category | Check | Status | Detail | |----------|-------|--------|--------| | Frontmatter | Has name + description | PASS/FAIL | ... | | Frontmatter | Model appropriate | PASS/FAIL | ... | | Alignment | Tech stack matches project | PASS/FAIL | ... | | Alignment | Conventions match CLAUDE.md | PASS/FAIL | ... | | Content | Clear workflow | PASS/FAIL | ... | | Security | No secrets | PASS/FAIL | ... | ``` ## Phase 3c: Rules Conflict Detection **Triggered by:** `rules`, or during `full` audit. ### Rules Conflict Detection When auditing rules (either as part of `full` or `rules` scope): 1. **Identify sources**: Classify each rules file: - **Arcana rules**: files matching `arcana-*.md` pattern in `.claude/rules/` - **User rules**: all other `.md` files in `.claude/rules/` - **CLAUDE.md**: project root instructions 2. **Read all rules files** and extract the key directives from each 3. **Cross-check for semantic conflicts**: - For each Arcana directive, check if any user rule contradicts it - Example conflict: Arcana says "research before acting" but user rule says "be concise, no research" - Example non-conflict: Arcana says "verify before output" and user says "use TypeScript strict" (different concerns) 4. **Report findings with source labels**: ``` 📦 Arcana rules (3 files): ✓ arcana-quality.md — no conflicts ⚠ arcana-research.md — potential conflict with your rules Arcana: "Research before acting" Your rule (coding-style.md): "Keep responses concise and fast" → These may conflict during complex analysis tasks 📁 Your project rules (2 files): ✓ architecture.md — no issues ✓ coding-style.md — reviewed (see conflict above) ``` 5. **For each conflict**: Ask the user which should take priority. Do NOT auto-resolve. 6. **Self-audit note**: When auditing Arcana's own skills, label them clearly: ``` 📦 Arcana skill: deep-review ✓ Frontmatter valid ⚠ Could benefit from `context: fork` (new Claude Code feature) ``` Never say "Arcana's skill is wrong." Say "could benefit from [improvement]" or "consider updating." ## Phase 4: Report ### Full/Component Audit Report ``` ## Agent Configuration Audit Report **Date:** YYYY-MM-DD **Project:** **New Features Found:** [any new Claude Code features from research] ### Score: X/10 ### What's Working Well - ... ### Issues Found | # | Severity | Component | Issue | Recommendation | |---|----------|-----------|-------|----------------| ### Recommendations (Priority Ordered) 1. [HIGH] ... 2. [MEDIUM] ... 3. [LOW] ... ``` ## Phase 5: Implementation Plan If actionable improvements found: 1. Write concrete plan with exact file changes 2. Wait for user approval 3. On approval, implement changes If no issues: report "All clear — configuration is up to date" and skip planning. ## Rules - NEVER modify files without user approval - ALWAYS search latest docs — do not rely on cached knowledge - Be specific — include exact file paths and code snippets in recommendations - Flag deprecated or silently-ignored settings/fields - If CLAUDE.md exceeds 15KB, recommend moving sections to `.claude/rules/` - Adapt to whatever project structure exists — don't assume any specific stack - Check for both project-level AND user-level skills/rules conflicts --- > Source: [cj-ways/arcana](https://github.com/cj-ways/arcana) — distributed by [TomeVault](https://tomevault.io).