Slim Claude MD

Restructure or initialize a project's CLAUDE.md so it stays small, sustainable, and credential-safe.

When to Use

CLAUDE.md is over ~300 lines and the user wants to slim it
Starting a new project from scratch and need the structured methodology
User mentions: context bloat, lost env URLs, sessions pointing at the wrong environment, CLAUDE.md becoming a journal, "organize project memory"
Sessions are burning too many tokens on project context before doing real work

What This Skill Produces

After running, the target project will have:

A slim CLAUDE.md (≤ ~300 lines) — acts as a router/index, not an encyclopedia. Contains hard rules, branch/environment topology (no secrets), pointers to topical docs, common commands, today's state, a housekeeping protocol, and a session protocol.
A gitignored CLAUDE.local.md — holds all live DB connection strings, credentials, hosting service names, API keys, and any other secret-shaped facts. Read before any DB or hosting operation.
A topical docs/ tree (architecture/, features/, pipeline/, scripts/, recaps/) containing reference material previously stuffed into CLAUDE.md. Each file loaded on-demand.
A built-in housekeeping protocol inside CLAUDE.md so future sessions know where new facts belong and the structure doesn't decay.
.gitignore updated to exclude CLAUDE.local.md.

Mode Detection

Run this first to decide which path to take:

[ -f CLAUDE.md ] && wc -l CLAUDE.md || echo "no CLAUDE.md yet"

No CLAUDE.md or fewer than ~50 lines → NEW mode (Section A below).
CLAUDE.md exists with substantial content (≥ 100 lines) → EXISTING mode (Section B below).
Borderline (50–100 lines): ask the user which mode they want.

Also check:

Is .gitignore present?
Is CLAUDE.local.md already present or already in .gitignore?
Is there an existing docs/ directory?

Section A — NEW Mode (Fresh Project)

A1. Gather project facts

Ask the user (one batched question) for:

Project name — for the H1 of CLAUDE.md
One-line description — for the subtitle
Production URL (if any)
Repo URL
Branches and environments — typical patterns:
- Single-branch (main only) — solo project, simple deploy
- Two-branch (develop → main) — small team, manual prod
- Three-branch (develop → staging → main) — most common
- Four-branch (develop → staging → canary → main) — production-grade with canary gate
Hosting — Railway, Vercel, Fly, AWS, self-hosted, etc.
What kinds of secrets does the project use? — DB URLs, API keys, OAuth secrets, etc. (categories only, not values)

If the user wants defaults: develop → staging → main, Railway hosting, DB + API key sections in CLAUDE.local.md.

A2. Create the directory structure

mkdir -p docs/architecture docs/features docs/pipeline docs/scripts docs/recaps docs/plans

Don't create pipeline/ or scripts/ if the project has no data pipeline or doesn't use scripts heavily.

A3. Write CLAUDE.md from the template

Read references/CLAUDE-template.md, substitute placeholders with values from A1. Inline the housekeeping protocol from references/housekeeping-protocol.md verbatim. Write to project root.

A4. Write CLAUDE.local.md from the template

Read references/CLAUDE-local-template.md, substitute placeholders for branch/env structure. Leave actual secret values as <paste-here> placeholders. Write to project root.

A5. Update .gitignore

Add (only if not already present):

# Claude Code local memory — contains live credentials. Auto-loaded by
# Hermes alongside CLAUDE.md but never committed.
CLAUDE.local.md

If .gitignore doesn't exist yet, also add standard ignores for the project's stack (node_modules/, .next/, __pycache__/, target/, etc.) — but be conservative and tell the user what was added.

A6. Verify

wc -l CLAUDE.md
git check-ignore -v CLAUDE.local.md   # should match
git status --short                     # CLAUDE.local.md should NOT appear
ls docs/

A7. Hand off

Tell the user:

"CLAUDE.md and CLAUDE.local.md are ready. CLAUDE.local.md is gitignored."
"Open CLAUDE.local.md and fill in the actual credentials — I left them as placeholders."
"As you build the project, add new facts to the relevant docs/ file, not directly to CLAUDE.md."

Do not commit anything. The user owns the first commit.

Section B — EXISTING Mode (Slim a Bloated CLAUDE.md)

B1. Read the case study first

Read references/cruise-intelligence-case-study.md to refresh on how a real 2,275-line CLAUDE.md got mapped to docs/. You don't need to copy the exact mapping — every project is different — but seeing the patterns helps you propose sensible homes.

