audit

What this skill does

Runs the Four Cs Audit on the current Claude Code project. Reads (never writes) the project's operating manual, memory, skills, agents, MCPs, decisions, and references. Scores each of the Four Cs out of 25. Surfaces strengths and the top 3 leverage-weighted gaps with concrete next-step commands.

Scope is structural — "is the AIOS built right?" It is NOT a capability planner. Capability gaps ("you could build a daily brief if you connected calendar") belong to /level-up. The audit answers: are the files, folders, registries, and connections in good shape?

First run is the baseline. Re-run weekly to watch the score climb. That's the compounding hook.

Today's context

• Date: !date +%Y-%m-%d
• Project root: the current working directory

The Four Cs (scored 25 each = 100 total)

Execution

Step 1: Discover the project shape

The audit looks for patterns and intent, not exact paths. File names vary. Use Glob and Read to check:

Operating manual: CLAUDE.md (root), CLAUDE.local.md (gitignored). Memory: MEMORY.md (root), ~/.claude/projects/<id>/memory/MEMORY.md, or memory/ folder. Skills: .claude/skills/*/SKILL.md — count + frontmatter. Agents: .claude/agents/*.md — count + frontmatter. Connection mechanisms (any of these = "reachable"):

• MCPs: .mcp.json, .claude/settings.json (mcpServers key), .claude/settings.local.json
• API scripts: scripts/*.py|.js|.ts documented in CLAUDE.md
• Export pipelines: data/, imports/, exports/ with refresh script + last-run timestamp
• API keys + reference guide: .env entries + corresponding references/{tool}-api.md

Connections registry: connections.md (anywhere). Reference guides: references/{tool}-api.md, references/*-reference.md, or equivalent. Decisions: decisions/log.md, decisions.md, or any append-only decisions file. References / SOPs: references/, docs/, sops/ folders. Templates: templates/, .claude/templates/. Hooks / scheduled jobs: .claude/settings.json hooks key, or skill names matching morning-*, weekly-*, daily-*, monthly-*, standup.

Don't penalize for non-canonical names if equivalent intent is captured elsewhere.

Step 2: Score each C (25 points each)

Context (25 pts)

Connections (25 pts) — domain-aware, mechanism-agnostic

A "reachable" connection counts via ANY mechanism: MCP, script, export pipeline, or .env key + references/{tool}-api.md. The kit is API-first; the audit doesn't prefer MCPs.

The 7 Tier-1 Universal Data Domains:

Tier-2 (bonus): AI service API keys (OpenRouter, Anthropic, OpenAI), decisions/history, content/publishing.

Capabilities (25 pts)

Cadence (25 pts)

North-Star trend metric — the one-window KPI (reported beside the Cadence score, not scored). "What percentage of my work can I do from this window right here?" — the AIOS-maturity number (Nate Herk, 2026-07-11 6h course; doctrine in references/four-cs.md § Cadence). Measure it when the project ships the estimator (Servy does): python3 scripts/skill-harvest.py --share --days 14 prints the two honest proxies from real transcripts — skill-mediated share of in-Servy work + unattended-session share. Transcripts can't see work done OUTSIDE the window, so also ask the user for their subjective % and record both. Track the trio across audits; a rising trend is the compounding hook made visible.

Step 2.5: Hygiene checks (advisory — always reported, never scored)

Two checks added 2026-07-11 (Nate 6h course). They ride project-local helpers — run what's present, skip silently what isn't. Advisory findings ARE eligible for the Top 3 Gaps list (Step 3): rank a hygiene finding as if it lost 3 points, key-hygiene flags at 1.5× (keys-not-prompts is security, not cosmetics).

a) Context hygiene. Grade the setup against references/claude-code-context-management.md § "The discipline checklist" (the page names /audit as its grader). Check the statically checkable items and report pass/fail: CLAUDE.md byte budget (wc -c CLAUDE.md — target <16 KB, hard cap 24 KB), statusline configured (statusLine in .claude/settings.json), .claudeignore where bulky folders exist, MCP surface lean (~18k tokens per server per message), noisy-command denies where the project warrants them. Then the fresh-session baseline: Claude can't run /context itself, so ask the user for the /context figure from a fresh session and compare against the recorded datapoints on that wiki page (~30-40k blank floor / Nate's 51k / older 62k). Offer to log the figure as a dated datapoint on that page — consent-gated, since it's a write beyond the report.

b) Key hygiene. Run python3 scripts/key-hygiene.py (read-only; prints key NAMES only, never values). It inventories env-file key names against connections.md and flags per the ElevenLabs scoped-key checklist in references/four-cs.md (name-per-purpose · credit-cap · endpoint-cap): unregistered, not-named-per-purpose, no-cap-noted, no-scope-noted. Report the counts; the cap/scope flags are proxies (annotations, not provider state) — the fix is provider-side scoping, then annotate the env line or the connections.md row.

Step 3: Identify top 3 gaps by leverage

For each criterion that lost points: leverage = (points lost) × (impact multiplier).

Impact multipliers:

• 0 tier-1 domains reachable: 4x (AIOS is blind to the business)
• Operating manual missing or thin: 3x (foundation)
• ≤2 tier-1 domains reachable: 3x (Connections is the gateway to live data)
• 0 skills: 2x (no Capabilities = no AIOS)
• No recurring trigger: 2x (no Cadence = no autonomy)
• All connections read-only: 2x (viewer, not an OS)
• 0 reference guides for connected tools: 1.5x (every future skill re-researches the same APIs)
• No decisions log: 1.5x
• All others: 1x

Sort gaps by leverage descending. Take top 3. For each, write a one-line concrete next step:

• Need a new skill? Recommend skill-creator (Anthropic) or skill-builder (if local), or "write SKILL.md at .claude/skills/<name>/SKILL.md with YAML frontmatter."
• Need to log a decision? "Append to decisions/log.md."
• Need to reach a tier-1 domain? Prefer API+script (write scripts/{tool}_api.py + save references/{tool}-api.md). Recommend claude mcp add only if no API path exists.
• Connected tool missing a reference guide? "Research the API once, save endpoints + auth + common queries to references/{tool}-api.md."
• Need a recurring trigger? "Add a hook to .claude/settings.json, or write a skill named daily-* you run each morning."

Step 4: Output the report

Print directly in chat (Markdown). Format:

# AIOS Audit — {date}
**Score: {total}/100** ({stage})

Stage thresholds:
- 0-39 → Stage 0: Foundation
- 40-69 → Stage 1: Built
- 70-89 → Stage 2: Compounding
- 90-100 → Stage 3: Autonomous

## Scoreboard

Context        {bar}  {n}/25  {label}
Connections    {bar}  {n}/25  {label}
Capabilities   {bar}  {n}/25  {label}
Cadence        {bar}  {n}/25  {label}

(bar = ## per 5pts; label = "Strong" ≥20, "Solid" 15-19, "Thin" 8-14, "Missing" <8)

One-window KPI: {skill-mediated}% skill-mediated · {unattended}% unattended · user's own estimate {pct or "not asked"} ({trend vs last audit, if a prior report exists})

## Hygiene (advisory)
- Context: {passed}/{checked} discipline-checklist items pass; fresh-session baseline {tokens, or "ask the user for /context"}
- Keys: {flagged}/{total} keys flagged ({unregistered} unregistered · {no-cap} no-cap-noted · {no-scope} no-scope-noted) — names only

(Omit whichever hygiene line has no helper/data in this project.)

## Strengths
- {1-3 short bullets from highest-scoring criteria}

## Top 3 Gaps (ranked by leverage)
1. **{gap name}** (-{points} × {multiplier})
   → {concrete next-step}
2. **{gap name}** (-{points} × {multiplier})
   → {concrete next-step}
3. **{gap name}** (-{points} × {multiplier})
   → {concrete next-step}

## Suggested next: {single most leveraged action}

---
Structural gaps only. To explore CAPABILITY gaps (what your AIOS could DO that it can't yet), run /level-up after this audit.

Step 5: Offer to save the report

After printing, ask: "Save this audit to audits/audit-{date}.md so you can track score over time?" If yes, write it (creating audits/ folder if needed). The only other writable side effect is the consent-gated /context datapoint from Step 2.5a.

Notes

• Read-only by default. Never modify CLAUDE.md, memory, skills, or any project files. Optional writes are exactly two, both consent-gated: the audit report, and the fresh-session /context datapoint on the context-management wiki page (Step 2.5a).
• Be flexible about file names. Don't penalize for using non-canonical names if intent is captured.
• Be honest, not generous. A 95/100 is a flex. Most setups land 40-70.
• Don't suggest skills that don't exist. Point at what's actually available.
• Speed matters. Report in under 60 seconds wall-clock. Read targeted files, count skill folders without reading each fully (frontmatter only).
• Cadence detection is fuzzy. Infer from skill names if hooks/cron data isn't cleanly available.