claude-md-template
Skill8 starsChanged 6 months agoMITView on GitHub
Use on every write to a file named CLAUDE.md -- create or modify, even a one-line tweak, in any repository.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- claude-world/director-mode-litetheir own version, first seen Nov 1, 2026
- vishalsachdev/claude-skillstheir own version, first seen Aug 12, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- claude-world/director-mode-lite★ 80same name
- vishalsachdev/claude-skills★ 2same name
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 repository7 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- memory/CLAUDE.mdCLAUDE.md
- daily-briefingSkill
- google-workspace-cliSkill
- memory-claude-md-syncSkill
- task-managementSkill
- wikiSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 32
If the existing file's shape strongly contradicts the filesystem signal (e.g., a leaf with no children but linking to planned child …
- Very specific: line 41
No manifest → knowledge leaf.
- Distinctive: line 97
File already satisfies the spine: Do nothing structural. Just make the user's requested edit.
- Distinctive: line 102
Never reorder sections that already exist: Only insert missing ones.
- Distinctive: line 103
Never replace user-written prose with template placeholders: If a required section exists but has thin content, leave it.
- Very specific: line 106
After auto-fix, briefly tell the user which sections were inserted, e.g.
- Distinctive: line 112
If the user's project happens to use a different filename convention (AGENTS.md, GEMINI.md, …), flag the mismatch and stop:
- Very specific: line 123
Use relative paths for child CLAUDE.md links (memory/CLAUDE.md, not absolute paths).
≈ “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
CLAUDE.md Template
Enforces a consistent shape across every CLAUDE.md in a project. Three variants exist — Root, Intermediate, Leaf — picked by filesystem position. The skill auto-fixes missing required sections without asking for confirmation, and preserves anything the user added on top.
The goal is a coherent, navigable hierarchy of CLAUDE.md files where each level explains itself and points to the next. The templates capture the minimum spine that makes that hierarchy work; on top of that, any project is free to add custom sections (Role, Preferences, Knowledge Areas, Operating Rules, etc.).
Scope: this skill applies only to files named exactly CLAUDE.md. Other agent-instruction filenames (AGENTS.md, GEMINI.md, .cursorrules, etc.) are out of scope — surface the mismatch but do not auto-apply this template. If multiple CLAUDE.md files are being touched in a single turn, run the skill for each.
Step 1 — Detect the variant
Given the path of the CLAUDE.md being edited (call it P):
- Root — no ancestor directory above
Pcontains aCLAUDE.mdfile (within the same repo or workspace).Pis the entry-point map for the whole project. - Intermediate — at least one descendant directory of
P's parent contains its ownCLAUDE.md.Pis a navigation node. - Leaf — neither of the above.
Pis a terminal node.
Walk the filesystem to decide. A useful pattern:
- For Root vs not-Root: check whether any directory between
P's parent and the repo root contains aCLAUDE.md. - For Intermediate vs Leaf: list child directories of
P's parent and check forCLAUDE.mdinside each (and one level deeper if needed).
Tie-breakers and respected signals
- A file that already contains a
Parent: [...](...)line directly under the H1 is never Root. - A file that already has a
## Deep-Dive Navigationtable linking to existing childCLAUDE.mdfiles is at least Intermediate, even if those children are sparse. - If the existing file's shape strongly contradicts the filesystem signal (e.g., a leaf with no children but linking to planned child CLAUDE.mds), trust the existing shape and do not restructure.
Step 2 — Detect code project vs knowledge node (Leaf only)
For Leaf files, decide whether this directory represents a code project by checking for a build/runtime manifest in the directory or any descendant:
package.json, pyproject.toml, requirements.txt, Pipfile, setup.py, Cargo.toml, go.mod, Gemfile, pom.xml, build.gradle, composer.json, Makefile (with build/test targets).
- Manifest present → code leaf. The full Leaf spine applies (Stack, Architecture, Key Files, Conventions, Running).
- No manifest → knowledge leaf. Only the H1, Parent link, and overview section are required. Stack / Architecture / Running are not enforced — knowledge nodes use whatever shape fits the content (e.g.,
## Key Files & People,## Conventions,## Links).
Step 3 — Apply the spine
The three reference templates are bundled under templates/. Each is the original AGENTS-style template with AGENTS.md swapped to CLAUDE.md everywhere. Use them as authoritative reference, not as full file rewrites — extras the user added are protected.
Root spine — required sections
# [Project Name]— H1.## How to Use This File— the mandatory protocol for using the hierarchy.## What Is This Project(or## What Is This Workspace/## What Is This Repository— any equivalent overview heading).## Deep-Dive Navigation— table with columnsPath | Description | Keywordslisting childCLAUDE.mdfiles.
Full reference: templates/root.md.
Intermediate spine — required sections
# [Module/Domain Name]— H1.Parent: [../CLAUDE.md](../CLAUDE.md)— line directly under the title.## What Lives Here— directory overview. Ideally followed by a sub-modules table with columnsDirectory | Role | Status.## Deep-Dive Navigation— table with columnsPath | Description | Keywordslisting childCLAUDE.mdfiles.
Full reference: templates/intermediate.md.
Leaf spine — required sections
Always required:
# [App/Service/Package Name]— H1.Parent: [../CLAUDE.md](../CLAUDE.md)— line directly under the title.## What This [App/Service] Does(or## What Lives Herefor knowledge leaves) — concise overview.
Additionally required for code leaves:
## Stack— table with columnsConcern | Technology.## Architecture / Directory Layout— ASCII tree or diagram of the directory.## Key Files & Components— table with columnsFile / Component | Purpose.## Conventions— local conventions for file naming, styling, patterns.## Running— exact commands to run, build, or test the app/service.
Full reference: templates/leaf.md.
Step 4 — Auto-fix structural gaps
Apply fixes automatically, without asking for confirmation. The three cases:
Brand new or empty file. Generate it from the appropriate template. Substitute placeholders with real values where you have them (project name, parent path, child CLAUDE.md links you can discover from the filesystem). Leave the remaining [bracketed instructions] so the user knows what to fill in.
File exists but is missing required sections. Insert each missing section at its natural position, using [bracketed placeholders] for the body. Natural positions:
- H1 → first line if missing.
Parent:line → immediately under the H1 (intermediate/leaf only).- Overview section (
How to Use This File,What Is This Project,What Lives Here,What This X Does) → right after the H1 / Parent line. Deep-Dive Navigation→ after the overview, before any custom sections.- Code-leaf sections (
Stack,Architecture, etc.) → after the overview, in the order shown in templates/leaf.md.
File already satisfies the spine. Do nothing structural. Just make the user's requested edit.
Protections that must always hold
- Never delete or rewrite existing custom sections. Sections like
## Role,## Preferences,## Knowledge Areas,## Operating Rules,## Management Lenses,## Key Files & People,## Links,## Local Conventions, etc. are valid extras and must be preserved verbatim. - Never reorder sections that already exist. Only insert missing ones.
- Never replace user-written prose with template placeholders. If a required section exists but has thin content, leave it.
- Never strip the
Parent:line even if filesystem detection suggests Root — that signal is intentional.
After auto-fix, briefly tell the user which sections were inserted, e.g. "Added a missing ## Deep-Dive Navigation skeleton with a placeholder row — fill it in with the child CLAUDE.md links."
Step 5 — Filename swap is already done
The bundled templates already use CLAUDE.md everywhere. Do not paste content from the templates that still references AGENTS.md; that swap is the whole point of bundling them.
If the user's project happens to use a different filename convention (AGENTS.md, GEMINI.md, …), flag the mismatch and stop:
This skill targets
CLAUDE.md. Your repo appears to useAGENTS.md— let me know if you want me to apply the same shape there, but I won't auto-rewrite without confirmation.
Step 6 — Link and Markdown conventions
Any content the skill inserts must follow these rules:
- Standard Markdown links only:
[label](relative/path.md#anchor). Never Obsidian-style[[wikilinks]]. - Section anchors are
#kebab-case-of-the-heading. - Tables use the exact column headers from the template (
Path | Description | Keywords,Directory | Role | Status,Concern | Technology, etc.) so downstream tooling can rely on them. - Use relative paths for child
CLAUDE.mdlinks (memory/CLAUDE.md, not absolute paths).
Templates
- Root — top-level project / workspace entry point.
- Intermediate — folder with child
CLAUDE.mdfiles. - Leaf — terminal folder (app / service / package / knowledge node).
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.

