Brooks Audit Agent Skill

> Architecture audit that maps module dependencies, checks layering integrity, and flags structural decay across a codebase, drawing on twelve classic engineering books. check for circular imports, understand how the codebase is organized, or asks "does this follow clean architecture?" or "why does everything depend on everything?". or "give me a codebase tour" (use onboarding mode). questions — this skill analyzes structural/module-level concerns, not individual functions.

3k tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

1313

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/hyhmrright/brooks-lint --skill brooks-audit

What comes with it

11 452 bytes besides the instruction

architecture-guide.md

onboarding-guide.md

The instruction itself

3 sections, as written by the author

Brooks-Lint — Architecture Audit

Setup

Read in order:

../_shared/common.md — Iron Law, Project Config, Report Template, Health Score
../_shared/source-coverage.md — book coverage, exceptions, tradeoffs
../_shared/decay-risks.md — symptom definitions and source attributions
architecture-guide.md (this directory) — the audit framework

Process

Onboarding mode: If the user asks for an onboarding report, codebase tour, or

"explain this codebase to a new developer", read onboarding-guide.md from this

directory and follow it instead of architecture-guide.md. This mode explains rather

than diagnoses — no Health Score, no Iron Law findings.

Scope: if the user did not specify files or a directory, apply Auto Scope Detection

(../_shared/common.md) first.

Gather codebase context and draw the module dependency graph as Mermaid (Steps 0–1 of the guide)
Scan for each decay risk in the order specified (Steps 2–4 of the guide)
Assign node colors in the Mermaid diagram based on findings (red/yellow/green) — after Step 4
Run the Testability Seam Assessment (Step 5 of the guide)
Run the Conway's Law check (Step 6 of the guide)
Output using the Report Template from common.md — Mermaid graph FIRST, then Findings

Mode line in report: Architecture Audit

How to use it

Copy the folder

Take hyhmrright/brooks-audit from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.