System audit

System Audit

Full system audit for AI agent setups. Inventories everything, scores health, measures context weight, maps dependencies, checks portability. Outputs a machine-readable manifest.

Built by doing it once by hand and recording every step. This skill is that recording.

When to Use

• First time setting up: "What do I actually have?"
• Periodic maintenance: "Is everything healthy?"
• Before publishing: "What's portable, what's trapped?"
• Onboarding someone to your system: "Here's the map"
• After major changes: "Did anything break?"

The Pipeline

Nine steps, in order. Each builds on the previous.

Step 1: Scope and Metrics (autoresearch:plan)

Define what you're auditing and how you'll measure progress.

Default scope: Everything in ~/.claude/ and ~/.openclaw/ (or equivalent agent infrastructure).

Default metrics:

• Manifest coverage (components cataloged)
• Portability score (% usable by 2+ platforms)
• Skill health average (out of 14)

Step 2: Health Audit

Run two parallel audits:

Skill Doctor (14-question health check): Launch an agent with this prompt:

"For each skill in ~/.claude/skills/, read the SKILL.md and score against 14 questions (1 point each): (1) SKILL.md exists with valid YAML frontmatter, (2) name field present and lowercase, (3) description present, (4) user-invocable set, (5) trigger/when-to-use section, (6) workflow section, (7) dependencies declared, (8) version in metadata, (9) author in metadata, (10) references/ subdirectory, (11) clear actionable instructions, (12) no hardcoded paths, (13) error recovery docs, (14) new user could understand it. Output: name | score/14 | failed questions."

Context Weight Audit: Launch an agent with this prompt:

"Measure byte size of everything that loads into context every session: MEMORY.md, CLAUDE.md, skills registry (~200 chars per entry), hooks (settings.json), each SKILL.md file. Flag anything over 5KB. Report total fixed cost per session."

Script Portability Audit: Launch an agent with this prompt:

"Audit all scripts for: hardcoded user paths (Y/N), macOS-only commands (Y/N), API dependencies, tool dependencies, internal script dependencies. Summarize: how many hardcoded, how many macOS-only, top 5 most-depended-on scripts."

Step 3: Dependency Map

Launch an agent with this prompt:

"Map which scripts are engines for which skills. Produce three lists: (A) Skills with script engines (correctly paired), (B) Skills with no script engine (pure prompt, not portable), (C) Scripts with no skill wrapper. Also map internal dependency chains."

Step 4: Blast Radius (Hurt Locker)

Before making any changes, analyze what could break.

Launch an agent with this prompt:

"For each planned change from the audit findings, analyze: what depends on it, what breaks if it goes wrong, is it reversible, risk level (LOW/MEDIUM/HIGH)."

Key hazards to check:

• Scripts inside single-quoted heredocs (Python) won't expand $HOME
• Trigger extraction needs CLAUDE.md keyword stubs (triggers fire on natural language, skills fire on /name)
• Moving skill directories can break scripts that reference the old path

Step 5: Do the Work

Ordered by risk (lowest first):

1. Delete dead weight. Empty directories, archived skills, ghost registry entries.
2. Fix hardcoded paths. Replace /Users/<username> with $HOME (bash) or os.path.expanduser("~") (Python heredocs).
3. Extract triggers into skills. Move full protocol from CLAUDE.md to SKILL.md. Leave keyword stubs in CLAUDE.md.
4. Fix skill health. Add missing frontmatter fields, error recovery docs, dependencies sections.
5. Build the manifest. Catalog every component into system-manifest.json.

Step 6: Review (PRISM)

Run PRISM on the new/modified skills and the manifest schema. Check for:

• Completeness (does the manifest capture everything?)
• Consistency (are fields used the same way across types?)
• Broken references (stubs pointing to non-existent skills)

Step 7: Bug Hunt (EyeOfHorus)

Run before shipping. Check:

• bash -n on all modified scripts
• YAML validity on all SKILL.md files
• No remaining hardcoded paths
• Manifest is valid JSON
• No broken references to deleted/moved components

Step 8: Commit

Stage and commit all changes. Push to git.

Step 9: This Step

You just ran this skill. The output is the audit. The audit is the skill. Recursion with ambition.

Manifest Schema

{
  "meta": {
    "version": 1,
    "generated": "YYYY-MM-DD",
    "generator": "system-audit",
    "component_count": N
  },
  "components": [
    {
      "name": "string",
      "type": "skill|script|cron|hook|trigger|oc-job|agent",
      "path": "string (relative to ~) or null",
      "description": "one line",
      "dependencies": ["other component names"],
      "platforms": ["claude-cli", "openclaw", "cowork", "any"],
      "primitive": "string or null",
      "health_score": "number or null (skills only, out of 14)",
      "context_weight_bytes": "number or null (skills only)",
      "portability": "portable|cli-only|macos-only|partial",
      "status": "active|disabled|archived|dead",
      "schedule": "crontab expression (crons/oc-jobs only)",
      "hook_event": "SessionStart|SessionEnd|PostToolUse|PreToolUse (hooks only)"
    }
  ]
}

Portability

This skill works in Claude Code, Cowork, or any agent that can launch subagents and read/write files. The audit targets (skills, scripts, crons, hooks) are standard Claude Code / OpenClaw infrastructure. Adapt the scan paths for other setups.

Error Recovery

• If a subagent fails, re-run just that step. Each step is independent once its prerequisites are met.
• If the manifest has invalid JSON, run python3 -c "import json; json.load(open('path'))" to find the error.
• If bash -n fails on a script, the hardcoded path fix likely broke a heredoc. Check for $HOME inside single-quoted heredocs.

Origin

Built from a live audit session, 2026-04-06. Dustin Pollock and EOM ran the full pipeline by hand, recorded every step, then packaged the recording as this skill. The process wrote itself.

Inspired by jeremyknows/watson-toolkit (packaging model) and jeremyknows/claude-context-audit (context weight methodology).