repo-audit
Skill9 starsChanged 24 days agoMITView on GitHub
Audit a repo across four dimensions — uniqueness and selling point, philosophy-to-implementation coherence, setup and doc effectiveness, and codebase quality (DRY, KISS, SRP, composition). Invoke when asked to review, assess, or health-check a repo.
24 other projects use a version of this.
Adopted by
Most recently taken up by
- albkhachikyan/claude-code-repo-audittheir own version, first seen Nov 15, 2026
- iuliandita/skillstheir own version, first seen Nov 15, 2026
- idaibin/skillstheir own version, first seen Nov 8, 2026
- TheVeller/claude-skillstheir own version, first seen Nov 2, 2026
- ekajaya740/skillstheir own version, first seen Nov 1, 2026
- 0xUrsanomics/utopia-ostheir own version, first seen Nov 1, 2026
Used with
Projects with it also use handoff and code-review.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
MicrosoftSkillhandoff
Compact the current conversation into a handoff document for another agent to pick up.
Also in 3 projects that use this
GoogleSkillcode-review
Adversarial systems, concurrency, memory-model, and architecture code review protocol. Use this skill whenever asked to review code, PRs, diffs, or branches in Filament.
Also in 3 projects that use this
Other versions24 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 24
- zebbern/claude-code-guide★ 4.7ksame name
- Kanevry/session-orchestrator★ 53same name
- iuliandita/skills★ 12same name
- Megaprompting/torque-loop★ 10same name
- idaibin/skills★ 6same name
- my-chiefmind/ai-maestro★ 6same name
- nikkogibler/cabinet★ 4same name
- TheVeller/claude-skills★ 4same name
- conorbronsdon/repo-audit★ 3same name
- 0xUrsanomics/utopia-os★ 2same name
14 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository22 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- ai-auditSkill
- bulk-readSkill
- canon-slidesSkill
- captureSkill
- context-checkSkill
- context-doctorSkill
- dead-code-cleanupSkill
- doc-auditSkill
- learnings-sweepSkill
- mikadoSkill
- mutation-testSkill
- output-validatorSkill
- promote-learningsSkill
- pr-reviewSkill
- repo-workflow-auditSkill
- sdlc-auditSkill
- skill-evalSkill
- skill-exportSkill
- sprintSkill
- wrapupSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 7 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 20 edited versions we read keep these.
7
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
Read these in order, stop when you have enough to answer each dimension:
- Distinctive: line 23
Do not read everything. Read until you can answer the questions for each dimension.
- Distinctive: line 41
Goal: Verify the implementation honors the philosophy — not just in words, but in every command, tool, and convention.
- Distinctive: line 49
If the README's stated feature count or command surface contradicts the actual implementation, flag it here as a coherence failure (and …
- Distinctive: line 51
Look for: philosophy stated but not implemented, implementation that outgrew its stated scope, or a tool that claims minimalism but adds …
- Distinctive: line 63
Do examples exist? Do they match current behavior?
- Distinctive: line 66
When step N fails, is there a recovery path — or does the guide end there?
- Very specific: line 97
Use this structure exactly.
“Common” is measured: kept by at least 6 in 10 of the 20 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Repo Audit
A four-dimension analysis. Run from any project directory — the audit reads the repo under analysis, not canon. Produces an inline report and always writes or updates the latest report at critique/canon-critique.md in the repo under analysis, with the audit run DateTime as the first line.
Before Auditing
Read these in order, stop when you have enough to answer each dimension:
README.md— value prop, install path, stated audience- Philosophy/design doc (
docs/how-it-works.md,DESIGN.md,ARCHITECTURE.md, or ADRs if present) - Primary setup/install guide
CONTRIBUTING.md(if present)- 3–5 core source files (main CLI entrypoint, core logic) — skip test fixtures, generated files,
node_modules,dist
Do not read everything. Read until you can answer the questions for each dimension.
Dimension 1 — Uniqueness and Selling Point
Goal: Determine whether the repo has a clear, genuine differentiator — and whether it lands for the target user.
Questions to answer:
- What is the stated purpose? Who is the target user?
- What problem does it solve, and for whom?
- What alternatives exist? Name them. What does this repo do that they don't?
- What is genuinely novel vs. table stakes?
- Does the README earn its differentiation claim, or does it assert without showing?
- Would the target user read this and say "finally" — or "so what"?
Rate: Distinct / Murky / Generic
Dimension 2 — Philosophy-to-Implementation Coherence
Goal: Verify the implementation honors the philosophy — not just in words, but in every command, tool, and convention.
Questions to answer:
- What is the repo's stated philosophy? Extract it explicitly from the docs. If no dedicated philosophy doc exists (no
DESIGN.md,ARCHITECTURE.md,docs/how-it-works.md, or ADRs), extract fromREADME.mdinstead — and note the absence as a finding. The missing doc is a finding, not a stop condition; proceed with best-effort ratings for all four dimensions. - Does the implementation honor it? Check: command surface size, complexity vs. claimed simplicity, patterns in core code
- Does the usage pattern (workflows, commands, default behaviors) reflect the philosophy?
- Where does the implementation contradict or silently undermine the stated philosophy?
- Are there features that have crept in and violated it?
- If the README's stated feature count or command surface contradicts the actual implementation, flag it here as a coherence failure (and also in Dimension 1 as a positioning gap).
Look for: philosophy stated but not implemented, implementation that outgrew its stated scope, or a tool that claims minimalism but adds flags for every edge case.
Rate: Strong / Drifting / Contradicted
Dimension 3 — Setup and Doc Effectiveness
Goal: "Can a newcomer get from zero to working using these docs?" Focus on the user journey, not per-claim accuracy. (Per-claim accuracy → doc-audit.)
Questions to answer:
- Is there a clear, tested install path? Can you follow it cold, without prior knowledge?
- Are prerequisites explicit before they're needed — not buried mid-guide?
- Is the first success moment reachable without hitting a wall? How many steps?
- Do examples exist? Do they match current behavior?
- Is the docs structure navigable? Can you find what you need without reading everything?
- Are there implicit environment assumptions (OS, shell, global tools)?
- When step N fails, is there a recovery path — or does the guide end there?
Rate: Clear / Gaps / Broken
Dimension 4 — Codebase Quality
Goal: Assess how well the codebase follows SDLC principles adapted for the repo's paradigm (shell, markdown, CLI, agents — not OOP).
Principles to apply (map to what's present, skip what isn't applicable):
| Principle | In shell/CLI/agent context |
| SRP (Single Responsibility) | Each script/tool/skill does one thing; no file with multiple unrelated jobs |
| DRY (Don't Repeat Yourself) | Each fact has one canonical location; logic isn't duplicated across scripts |
| KISS (Keep It Simple) | Scripts are as simple as they could be; no abstractions that could be a one-liner |
| YAGNI (You Ain't Gonna Need It) | No unused flags, config options, or features not yet needed |
| Composition over commands | Complex operations built from smaller composable units, not monolithic multi-step scripts |
| CoC (Convention over Configuration) | Conventions established and followed; explicit config only where necessary. For canon-managed content markers in shared files (AGENTS.md, HANDOFF.md, etc.): new markers should follow <!-- canon:<name>:BEGIN/END --> (see standards/skill-setup-std.md); flag any new ad-hoc marker naming that doesn't follow it. AI-SKILLS/MODEL-TIERS are documented exceptions predating the convention — not a violation. |
| Separation of concerns | Config vs. logic, data vs. behavior, CLI vs. agent, state vs. judgment — each in its place |
| Context efficiency (AI-native repos) | Always-loaded files are lean; skills have tight activation; no content duplication across imports. In skill files specifically: no summary: frontmatter field when description: already covers it; no --- horizontal rules (visual noise in injected context); no step that duplicates another step's outcome |
Questions to answer:
- Find the 3 most significant violations. Name them as
file:line: problem. fix. - Is there structural complexity that compounds failure (shared mutable state, side-effects in unexpected places)?
- Does the complexity of the codebase match the complexity of the problem it solves?
- Is the separation of concerns clean, or do concerns bleed into each other?
Rate: Clean / Acceptable / Needs Work
Report Format
Use this structure exactly. Omit sections that aren't applicable. After composing the report, ensure critique/ exists and write the same report to critique/canon-critique.md, replacing the prior contents so the file is the latest critique snapshot.
The first line must always be the local DateTime when the audit ran, formatted as MM-DD-YYYY hh:mm AM/PM:
Audit run: MM-DD-YYYY hh:mm AM/PM
Audit run: MM-DD-YYYY hh:mm AM/PM
## Repo Audit: <repo-name>
### 1. Uniqueness / Selling Point — [Distinct | Murky | Generic]
- <finding>
- <finding>
Recommendation: <one actionable sentence>
### 2. Philosophy Coherence — [Strong | Drifting | Contradicted]
Stated philosophy: <extract — quote or paraphrase from source file>
- <specific example of coherence or drift>
- <specific example of coherence or drift>
Recommendation: <one actionable sentence>
### 3. Docs Effectiveness — [Clear | Gaps | Broken]
Zero-to-working: <yes/no + rough step count or time estimate>
- <specific friction point or win>
- <specific friction point or win>
Recommendation: <one actionable sentence>
Note: per-claim accuracy → run doc-audit
### 4. Codebase Quality — [Clean | Acceptable | Needs Work]
- file:line: problem. fix.
- file:line: problem. fix.
- file:line: problem. fix.
Recommendation: <one actionable sentence>
### Summary
Overall: [Healthy | Minor gaps | Needs attention]
Top priority: <the one thing to address first, and why>Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