B2. Audit the current state

wc -l CLAUDE.md                              # current size
ls .gitignore && grep -c CLAUDE.local.md .gitignore  # is it ignored?
ls -d .claude 2>/dev/null                     # existing .claude/ dir?
ls docs/ 2>/dev/null                        # existing docs?
[ -f CLAUDE.local.md ] && wc -l CLAUDE.local.md || echo "no CLAUDE.local.md yet"

Read CLAUDE.md in chunks if it's >2000 lines so the full content is in context for extraction.

B3. Propose a section → destination map

For each top-level ## Section in the current CLAUDE.md, decide:

Stays in slim CLAUDE.md: hard rules, branch table, common commands, today's-state bullets
Moves to CLAUDE.local.md: any block containing connection strings, passwords, API keys, internal proxy URLs
Moves to docs/architecture/<name>.md: schema, auth, caching, project structure, rating systems, patterns
Moves to docs/features/<name>.md: per-feature deep dives (one file per major feature)
Moves to docs/pipeline/<name>.md: data pipelines, scrapers, sync scripts
Moves to docs/scripts/README.md: script catalogs
Moves to docs/STATE-SNAPSHOT.md: dated entity counts, "current state" tables
Moves to docs/recaps/: existing dated session recap files (use git mv to preserve history)
Deleted entirely: "Updated YYYY-MM-DD" markers, narrative changelogs, content already in prisma/schema.prisma

Present the map to the user as a table. Confirm before executing.

B4. Hard rules to extract

Pull these into the slim version's "Hard rules" section:

"NEVER do X" / "ALWAYS do Y" statements
Approval requirements for destructive ops
Default deploy targets
Language-specific footguns (raw SQL conventions, import requirements)
Reuse-before-rewrite directives

These are the load-bearing parts that genuinely need to be in every session's context.

B5. Execute the migration

Read full CLAUDE.md into context (chunked if needed).
Add CLAUDE.local.md to .gitignore.
Create CLAUDE.local.md with secrets extracted from existing CLAUDE.md. Verify git check-ignore.
Create docs/architecture/, docs/features/, docs/pipeline/, docs/scripts/, docs/recaps/ directories.
git mv existing SESSION-RECAP-*.md files into docs/recaps/.
Write each topical docs file using content extracted from CLAUDE.md.
Write docs/STATE-SNAPSHOT.md with dated entity counts pulled from CLAUDE.md.
Rewrite CLAUDE.md from references/CLAUDE-template.md, substituting hard rules, branch table, and pointer index. Inline housekeeping protocol.
Verify (see B6).

B6. Verify

wc -l CLAUDE.md                                       # should be ≤ ~300
git check-ignore -v CLAUDE.local.md                    # should match
git status --short                                     # CLAUDE.local.md must NOT appear

# Walk every docs/ pointer in the new CLAUDE.md and confirm:
for f in $(grep -oE 'docs/[a-zA-Z0-9_/.-]+\.md' CLAUDE.md); do
  [ -e "$f" ] && echo "OK   $f" || echo "MISS $f"
done

Also grep new CLAUDE.md and all new docs files for accidentally-leaked secrets.

B7. Do NOT commit

Leave a clean working tree of changes for the user to review. Tell them:

The suggested 4-commit sequence
That CLAUDE.local.md is on disk but invisible to git
Any pre-existing tracked files with secrets that are out of scope but worth cleaning up later

The user owns the commit.

Things to Avoid in Either Mode

Do not invent project facts. If you don't know production URL, hosting, or branch structure, ask. Don't guess.
Do not put real secret values in any tracked file. CLAUDE.local.md only, and it must be gitignored before writing.
Do not duplicate content between CLAUDE.md and a docs file. Each fact lives in exactly one place.
Do not add stat tables to topical docs. Counts (entities, rows, users) go in docs/STATE-SNAPSHOT.md.
Do not add "Updated YYYY-MM-DD" markers to anything. Git history is the source of truth for "when".
Do not add hooks or skills as part of this skill. Those are separate follow-ups.
Do not commit or push automatically. The user always owns those steps.
Do not assume develop → staging → canary → main. Detect actual branches with git branch -a.
Do not create directories the project doesn't need. Pure frontend projects don't need docs/pipeline/.

slim-claude-md

Safety Notice

Copy this and send it to your AI assistant to learn