agentleFS
sunitghubsunitghub/canon-skills/skills/repo-audit/SKILL.md

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

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.
  • MicrosoftSkill

    handoff

    Compact the current conversation into a handoff document for another agent to pick up.

    Also in 3 projects that use this

  • GoogleSkill

    code-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

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
  1. Distinctive:

    Read these in order, stop when you have enough to answer each dimension:

    line 15
  2. Distinctive:

    Do not read everything. Read until you can answer the questions for each dimension.

    line 23
  3. Distinctive:

    Goal: Verify the implementation honors the philosophy — not just in words, but in every command, tool, and convention.

    line 41
  4. Distinctive:

    If the README's stated feature count or command surface contradicts the actual implementation, flag it here as a coherence failure (and …

    line 49
  5. Distinctive:

    Look for: philosophy stated but not implemented, implementation that outgrew its stated scope, or a tool that claims minimalism but adds …

    line 51
  6. Distinctive:

    Do examples exist? Do they match current behavior?

    line 63
  7. Distinctive:

    When step N fails, is there a recovery path — or does the guide end there?

    line 66
  8. Very specific:

    Use this structure exactly.

    line 97

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. README.md — value prop, install path, stated audience
  2. Philosophy/design doc (docs/how-it-works.md, DESIGN.md, ARCHITECTURE.md, or ADRs if present)
  3. Primary setup/install guide
  4. CONTRIBUTING.md (if present)
  5. 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 from README.md instead — 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):

PrincipleIn 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 commandsComplex 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 concernsConfig 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>

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.