agent-config-audit

Files (1)

• SKILL.md

SKILL.md (first lines)

# Agent Config Audit

Use this skill when the task is to review the *static* configuration that shapes an AI agent's behavior in a repo. These surfaces accumulate over time: a rule added in one place, an override in another, a hook in a third — and they drift apart. This skill finds the drift.

## Use when

- the project has multiple agent surfaces (AGENTS.md, CLAUDE.md, OpenAI Agent docs, MCP configs) and the user wonders if they agree
- a rule "is supposed to apply" but does not
- a new contributor will be added and the question is which surface they need to read
- a third-party agent is being introduced and the team wants to know what surfaces it will or will not respect

## Workflow

1. **Inventory the surfaces.** Look for:
   - `AGENTS.md`, `CLAUDE.md`, `.cursor/rules`, `.cursorrules`, `.aider*`
   - `.claude/settings.json`, `.claude/settings.local.json`, `.claude/hooks/`
   - MCP server configs (`mcp.json`, `.mcp/`, app-specific config dirs)
   - Tool registration code (anything that calls `registerTool`, `defineTool`, or builds a tool registry)
   - Skill / instruction directories (`skills/`, `instructions/`)
   - `.github/copilot-instructions.md` if present
   - Provider-specific docs in `docs/` that prescribe agent behavior
2. **Map authority.** For each surface, record:
   - Which agent(s) read it
   - Whether it is committed or local-only (gitignored)
   - Whether it overrides another surface (and how — precedence rules)
3. **Rule extraction.** Pull the explicit rules from each surface into a normalized list: "agent X must / must not / should…"
4. **Cross-surface comparison.**
   - Identify rules that appear in only one surface
   - Identify rules that contradict between surfaces
   - Identify rules that *appear* to agree but use different vocabulary for the same thing (e.g., "feature branch" vs "topic branch")
5. **Hook and gate verification.**
   - For each hook (Claude Code, git hooks, pre-tool gates, runtime guards), confirm:
     - The trigger condition matches the documented rule
     - Failure messages reference the canonical surface
     - The bypass path (if any) is documented in the surface that describes the rule
6. **Tool registration consistency.**
   - Tools described in the agent prompt actually exist
   - Tool schemas match between the registration and the documentation
   - Tools that require approval are flagged as such in their description
7. **MCP server health.**
   - Each declared MCP server has a working command and known transport
   - Secrets referenced by MCP servers exist (env var names match)
   - Stale MCP entries pointing to removed binaries flagged
8. **Local vs committed.**
   - Rules that exist only in local settings (e.g., `.claude/settings.local.json` when `.claude/` is gitignored) are flagged with their team-coverage implication
   - Recommend committed equivalents when the rule should apply to everyone

## Checks

- Some surfaces are *intentionally* local-only (personal preferences, machine-specific paths) — do not flag those
- Treat `AGENTS.md` as the canonical written rule unless the repo declares otherwise
- For DAX specifically: `AGENTS.md` is canonical, `CLAUDE.md` is a Claude-specific entry point, `.githooks/` is the cross-contributor backstop, `.claude/settings.local.json` is per-user

## Output contract

Findings follow [docs/skills/OUTPUT_CONTRACT.md](../../docs/skills/OUTPUT_CONTRACT.md).

Return:

1. **Verdict** — one line + a small table:
   - `Surfaces found`, `Agents covered`, `Hooks active`, `MCP servers`, `Local-only surfaces`
2. **Counts** — Critical/High/Medium/Low/Info totals
3. **Findings** — one table per category, ordered by impact:
   - Contradictions between surfaces
   - Rules in only one place that should apply everywhere
   - Hooks not matching their documented rule
   - Tool registration / documentation drift
   - MCP server health
   - Local-only rules that should be committed
4. **Open questions / assumptions** — intended canonical surface, intended audience
5. **Next actions** — for each contradiction, recommend which surface wins and which to align

## Evidence to collect

- File path for every surface
- The normalized rule list with its source surface
- Hook trigger expressions verbatim
- MCP server command + transport for each declared server
- Tool name, schema reference, and prompt mention for each tool

From ShaileshRawat1403/dax, MIT.

More from ShaileshRawat1403/dax