How to use the Agent Config Health Audit skill (health)

What an agent skill is and what health does

An agent skill is a folder of instructions and optional scripts that an agent such as Claude Code or Codex loads when a task matches the skill's description. The health skill is for setups that look wrong, for example when an agent keeps ignoring project instructions.

When it runs, the agent inspects the current project's assistant setup, such as Claude or Codex instruction files, settings, hooks and MCP connections. It reports where they look broken or out of date, such as instructions that are ignored or references that point to missing files. It also checks whether the codebase is easy for AI agents to maintain, for example whether verification checks exist and whether stale docs or verifier output point at old paths.

• Agent config health: instruction drift, permissions, hooks, MCP, skills and memory.
• AI maintainability health: whether verification checks exist, whether docs are stale, and whether generated artifacts are checked.
• Output: a prioritized report with status, impact and a suggested next action for each finding.

Install the health skill

Download the ZIP for the skill from the directory page. You can install it in one of two ways.

For Claude Code, unzip the download into ~/.claude/skills/ for a personal install, or into the .claude/skills/ folder of a project to share it with that project. For the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: the .claude/skills/ folder inside your project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Trigger the audit with a natural request

You do not need a special command. Ask in plain language, and the skill loads when your request matches its description. The skill's own trigger phrases include requests such as check config, audit config, settings not working, Claude ignoring instructions and Pi coding agent.

Name the scope in your request if you want a narrower check. A request that names only static material, such as AGENTS.md, skills, rules or settings, skips conversation history and reports that history as out of scope rather than as a gap.

• "Audit my agent config. Claude keeps ignoring the rules in CLAUDE.md."
• "Check whether my Codex setup and hooks are working."
• "Only review my AGENTS.md and skills, not my past sessions."
• "Run a deep health audit of this project's AI coding maintainability."

Read the report and act on it

The report groups findings by the layer where the problem sits: agent configuration, instruction surfaces, tools and runtime, verifiers, or maintainability. Each finding should name the misaligned layer, the evidence and a next action, which may be a diagnostic command.

The skill is report-only. It is designed not to fix things without your permission, so you decide which changes to make.

• Check that each finding names the layer and the evidence before you act on it.
• Ask the agent to apply a specific fix only after you have read the finding.
• Treat a clean report as a clean bill with residual risk, not a guarantee.

Requirements, scripts and safety

The bundled checks execute Python 3 and shell scripts (bash or zsh) on your machine. The skill does not use the network. It can read local Claude or Codex session history when you ask for conversation analysis, so only enable that if you are comfortable with it being read.

Deep audits can consume significant token quota. The skill states that it asks you before escalating to a deep run, and it does not read conversation extracts or start sub-agents in the summary pass.

• Requires Python 3 for the bundled scripts.
• Requires a shell environment (bash or zsh).
• Runs scripts: yes. Uses network: no.
• Local Claude or Codex session history is read only if you request conversation analysis.
• Do not use it if you do not want local scripts to run automatically.

Tips for getting useful results

Start with the default summary audit. Ask for a deep audit only when you need a thorough review, since it uses more quota. Do not use health for application bugs or pull request review, because the skill says it is not for those tasks.

• Use the static-only scope when you care about instructions, skills and settings but not past conversations.
• Keep your project instruction files current, since stale references are one of the things the audit flags.
• Re-run the audit after you change hooks or MCP settings to confirm the setup still matches the report.