agentleFS
mgonzalezbailemgonzalezbaile/personal-assistant/.claude/skills/claude-md-template/SKILL.md

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

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. claude-world/director-mode-lite★ 80same name
    2. 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.

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

    If the existing file's shape strongly contradicts the filesystem signal (e.g., a leaf with no children but linking to planned child …

    line 32
  2. Very specific:

    No manifest → knowledge leaf.

    line 41
  3. Distinctive:

    File already satisfies the spine: Do nothing structural. Just make the user's requested edit.

    line 97
  4. Distinctive:

    Never reorder sections that already exist: Only insert missing ones.

    line 102
  5. Distinctive:

    Never replace user-written prose with template placeholders: If a required section exists but has thin content, leave it.

    line 103
  6. Very specific:

    After auto-fix, briefly tell the user which sections were inserted, e.g.

    line 106
  7. Distinctive:

    If the user's project happens to use a different filename convention (AGENTS.md, GEMINI.md, …), flag the mismatch and stop:

    line 112
  8. Very specific:

    Use relative paths for child CLAUDE.md links (memory/CLAUDE.md, not absolute paths).

    line 123

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

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

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):

  1. Root — no ancestor directory above P contains a CLAUDE.md file (within the same repo or workspace). P is the entry-point map for the whole project.
  2. Intermediate — at least one descendant directory of P's parent contains its own CLAUDE.md. P is a navigation node.
  3. Leaf — neither of the above. P is 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 a CLAUDE.md.
  • For Intermediate vs Leaf: list child directories of P's parent and check for CLAUDE.md inside 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 Navigation table linking to existing child CLAUDE.md files 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

  1. # [Project Name] — H1.
  2. ## How to Use This File — the mandatory protocol for using the hierarchy.
  3. ## What Is This Project (or ## What Is This Workspace / ## What Is This Repository — any equivalent overview heading).
  4. ## Deep-Dive Navigation — table with columns Path | Description | Keywords listing child CLAUDE.md files.

Full reference: templates/root.md.

Intermediate spine — required sections

  1. # [Module/Domain Name] — H1.
  2. Parent: [../CLAUDE.md](../CLAUDE.md) — line directly under the title.
  3. ## What Lives Here — directory overview. Ideally followed by a sub-modules table with columns Directory | Role | Status.
  4. ## Deep-Dive Navigation — table with columns Path | Description | Keywords listing child CLAUDE.md files.

Full reference: templates/intermediate.md.

Leaf spine — required sections

Always required:

  1. # [App/Service/Package Name] — H1.
  2. Parent: [../CLAUDE.md](../CLAUDE.md) — line directly under the title.
  3. ## What This [App/Service] Does (or ## What Lives Here for knowledge leaves) — concise overview.

Additionally required for code leaves:

  1. ## Stack — table with columns Concern | Technology.
  2. ## Architecture / Directory Layout — ASCII tree or diagram of the directory.
  3. ## Key Files & Components — table with columns File / Component | Purpose.
  4. ## Conventions — local conventions for file naming, styling, patterns.
  5. ## 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 use AGENTS.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.md links (memory/CLAUDE.md, not absolute paths).

Templates

  • Root — top-level project / workspace entry point.
  • Intermediate — folder with child CLAUDE.md files.
  • Leaf — terminal folder (app / service / package / knowledge node).

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.