# System Audit

> Full system audit for AI agent setups. Inventories skills, scripts, crons, hooks, agents. Scores health, measures context weight, maps dependencies, checks portability. Outputs a machine-readable manifest.

- Skill: `cogpros/system-audit` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add cogpros/system-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cogpros/system-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: cogpros (https://skillmd.com/u/cogpros)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cogpros/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

```json
{
  "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).