review-structure
Skill2 starsChanged 4 months agoMITView on GitHub
Audit a non-technical repo's folder structure for agent-navigability and propose a refactor plan. TRIGGER when user says "review structure", "audit folders", "audit my repo", "check organization", "is my repo agent-friendly", "clean up structure", or runs "/review-structure".
- Reads credentials
In this repository13 other files it gives its agents.
- claude-mdSkill
- commit-pushSkill
- create-cliSkill
- debug-agentSkill
- domain-modelingSkill
- grillingSkill
- grill-with-docsSkill
- handoffSkill
- helpSkill
- prototypeSkill
- schedule-tasksSkill
- skill-masterSkill
- wayfinderSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
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
- Very specific: line 32
Sibling folders mirror each other's shape: If every client folder has profile.md, contacts.md, updates.md, then Glob clients/*/profile.md …
- Distinctive: line 40
Subdirectory
CLAUDE.md: default is none: Only add one when the folder carries implicit context that names can't convey. - Distinctive: line 130
Stop asking once you have what you need to audit confidently.
- Distinctive: line 182
If the audit finds no issues, say so plainly:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Review Structure
You are auditing the user's repo so that you (Claude) can navigate it cold and operate inside it effectively. The user is non-technical — they don't search this repo, you do. Every principle below comes from how your own search tools actually work.
How you search a repo
Internalize this before auditing — every principle downstream is a consequence of these mechanics.
Read— load a known file by path. First move on entry: read rootCLAUDE.mdorREADME.md.Glob— pattern-match file paths. Case-sensitive, literal. e.g.**/CLAUDE.md,clients/*/profile.md.Grep— search file contents, usually scoped with--glob.Bash: ls / find— see directory shape, not content. e.g.find . -type d -maxdepth 2.CLAUDE.mdauto-loading:- Ancestor
CLAUDE.mdfiles (root + dirs above cwd) load at session start. - Subdirectory
CLAUDE.mdfiles load lazily, only when youRead/Edita file in that subtree. They do not fire onGlob,Grep, orls.
- Ancestor
The corollary: a subdirectory CLAUDE.md cannot rescue bad names. Naming carries navigation; CLAUDE.md only carries non-obvious context once you've already decided to open a file.
Principles (the audit checklist)
- Self-describing names. A cold reader (you) should infer content from the path alone.
data/says nothing;sales/pipeline.csvsays everything. Naming is your primary navigation aid because Glob/Grep see paths, not CLAUDE.md. - Lowercase kebab-case —
acme-corp/, notAcme Corp/orAcmeCorp/. This is mechanical, not aesthetic: spaces break shell commands, casing breaks Glob patterns. - Group by domain, not by file type. Folders are business areas (
sales/,clients/,operations/), not file kinds (templates/,data/,scripts/). Domain grouping lets you ignore irrelevant subtrees entirely; file-type grouping forces you to load everything. - Sibling folders mirror each other's shape. If every client folder has
profile.md,contacts.md,updates.md, thenGlob clients/*/profile.mdpulls all profiles in one call. If shapes vary, you have toReadeach folder to discover what's there. - Shallow + wide over deep + narrow. Three levels (root → domain → leaf) is comfortable. Five-deep generic nesting (
stuff/items/things/2024/q1/) gets lost. Glossary for user-specific vocabulary. Keep an
agent-docs/glossary.mdfile (in anagent-docs/directory at the repo root, alongside other progressive-disclosure docs likearchitecture.md,conventions.md, etc.) for terms specific to the user's world that Claude can't infer — internal client codenames, industry acronyms, custom workflow names ("V2 brief", "the rolodex"), team shorthand. The rootCLAUDE.mdmust include this self-perpetuating rule:"When the user uses a term you don't understand, check
agent-docs/glossary.mdfirst. If the term isn't there, ask the user to clarify, then add the definition there."Why a separate file (not inline in
CLAUDE.md): the glossary keeps growing as the user works; a dedicated file stays manageable and only loads when needed. Why the rule lives in rootCLAUDE.md: that file auto-loads at session start, so Claude always knows where to check and how to maintain the glossary — even though the glossary itself is read lazily, only when an unfamiliar term appears. Whyagent-docs/: the convention from theclaude-mdskill — all progressive-disclosure docs live there, keeping the root tidy.- Root
CLAUDE.mdalways. It's the entry interface — what the repo is, how the domains connect, where to go for what. Subdirectory
CLAUDE.md: default is none. Only add one when the folder carries implicit context that names can't convey. Conditions that justify one:- Behavioral rules that apply to every file in the subtree — e.g. brand voice in
marketing/, citation style inresearch/. Auto-loading the rule means Claude can't forget it when editing files inside. - Per-instance context that varies — e.g. each client folder has its own engagement history, contacts, recent decisions.
- Domain rules Claude can't infer from file names — pricing logic, pipeline stages, judgment calls, things-to-watch-for.
- Naming conventions that operate inside the folder — e.g. "files prefixed
draft-are not yet reviewed."
Skip when the folder's shape and names already explain themselves. An empty-restating
CLAUDE.mdis dead weight and trains Claude to skim past them.- Behavioral rules that apply to every file in the subtree — e.g. brand voice in
- No orphaned business content. Business files (proposals, client notes, pricing data, templates, scripts that operate on your data) belong inside a domain folder. Conventional root-level files —
README.md,CLAUDE.md,.gitignore,.env,package.json,pyproject.toml,LICENSE, plus Claude-infrastructure dirs (.claude/,agent-docs/) and other hidden config dirs (.github/) — are expected at root and don't count as orphans.
Teaching example
The same business, organized two ways:
Wrong — grouped by file type:
my-business/
├── CLAUDE.md
├── templates/
│ ├── proposal-template.md
│ ├── invoice-template.md
│ └── campaign-brief.md
├── data/
│ ├── client-list.csv
│ └── pipeline.csv
├── docs/
│ ├── sales-process.md
│ ├── brand-guidelines.md
│ └── pricing.md
└── scripts/
├── generate-invoice.py
└── send-proposal.pyAsked to "draft a proposal for Acme Corp," you have to hunt across templates/, docs/, data/, and scripts/ and load it all to figure out what's relevant. No domain boundaries. No place to put domain context that auto-loads when you open a sales file.
Right — grouped by domain:
Note: not every folder needs a CLAUDE.md — only the ones with implicit context that names can't carry (see Principle 8). Folders whose shape and names speak for themselves get none.
my-business/
├── CLAUDE.md ← what this repo is, how domains connect; rule: ask + add to agent-docs/glossary.md
├── agent-docs/
│ └── glossary.md ← user-specific vocab, grows over time, read lazily
├── sales/
│ ├── CLAUDE.md ← pricing rules, pipeline stages (domain rules Claude can't infer)
│ ├── templates/
│ ├── pipeline.csv
│ └── scripts/
├── clients/ ← no CLAUDE.md: every client folder mirrors the same shape, Glob discovers it
│ ├── acme-corp/
│ │ ├── CLAUDE.md ← per-client engagement context, contacts (varies per instance)
│ │ ├── profile.md
│ │ ├── contacts.md
│ │ └── updates.md
│ └── beta-inc/
│ ├── CLAUDE.md
│ ├── profile.md
│ ├── contacts.md
│ └── updates.md
├── operations/ ← no CLAUDE.md: `sops/` and `templates/` are self-explanatory
│ ├── sops/
│ └── templates/
└── marketing/
├── CLAUDE.md ← brand voice (behavioral rule that applies to every file written here)
├── brand-voice.md
└── templates/Same task: read root CLAUDE.md → sales/CLAUDE.md → clients/acme-corp/CLAUDE.md. You never touch operations/ or marketing/. Each domain CLAUDE.md auto-loads when you open files in its subtree, so domain rules ride along with the work — and folders without one stay out of the way.
Workflow
- Map the repo.
Thenls find . -type d -maxdepth 3 -not -path '*/.*' -not -path '*/node_modules/*'Glob **/CLAUDE.mdandReadthe rootCLAUDE.md. Clarify before auditing — one question at a time. After mapping, you'll have inferences but also gaps. Fill them through
AskUserQuestion. Ask one question, propose a recommended answer with a one-line reason, wait for the response before asking the next. Each answer informs the next question — never batch. The user is non-technical; foreign-looking folder names may be meaningful domain terms to them, and only they can tell you which.Common questions to walk in this order (skip any that are already obvious from the repo):
- Domain confirmation — "I see [list]. Are these your main business areas?" Recommend the inferred list with a one-line reason; let user correct, add, or merge.
- Ambiguous folders — for any folder whose purpose isn't clear from the name, ask what lives in it and whether it belongs inside one of the confirmed domains.
- Sibling-shape intent — when sibling folders look inconsistent (e.g. some clients have
profile.md, others don't), ask whether they should mirror each other or whether the variation is intentional. CLAUDE.mdnecessity — for any subdirectoryCLAUDE.mdthat just restates what names already say, ask whether there's implicit context worth keeping or whether it can be removed.- Glossary check — list any terms you spotted in the repo or in the user's recent prompts that look user-specific and aren't in
agent-docs/glossary.md. Ask: "Are these worth adding so a future session can look them up when they appear?" Recommend adding the obvious ones; let user accept, edit, or skip.
Stop asking once you have what you need to audit confidently. Don't over-interview.
- Audit against the principles. Walk the checklist. Note what's working and what isn't. Flag specifically:
- Folders grouped by file type (templates/, docs/, data/, scripts/ at root)
- Names with spaces, capitals, or that don't describe content
- Sibling folders with inconsistent shapes
- Subdirectory
CLAUDE.mdfiles that don't meet any of Principle 8's four conditions (dead weight — restates what names already say) - Domain folders missing a
CLAUDE.mdwhere Principle 8's conditions clearly apply (e.g. behavioral rules like brand voice, per-instance context that varies) - Missing
agent-docs/glossary.md, or rootCLAUDE.mddoesn't include the "ask + add to glossary" rule - Loose business content at the root (not config/metadata files like
.gitignore,package.json, etc.) - Generic nesting more than 3 levels deep
- Produce the report (template below). Include a proposed before/after tree and a plain-English list of changes — no shell commands, the user is non-technical.
- Wait for explicit user confirmation before any file moves. Even if the user invoked the skill, do not move files until they approve the specific plan. Then execute the moves yourself (you know the commands) and re-run step 1 to confirm.
Output template
## Structure Audit
### What's working
- [Concrete patterns to keep]
### Issues
**Critical** (blocks navigation):
- [Issue] — at `path/` — [what to do]
**Warning** (slows navigation):
- [Issue] — at `path/` — [what to do]
**Suggestion** (polish):
- [Issue] — at `path/` — [what to do]
### Proposed structure
Before:
[ASCII tree of current shape]
After:
[ASCII tree of proposed shape]
### Changes I'll make
1. Rename `clients/Acme Corp` → `clients/acme-corp` (lowercase, no spaces — so my Glob/Grep tools can find it)
2. Move `templates/proposal-template.md` into `sales/templates/` (group by domain, not file type)
3. Remove `operations/CLAUDE.md` — its content just restates what the folder names already say
Confirm to execute? (yes / skip specific numbers / edit)When everything is good
If the audit finds no issues, say so plainly:
## Structure Audit
Your repo is agent-navigable.
- Domains are clear: [list inferred domains]
- Names are self-describing and lowercase kebab-case
- Sibling folders mirror each other's shape
- CLAUDE.md placement matches where implicit context exists
- `agent-docs/glossary.md` exists and `CLAUDE.md` includes the ask-and-add rule
- Nesting stays within 3 levels
No changes needed.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.

