How do I install the Setup Audit skill?

Run npx skillmds@latest add shaheershoaib/setup-audit in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Setup Audit safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Setup Audit?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Setup Audit free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Setup Audit?

shaheershoaib (@shaheershoaib) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Setup Audit by shaheershoaib — Agent Skill

Name: Setup Audit
Author: shaheershoaib

Setup Audit

Grade the Claude agent setup (~/.claude) and catch SILENT breakage - a skill whose frontmatter won't parse so it never loads, a hook pointing at a moved/renamed script so it no-ops, an MCP whose entry file is gone, a skill dir with no SKILL.md, or an accidental deletion (drift vs a saved snapshot). Use when asked to "audit my setup", "is my Claude config healthy", "grade my agent setup", after editing skills/agents/hooks/MCPs, or before sharing the environment bundle with someone.

shaheershoaib 62ca7fd 9 files · 64.1 KB Updated Sep 17, 2026

File contents

setup-audit

A health check for the agent environment itself - the meta layer most setups never verify until something silently stops working. (The "grade your setup" idea, kept to a static dependency-free check.)

What it checks

Skills - every ~/.claude/skills/*/SKILL.md parses as frontmatter and has name: + description:; name matches the directory; flags skill dirs with no SKILL.md. (A malformed frontmatter means the skill never loads - the failure is invisible until you reach for it.)
Agents - every ~/.claude/agents/*.md has valid frontmatter.
Hooks - every command in ~/.claude/settings.json resolves to a script that EXISTS and (for .sh) is executable. A hook pointing at a moved file fails silently.
MCP servers - every user-scope server in ~/.claude.json has its entry file present on disk (static check; see live-status step below).
Plugins + core - inventories plugins; confirms ~/.claude/CLAUDE.md.
Drift - compares the current inventory against a saved snapshot and lists anything ADDED or REMOVED (catches accidental deletions).

Run it

python3 ~/.claude/skills/setup-audit/audit.py

Output is a readiness score, then FAIL (broken - fix) and WARN (check) findings, then drift vs snapshot. Exit code is 1 if any FAIL.

Live MCP status (the static check only proves the entry file exists, not that the server handshakes): run

claude mcp list

and confirm each server reads ✔ Connected. A server that fails here but passes the static check usually has a runtime error - run node <entry> or check claude mcp get <name>.

Baseline a known-good setup so future runs can detect drift:

python3 ~/.claude/skills/setup-audit/audit.py --snapshot

Re-snapshot deliberately after intentional changes; between snapshots, drift lines are the diff.

Interpreting

FAIL = it will not work as intended (skill won't load, hook script gone, MCP entry missing). Fix before relying on it.
WARN = worth a look (name/dir mismatch, non-executable hook, inline hook command with no script file to verify, missing optional core file).
Drift = an item appeared or disappeared since the snapshot. Expected after you add/remove things; suspicious otherwise (e.g. a skill you didn't mean to delete).

When to use

After editing skills/agents/hooks/MCPs (did anything silently break?).
Before packaging/sharing the environment with a teammate (ship a clean setup).
Periodically, as a config-health pass.

The user-scope MCP servers in ~/.claude.json are what the MCP check audits.
fewer-permission-prompts - the other "tune your setup" skill.

---name: setup-auditdescription: Grade the Claude agent setup (~/.claude) and catch SILENT breakage - a skill whose frontmatter won't parse so it never loads, a hook pointing at a moved/renamed script so it no-ops, an MCP whose entry file is gone, a skill dir with no SKILL.md, or an accidental deletion (drift vs a saved snapshot). Use when asked to "audit my setup", "is my Claude config healthy", "grade my agent setup", after editing skills/agents/hooks/MCPs, or before sharing the environment bundle with someone.---# setup-auditA health check for the agent environment itself - the meta layer most setupsnever verify until something silently stops working. (The "grade your setup"idea, kept to a static dependency-freecheck.)## What it checks- **Skills** - every `~/.claude/skills/*/SKILL.md` parses as frontmatter and has `name:` + `description:`; `name` matches the directory; flags skill dirs with no SKILL.md. (A malformed frontmatter means the skill never loads - the failure is invisible until you reach for it.)- **Agents** - every `~/.claude/agents/*.md` has valid frontmatter.- **Hooks** - every `command` in `~/.claude/settings.json` resolves to a script that EXISTS and (for `.sh`) is executable. A hook pointing at a moved file fails silently.- **MCP servers** - every user-scope server in `~/.claude.json` has its entry file present on disk (static check; see live-status step below).- **Plugins + core** - inventories plugins; confirms `~/.claude/CLAUDE.md`.- **Drift** - compares the current inventory against a saved snapshot and lists anything ADDED or REMOVED (catches accidental deletions).## Run it```bashpython3 ~/.claude/skills/setup-audit/audit.py```Output is a readiness score, then `FAIL` (broken - fix) and `WARN` (check)findings, then drift vs snapshot. Exit code is 1 if any FAIL.**Live MCP status** (the static check only proves the entry file exists, notthat the server handshakes): run```bashclaude mcp list```and confirm each server reads `✔ Connected`. A server that fails here but passesthe static check usually has a runtime error - run `node <entry>` or check`claude mcp get <name>`.**Baseline a known-good setup** so future runs can detect drift:```bashpython3 ~/.claude/skills/setup-audit/audit.py --snapshot```Re-snapshot deliberately after intentional changes; between snapshots, driftlines are the diff.## Interpreting- **FAIL** = it will not work as intended (skill won't load, hook script gone, MCP entry missing). Fix before relying on it.- **WARN** = worth a look (name/dir mismatch, non-executable hook, inline hook command with no script file to verify, missing optional core file).- **Drift** = an item appeared or disappeared since the snapshot. Expected after you add/remove things; suspicious otherwise (e.g. a skill you didn't mean to delete).## When to use- After editing skills/agents/hooks/MCPs (did anything silently break?).- Before packaging/sharing the environment with a teammate (ship a clean setup).- Periodically, as a config-health pass.## Related- The user-scope MCP servers in `~/.claude.json` are what the MCP check audits.- `fewer-permission-prompts` - the other "tune your setup" skill.

Frequently asked questions