Not a linter. Not a security scanner. An architectural MRI.
Finds the structural bugs that survive tests and code review: data format mismatches at module boundaries, parallel implementations that silently diverge, pipeline bypasses that skip validation, and untyped contracts between modules that let bugs pass through undetected.
Built for mature codebases (10k+ lines) that have grown organically — where "it works but we keep finding weird bugs" is the symptom.
| Issue Class | Example |
|---|---|
| Data format disagreements | Module A outputs email_addresses but Module B expects email — silently breaks dedup |
| Parallel implementations | Two code paths create the same record with different defaults |
| Pipeline bypasses | A shortcut path skips validation that the main path enforces |
| God modules | 1,400-line file handling 12 responsibilities |
| Untyped contracts | dict[str, Any] flowing between modules — format bugs invisible until runtime |
| Duplicate definitions | Same function defined in 2 places, slowly diverging |
Five phases, each building on the last:
- Map — Every module's responsibility, imports, data formats in/out
- Trace — Data flows end-to-end through every pipeline
- Seam Analysis — Check every module handoff for format mismatches; build a pipeline completeness matrix; run the "same input, different output" test on parallel paths
- Find — Systematic search for 10 issue classes (format disagreements, parallel implementations, dead code, bypasses, god modules, duplicates, untyped contracts, circular deps, inconsistent error handling, naming inconsistencies)
- Assess — Health rating per module (🟢/🟡/🔴), fixes ranked by impact × effort
Drop the SKILL.md file into your skills directory:
# OpenClaw
cp SKILL.md ~/.openclaw/workspace/skills/code-audit/SKILL.md
# Claude Code
cp SKILL.md ~/.claude/skills/code-audit/SKILL.mdOr install the .skill package:
# Download the latest release
curl -LO https://github.com/ameet/code-audit-skill/releases/latest/download/code-audit.skillThe methodology in SKILL.md works with any AI coding agent that reads markdown instructions. Copy the file into your agent's context or skills directory.
Just ask your agent:
- "Audit this codebase"
- "Review the architecture"
- "Map the codebase and find issues"
- "What's wrong with this code?"
- "Do a health check on this repo"
For large codebases, spawn as a background task:
Perform a comprehensive architecture review of /path/to/code.
Phase 1: Map every module — what it owns, imports, expects, produces.
Phase 2: Trace data flows end-to-end for the key pipelines.
Phase 3: Seam analysis — check every module handoff for format mismatches,
build pipeline completeness matrix, test parallel paths.
Phase 4: Find format disagreements, parallel implementations, dead code,
pipeline bypasses, god modules, duplicate definitions, untyped contracts.
Phase 5: Rate each module (🟢/🟡/🔴), rank fixes by impact × effort.
Write the full report to ./architecture-review.md.
The audit produces a structured markdown report:
- Architecture Map — tree view with one-line descriptions
- Module-by-Module Assessment — health rating, issues, recommendations
- Data Flow Diagrams — ASCII diagrams for each major pipeline
- Pipeline Completeness Matrix — which entry points go through which steps
- Cross-Cutting Issues — problems that span modules
- Priority Fixes — ranked by impact × effort
- Summary Stats — files, lines, health distribution
Generic code review tools check style, lint rules, and known vulnerability patterns. They're useful but shallow.
The bugs that actually break production in complex systems live at the seams — where modules hand off data to each other. When Module A outputs {"email_addresses": [...]} but Module B expects {"email": "..."}, no linter catches that. Tests pass because each module works in isolation. The bug only manifests when real data flows through the full pipeline.
This skill finds those bugs by doing what humans do when they're really good at code review: reading the code, tracing the data, and checking the seams.
Issues and PRs welcome. The methodology is designed to evolve — if you find new issue classes or better heuristics, please contribute them.
MIT