gustavo-meilus Auditing agent onboarding files
Static + cross-reference linter for instruction-file smells. Read-only: this
skill never writes files. It produces a findings report; applying fixes is
update-agent-onboarding's job (content) or the user's (structure).
Announce at start: "Using audit-agent-onboarding to lint the onboarding files."
Usage: audit-agent-onboarding [--stats]
--stats: compression receipts
Read .aiboarding/state.json:receipts and render a table: file, level, bytes and
lines before/after, percent saved, measured-at. Label token figures approximate
when the receipt does (they are byte/4 estimates unless a real tokenizer produced
them). Since instruction files load every session, per-session savings compound -
present "per-session saved × sessions" only as a clearly labeled estimate. For each
receipt, render optional high_consequence_regions evidence as location, category,
outcome (preserved or rewritten), and explicit opt-in status, without instruction
text. Render an empty array as none; when field is absent, render not recorded.
Keep existing level, byte, line, date, and token output unchanged. Then stop.
Evidence-aware audit
Run .aiboarding/tools/audit-onboarding-evidence <repo-root> first (fallback:
the plugin's templates/tools/audit-onboarding-evidence). Capture its lines and
exit status. Exit 0 means no computed FAIL; 1 means computed validation FAIL;
2 is an operational error: stop and report tooling failure, never render it as an
audit finding. Do not write onboarding files in either case.
Each finding has independent severity (FAIL, WARN, INFO) and provenance
(computed, inferred). Preserve validator provenance and render one report
ordered FAIL, WARN, INFO. Never upgrade model judgment to computed.
| Category | Evidence |
|---|---|
| Local size budget; Codex project-chain budget; wrapper integrity | Computed |
| Stale commands | Mixed: validator only for explicit paths, package scripts, Make/Just targets; infer unresolved context-dependent cases |
| Duplication; contradictions; vague commands; missing sections; skill leakage; lint leakage; rules extraction candidates; unsafe content | Inferred |
Then review inferred categories and unresolved command references across AGENTS.md,
CLAUDE.md, and .claude/rules/*.md:
- Duplication - imported or README content restated meaningfully.
- Contradictions - instructions whose scope or intent conflicts.
- Stale commands - only commands validator cannot prove absent.
- Vague commands - imperative guidance lacking usable invocation.
- Missing sections - absent guardrail or verification guidance, not headings alone.
- Skill/lint leakage and rules extraction candidates - ownership and scope need judgment.
- Unsafe content - secrets and destructive-command framing need context; do not quote secrets.
Report
Output findings ordered FAIL → WARN → INFO, each with provenance, file, location, one-line rationale, and concrete fix. Example:
FAIL [computed] wrapper-integrity CLAUDE.md:1 — missing @AGENTS.md import; add it.
WARN [computed] size-budget AGENTS.md:1 — 24001 bytes > budget 24000; compress it.
WARN [inferred] vague-commands AGENTS.md:8 — "run tests" lacks invocation; name command.
End with one-line verdict and handoff: content fixes → offer
update-agent-onboarding (approval gate applies); compression fixes →
compress-onboarding. Suggestions are never auto-applied.