For Anyone Writing a CLAUDE.md
Your Agent’s Letter
Stays Honest
Author a short letter to your agent, line by line, then keep it honest as you work. It grows only when a mistake actually repeats.
Most CLAUDE.md files get written once and bloated forever. Nobody goes back to cut a line.
The external problem
Yours started as a few honest notes and turned into a pile of commands, file paths, and rules nobody remembers writing or approving.
The internal problem
You can feel the agent getting worse the longer the file gets, but cutting anything feels risky, so the safer move always looks like adding one more line.
What's at stake
A file long enough that the model stops reading it closely, misses the one line that actually mattered, and you end up repeating yourself in chat anyway.
Four routes. One letter, kept honest.
Run the route that matches what’s happening: nothing to start from, an existing file to audit, a structural question to settle, or the end of a work session.
Create the Letter
Interviews you for intent, mental model, and hard boundaries, then drafts a short first letter in your own words, approved line by line before anything is written.
Refine the File
Reads what’s already on disk and tags every line keep, delete, or re-voice. Deletions are mandatory every pass, and the line count should go down.
Scale Check
Judges whether the project has actually outgrown a plain letter and earned a routing section, based on signals like repeated misrouting, never a hunch.
Session Capture
Scans a working session for corrections that actually recurred, proposes the smallest fix in your own words, and says plainly when nothing qualified.
Reference library: Two disciplines, one file.
Theo treats it as a letter to a new hire: purpose, mental model, why, a glossary only where words genuinely collide, written by hand and grown reactively. Gary treats it as a resolver: route, don’t explain, and only add routing once the project has actually outgrown a plain letter.
Supporting reference files follow the practical guide. Archived source material and author workflow notes are not a current policy certification.
01 Letter MentalityTheo’s case for a hand-authored letter over rules: intent, glossary, reactive growth.
Reference
Letter Mentality
Core Philosophy
The single most important thing in agentic coding is that the AI understands what you want and how you build — not what files to touch or how to implement. The agent.md exists to transfer *your way of thinking* ("your psychosis," in his words) into the model so it stops making the same wrong assumptions. It is a steering document, not a specification or a rulebook.
He frames it as a spectrum of ways to get the model aligned with you:
- Write a 5,000-line global agent.md describing everything you like and do.
- Be a famous influencer and just tell the model "I'm Theo, build the way I like" (works *sometimes*).
- The easiest and best: read the model's outputs and steer it conversationally; only when you see it making the *same mistake repeatedly* do you encode that correction into the agent.md.
His big shift: he used to use a "big bloated useless agents MD." With GPT-5.5 in that bloated default state, "55 sucks." Once he condensed the file and made it about steering rather than rules, "it becomes the coolest way to work I've ever built with." The agent.md was one of the strongest things that let him build Lakebed so fast.
Key Principles
- Write it like a letter from you to the agent. He wrote the Lakebed AGENTS.md "almost like a letter from me to the agent to tell it how we're thinking, what we're building, and why we're doing this." The goal: reduce bad assumptions, weird questions, and work that drifts outside his intended constraints.
- Convey intent and "why," not file paths or implementation. His Lakebed agent.md has no file paths, no technical decisions, no enforcements. Telling the model *what* to do and *why* beats telling it *how*. This mirrors how he prompts: high-level goal first, not implementation detail.
- Encode corrections, not anticipations. Don't pre-write rules for problems you imagine. When you "notice it making the same mistakes over and over again, go into the agent MD and try to give the model your psychosis." The file grows reactively from observed failures, not speculatively.
- A glossary of terms is high-value. This is his one concrete, strongly-endorsed structural element. On Lakebed the word "you/me/we/developers/agents" was genuinely ambiguous (he was both the builder and a user; agents built Lakebed and also used Lakebed). So he defined terms explicitly: *you* = the agent making changes; *me/we/us* = the humans building Lakebed; *developers* = end users building on Lakebed; *agents* = what those developers use. Purpose: "make it easier for the model to know what I'm referring to."
- Keep it simple — and when simple fails, fix the obstacle, don't add complexity. A recurring theme: "if it doesn't work, that doesn't mean make it more complex. It means fix the things that prevent it from being simple." If plain-language prompting isn't landing, the fix is a *small* agent.md/CLAUDE.md tweak so prompts can stay simple — not more verbose prompts and not a heavier rules file.
- Write it by hand, yourself. He emphasized twice: "my agents did not write this file. I wrote this file." The point of the document is to transfer *his* mental model, so the human has to author it.
- Reinforce behavior through artifacts in the codebase, not just the agent.md. Once the model behaves the way you want — via the agent.md, via well-formatted HTML plans it can copy, or via the existing code — "everything else almost stops mattering." The agent.md is one of several steering surfaces; consistency across them compounds.
What Theo Does
- Writes a short, prose, intent-driven AGENTS.md addressed *to* the agent, explaining the project's purpose, his mental model, and the constraints he wants respected.
- Includes a glossary when terminology is ambiguous in the domain.
- Keeps a couple of small general rules at the bottom — and is candid that he "might even delete them because I haven't found them to be super useful."
- Authors and edits the file manually.
- Updates it reactively, only after repeated observed mistakes, with the minimal addition needed to fix the recurring problem.
- Uses it to keep prompts short — most of his actual prompts end up two sentences or less because the agent.md already carries the shared context.
What Theo Avoids (Anti-Patterns)
- Bloated agent.md files. The "big bloated useless agents MD" actively made GPT-5.5 worse. Size is a liability, not thoroughness.
- File paths in the agent.md (and in prompts). "I trust the model to find the right file. I am more likely to recommend the wrong file than the model is half the time." A wrong path actively confuses the model into forcing changes in the wrong place.
- Technical decisions / hard enforcements baked into the file. His Lakebed file has none.
- Over-engineered workflow scaffolding around the file. When chat asked what skills/frameworks/"superpowers plugin" he used to get the model to behave: "No, you're all coping. You don't need all of that. I have almost zero skills installed. Just talk to the model. They're smart enough now." He keeps even his "grill me" prompt as a Whisper Flow text-expansion binding rather than an installed skill.
- Letting the agent write its own context file. It defeats the purpose of transferring *your* thinking.
- Speculative rules. Don't add detail "unless it needs the details." Be sparse; figure out what the model *doesn't* understand and fix only that.
- Adding complexity as a response to failure. The instinct to get more specific/overspecific is the wrong move; condense and steer instead.
Notable Quotes (verbatim)
"The most important thing when you're building with AI is that the AI understands what you want and how you build."
— His stated thesis for the whole topic; the agent.md is one tool for achieving it.
"If you notice it making the same mistakes over and over again, go into the agent MD and try to give the model your psychosis. That's what I've done. And I think that's one of the strongest things I did that made it possible for me to make this project so quickly."
— On when and why to edit the file.
"You'll notice that in this Lakebed Agents MD, there are no file paths. There are no technical decisions or enforcements. There's a couple small general rules at the bottom that I might even delete because I haven't found them to be super useful."
— Describing the actual contents of his file.
"I wrote this one almost like a letter from me to the agent to tell it how we're thinking, what we're building, and why we're doing this so that it's less likely to have bad assumptions or ask weird questions or work outside of the technical constraints that I want it to work within."
— The format and intent.
"I noticed almost immediately after writing this — by hand, by the way, my agents did not write this file, I wrote this file — ... I didn't really have to do much to get the agent to build how I wanted it to. Once it had the context of how I was thinking about this, it started behaving way, way better."
— On authoring it himself and the payoff.
"A glossary of terms and language to help the model understand what you're saying can be very, very helpful."
— On the one structural element he explicitly recommends.
"Generally speaking, you should try to keep things simple. And if it doesn't work, that doesn't mean make it more complex. It means fix the things that prevent it from being simple. ... You should make slight changes to your agents MD and to your claude MD so that you can keep your prompt simple."
— The simplicity principle applied directly to context files.
"Copying the prompts I used to use with the big bloated useless agents MD, 55 sucks. When you take the time to condense and steer it the way you want it to work, it becomes the coolest way to work I've ever built with."
— Bloat vs. condensed, with a concrete before/after.
"No, you're all coping. You don't need all of that. I have almost zero skills installed. Just talk to the model. They're smart enough now."
— Pushing back on skills/plugins/frameworks as a substitute for plain steering.
"Once you get the agent to behave how you want — if there is enough proof of that behavior in your codebase, whether that is HTML plans, whether that is your agents MD steering it certain ways, whether it's the code itself — once you get the model to behave how you want it to, everything else almost stops mattering."
— The agent.md as one of several reinforcing steering surfaces.
"I trust the model to find the right file. I am more likely to recommend the wrong file than the model is half the time."
— Why no file paths.
Practical Takeaways
- Default to no agent.md, then earn it. Start by just talking to the model. Add to the file only when a mistake recurs.
- Write prose, addressed to the agent, about purpose and mindset — not specs, not paths, not enforcement.
- Add a glossary the moment your domain has ambiguous or overloaded terms.
- Keep it short. Bloat measurably degrades model behavior. Condensing is an active improvement, not just tidiness.
- Author it by hand. The file's job is to transmit your thinking; don't outsource that to the agent.
- Use the agent.md to shrink your prompts. If you're writing long, over-specified prompts, that's a signal to make a small context-file change — not to write longer prompts.
- Don't reach for skills/plugins/frameworks first. Treat them as last resorts; modern models respond to plain conversational steering plus a lean context file.
- Stay reactive and minimal. Don't anticipate; fix what you actually observe, with the smallest change that works. Be willing to delete rules that aren't pulling weight.
*Source: Theo (t3.gg), "How I Build with AI (Updated)," https://www.youtube.com/watch?v=xJaMTo2YgO8. All quotes transcribed from the video's auto-transcript; minor verbal artifacts and censored profanity have been smoothed for readability without changing meaning.*
02 Resolver DisciplineGary’s case for routing over explaining, and why bloated files drown the model.
Reference
Resolver Discipline
TL;DR
Gary's central thesis: a CLAUDE.md is not an encyclopedia, it is a routing table. Its job is not to teach the model how to do the work — it is to tell the model *where to find the instructions* for the work, and to load that context only at the moment it is needed. He calls this routing table a resolver. The mentality is "route, don't explain." A bloated CLAUDE.md doesn't make the model smarter; it drowns it.
Core Philosophy
The model isn't dumb — it's drowning
The single most important idea. Gary's instinct, like everyone's, was "you want the model to know everything." So he crammed every quirk, pattern, lesson, convention, and edge case into CLAUDE.md until it hit 20,000 lines. It felt productive. It was the opposite.
"I wasn't [making the model smarter]. I was drowning it. The model's attention degraded. Responses got slower and less precise. Claude Code literally told me to cut it back. That's when you know you've gone too far — the AI is telling you to stop talking."
He names the failure mode directly: "omniscience by proximity." The belief that stuffing everything into the context window makes the model omniscient.
"You can't make someone smarter by shouting louder. You make them smarter by giving them the right book at the right moment."
And the punchline of the whole article:
"Almost nobody is building [resolvers] explicitly. Everyone is cramming 20,000 lines into the system prompt and wondering why the model seems dumber than it should be. The model isn't dumb. It's drowning. Give it a routing table and watch what happens."
Route, don't explain
The fix for the 20,000-line file was about 200 lines: a numbered decision tree of pointers to documents. Not the knowledge itself — pointers to where the knowledge lives.
"That 200-line file is the resolver. It replaced 20,000 lines of instructions. And the system immediately got better — faster responses, more accurate filing, fewer hallucinations. Not because the model got smarter. Because I stopped blinding it with noise."
The definition of a resolver, in his own words:
"A resolver is a routing table for context. When task type X appears, load document Y first. That's it. One sentence. But that one sentence is the difference between an agent that compounds intelligence and an agent that slowly forgets what it knows."
CLAUDE.md is a management layer, not a manual
The deepest reframe in the article. Gary argues that once a system has 40+ skills and 25,000 files, "you don't just have code. You have an organization." The resolver is the management layer of that organization:
- Skills are employees — each has a capability; some specialists, some generalists, some cron-only, some user-facing.
- The resolver is the org chart — who handles what, how tasks route, and the escalation logic when something doesn't match.
- The filing rules are internal process — where information lives and how decisions get recorded.
- check-resolvable is audit & compliance — can the system actually do what it claims?
- Trigger evals are performance reviews — given a real input, does the right part of the org respond?
"The problem isn't that models aren't smart enough. The problem is that we've been building organizations with no management layer. Just a pile of talented employees and a vague hope they'll coordinate. Resolvers are that missing layer."
Key Principles
Gary's own end-of-article summary of "the pattern":
- Load the right context at the right moment. Don't cram.
- Mandate that every skill consults the resolver. Don't trust individual filing logic.
- Test the routing, not just the output. (Trigger evals.)
- Audit reachability. (check-resolvable, weekly.)
- Make the resolver learn from its own traffic. (The endgame.)
He frames these as a maturity ladder:
"When it's missing, skills invent their own filing logic and everything slowly degrades. When it's present but untested, capabilities go dark — you have a surgeon the hospital can't find. When it's tested but static, it rots within 90 days. When it's tested and self-healing, the system compounds."
Resolvers are fractal
The principle "that makes everything click." Resolvers compose — they exist at every layer, not just the top:
- Skill resolver (lives in AGENTS.md / the root context file): maps task types to skill files. "Who is this person?" → brain-ops. "Ingest this PDF" → pdf-ingest.
- Filing resolver (lives in RESOLVER.md): maps content types to directories. Person →
people/, Company →companies/, Policy analysis →civic/. - Context resolver (lives inside each skill): internal sub-routing — email triage one way, scheduling another, signature tracking a third.
"Claude Code already has this pattern. Every skill has a description field. The model matches user intent to skill descriptions automatically... The description *is* the resolver. It's resolvers all the way down."
This fractal sameness is what lets the architecture scale "from 5 skills to 50, from 1,000 files to 25,000, from a toy demo to a production system that processes 200 inputs a day."
What Gary Does (Recommended Practices)
Keeps the root file short — pointers, not prose
A numbered decision tree the model walks:
- Is it a person? →
/people/directory - A company? →
/companies/directory - A policy analysis? →
/civic/directory
20,000 lines of knowledge remains accessible *on demand* without polluting the context window. ~200 lines at the top; everything else lives in linked documents loaded only when relevant.
Mandates that every skill consult the resolver
After catching a misfiling (see anti-patterns), he didn't patch skills one by one — he created a shared filing-rules document and a hard mandate. His actual two-line mandate, placed at the top of every brain-writing skill, verbatim:
*"Before creating any new brain page, read brain/RESOLVER.md and skills/_brain-filing-rules.md. File by primary subject, not by source format or skill name."*
"One rule. Ten skills fixed." Result: zero misfilings since.
Maintains a disambiguation / filing-rules document
A secondary doc (_brain-filing-rules.md) that catalogs edge cases and *past mistakes* so the same error can't recur a different way: Sources vs. originals. People vs. companies (when someone IS a company). Civic vs. sources (the misfiling that started it all).
"Every mistake, documented, so the same mistake can't happen a different way."
Tests the routing with trigger evals
A suite of ~50 sample inputs with expected outputs. His actual examples:
Input: "check my signatures" → Expected: executive-assistant (signature section) Input: "who is Pedro Franceschi" → Expected: brain-ops → gbrain search Input: "save this article to brain" → Expected: idea-ingest + RESOLVER.md
Two failure modes he names:
- False negative — skill should fire but doesn't (trigger description wrong/missing).
- False positive — wrong skill fires (two triggers overlap).
Both are fixable by editing markdown, no code changes. "The resolver is a document, and documents are cheap to fix." He is emphatic this is non-negotiable:
"If you can't prove the right skill fires for the right input, you don't have a system. You have a collection of skills and a prayer."
Audits reachability with a meta-skill (check-resolvable)
A skill that walks the entire chain — AGENTS.md → skill file → code — to find dead links: skills that exist but have *no path* from the resolver at all. First run found 6 unreachable skills out of 40+ — 15% of capabilities were "dark." Fixed in an hour by adding triggers. Now runs weekly.
"It's the resolver equivalent of a linter — it tells you what's broken before a user discovers it the hard way."
Plans for a self-healing resolver (the endgame)
Forward-looking, not fully built. The idea (raised by a YC CTO in office hours): a reinforcement-learning loop that observes every task dispatch — which skill fired, which didn't, which had no match, which matched wrong — and periodically rewrites the resolver from observed evidence. "Not a human maintaining a table. The table maintaining itself." He notes Claude Code's AutoDream memory-consolidation system is a primitive version of this.
"A resolver that learns from its own traffic. That's the endgame for agent governance."
What Gary Avoids (Anti-Patterns)
The 20,000-line CLAUDE.md
The originating sin. Cramming every lesson and edge case into one file degrades attention, slows responses, and reduces precision. Signal you've gone too far: the AI itself tells you to cut it back.
Hardcoded filing logic inside skills
The misfiling that revealed everything: he asked his agent to ingest Will Manidis's essay "No New Deal for OpenAI" — a sharp policy analysis. The agent filed it in sources/ (meant for raw data dumps, CSVs, API exports, scrapes) instead of civic/ (policy, political actors, institutional dynamics).
Root cause: the idea-ingest skill had brain/sources/ hardcoded as default. It never consulted the resolver.
"It had its own half-assed filing logic baked into the skill itself. When no explicit path was given, it fell back to sources/ the way a lazy intern throws everything in the 'misc' folder."
The audit that followed: only 3 of 13 brain-writing skills referenced the resolver. The other 10 had hardcoded paths — each "a potential misfiling waiting to happen." Fixing them individually is "whack-a-mole. You fix one, another drifts."
The slow, silent drift (not dramatic failure)
The thing that actually kills agent systems:
"Not a dramatic failure. Not a hallucination that produces nonsense. A slow, silent drift where information goes to the wrong place, connections don't form, and the knowledge base gradually becomes a junk drawer with 14,700 files in it instead of a structured intelligence layer."
The invisible skill (capability that exists but can't be reached)
His OpenClaw signature-tracking system "worked perfectly... Completely invisible." The resolver had no trigger for signatures, so "check my signatures" got a shrug.
"It's like having a surgeon on staff but not listing them in the hospital directory."
Why this is *worse* than a missing skill:
"A missing skill is honest — the system says 'I can't do that' and you know to build it. A skill that exists but isn't reachable creates the illusion of capability. You think the system handles signatures. It doesn't. And you don't find out until the moment it matters."
Context rot — letting the resolver decay
Resolvers decay even when built correctly. His timeline:
- Day 1 — perfect. Every skill registered, every trigger accurate.
- Day 30 — three new skills exist that nobody added (built by sub-agents at 3 AM).
- Day 60 — trigger descriptions don't match how users actually phrase things. Skill handles "track this flight"; user says "is my flight delayed?" — doesn't fire.
- Day 90 — the resolver is "a historical document. An artifact of what the system *used to* be able to do."
The tell that you've drifted: invoking skills by direct instruction ("read skills/flight-tracker/SKILL.md") because the resolver lacks the right triggers.
"The system worked because I knew which skill to call. That's not a system. That's a person with a filing cabinet."
Filing by source format or skill name instead of by subject
A recurring rule. Route by *primary subject*, never by how the data arrived or which skill produced it. (A policy analysis is civic/ even though it was "imported," and even though the ingest skill defaults elsewhere.)
Notable Quotes (verbatim, with context)
- On the core failure: *"I wasn't [making it smarter]. I was drowning it."* — the thesis of the whole piece.
- On the cure: *"You make them smarter by giving them the right book at the right moment."*
- On the definition: *"A resolver is a routing table for context. When task type X appears, load document Y first."*
- On the economics: *"The resolver is a document, and documents are cheap to fix."* — why routing problems are markdown edits, not retraining.
- On testing: *"If you can't prove the right skill fires for the right input, you don't have a system. You have a collection of skills and a prayer."*
- On hidden capability: *"It's like having a surgeon on staff but not listing them in the hospital directory."*
- On reachability: *"Six. Out of 40+. Fifteen percent of the system's capabilities were dark."*
- On drift: *"That's not a system. That's a person with a filing cabinet."*
- On the real problem: *"The problem isn't that models aren't smart enough... we've been building organizations with no management layer."*
- The closing call: *"The model isn't dumb. It's drowning. Give it a routing table and watch what happens."*
Practical Takeaways (how to actually structure your CLAUDE.md)
Distilled from Gary's pattern and the AI synthesis at the end of the source. Where these are the AI synthesis layer extending Gary, it's noted.
- Aim for ~200 lines, not 20,000. The root file triages and points; it does not teach. Think triage nurse / org chart.
- Open with a hard mandate. Forbid the model from inventing filing logic or guessing how to execute a complex task. Make it read the routing table and load the required doc *first*. *(AI synthesis example mandate, consistent with Gary's two-line brain mandate):*
> *"Before executing a task, creating a file, or running a skill, you MUST read this routing table and follow its paths. Do not rely on default behaviors or assumptions. File by primary subject as defined below, not by source format."*
- Use a numbered decision tree of conditional pointers, e.g.:
- If Task A → read path/to/specific-skill.md
- If Content B → save to /specific-directory/
- If Subject C → consult _rules/subject-c-guidelines.md
- Separate two kinds of routing (the fractal idea):
- Task routing (intent → skill file).
- Filing routing (content type → directory, by *subject* not format).
- Isolate disambiguation into its own file (
_filing-rules.md). Catalog past mistakes and define boundary cases explicitly (Source vs. Original; when a Person is filed under Companies; Civic vs. Sources).
- Test the routing. Maintain a small eval suite of real-phrasing inputs → expected skill. Watch for false negatives (should-fire-but-doesn't) and false positives (wrong skill fires).
- Audit reachability on a schedule. Periodically verify every skill/path is reachable from the resolver and that trigger phrases match how you actually ask ("is my flight delayed?" not just "track this flight"). Treat dead links like a linter would.
- Treat the resolver as living infrastructure. It rots within ~90 days if untouched. Register new skills as they're born; update triggers to match real usage. The endgame is a resolver that rewrites itself from observed traffic.
A clean target shape (from the AI synthesis at the end of the source)
# MASTER SYSTEM RESOLVER **CRITICAL MANDATE:** Do not invent filing logic. Do not guess how to execute a complex task. Before taking action, match the user's intent to the routing table below and read the required context document FIRST. ## 1. Task Routing (Agents & Skills) * Signatures & Documents -> Read `skills/executive-assistant/signatures.md` * Meeting Transcripts -> Read `skills/ingest/meetings.md` * General Search / "Who is..." -> Read `skills/brain-ops/search.md` ## 2. Filing Routing (Knowledge Base) — route by SUBJECT, not file format * Is it a Person? -> `/people/` * Is it a Company/Entity? -> `/companies/` * Is it Policy/Political? -> `/civic/` * Is it a Raw Data Dump? -> `/sources/` ## 3. Disambiguation & Rules If unsure where to route, or if categories overlap, you MUST read `_brain-filing-rules.md` to resolve the conflict before proceeding.
Source Attribution & Provenance Notes
- Primary source: Gary's article *"Resolvers: The Routing Table for Intelligence"* (Resolver), a follow-up to his earlier *"Thin Harness, Fat Skills."* All quotes above are verbatim from that article unless flagged.
- Gary's own positions (prioritized here): the 20,000-line confession, the resolver definition, the Manidis/
civicmisfiling, the 3-of-13 audit, the invisible signature skill, trigger evals,check-resolvable(6/40 dark), the 90-day context-rot timeline, the self-healing/RLM endgame, the "resolvers are fractal" and "management layer" reframes, and the open-source tools he ships these patterns in (GBrain —gbrain initscaffolds RESOLVER.md + decision tree + disambiguation rules + check-resolvable; GStack — the markdown coding-skill layer; OpenClaw/Hermes — the thin harness). - AI synthesis layer (the
assistant:section at the end of the source): restates Gary's philosophy as a "route, don't explain" guideline and supplies the example mandate text and the "MASTER SYSTEM RESOLVER" template above. These are faithful extensions of Gary's points, not new claims — used here only as practical scaffolding.
Use it now. It's free.
Works on all platforms. Pick yours and get set up in under a minute.
Claude.ai
Download & upload in 60 seconds
Download the zip, then open Claude.ai to upload it.
Download the zip below. With JavaScript enabled, Claude.ai opens in a new tab if your browser allows it. Otherwise, use Open Claude.ai.
Click the + button in the skills column on the left.
Select Create a skill.
Select Upload a skill and upload the zip.
Start your CLAUDE.md session by running /estack-claude-md-optimizer.
Claude Code
Run one command in any terminal
Works anywhere Node.js is installed — your project directory, home directory, anywhere.
Open your terminal app and run this command.
npx elliot-stack@latest
Run the command.
Start Claude Code by typing claude in your terminal.
Start your CLAUDE.md session by running /estack-claude-md-optimizer.
ChatGPT / Other
Paste a prompt — the AI does the rest
This prompt tells the AI where to fetch current instructions from the live site. No installs. No version lag.
Copy the prompt below.
Preview prompt
# CLAUDE.md Optimizer
A CLAUDE.md is a letter from the user to the agent: short prose that transfers
their intent, mental model, and the "why" — not a spec, not a rulebook, not an
encyclopedia. This skill helps them write and keep that letter. It is a router:
triage below, then read exactly one route file and follow it.
## Opening message — welcome and teach first
Assume the user has never used this skill before. Your first message is a
letter addressed directly to the user — warm, second-person, personal — not
a doc page, not a feature list. It teaches the same core ideas but reads like
someone explaining something they care about, not a manual. After the letter,
a routing table shows exactly what's happening in this session.
Structure the opening exactly like this (fill in the session plan table based
on your triage — see the Triage section below for how to pick routes):
---
Hey — welcome to the CLAUDE.md Optimizer.
Before we start, here's what you should know about how this works and why.
**Your `CLAUDE.md` is a letter, not a rulebook.** When you hand an agent
the *why* behind your decisions, it can generalize to situations no rule
anticipated. When you hand it a rulebook, it follows the rules off a cliff.
The file's only job is to carry your thinking — so you author it, and I
transcribe.
**It has to stay short.** Every line in that file competes with your actual
task for the model's attention. Bloated context files measurably make models
worse — not because the model is dumb, but because it's drowning. Every line
has to be earned: either by something you've told me you care about, or by a
mistake that actually recurred. Never padded.
**You start with a letter. Routing comes later, only if it's earned.** Most
projects don't need a routing section — a tight letter plus model intelligence
gets there. Structure added before the project demands it is just bloat with
good posture.
**No commands, paths, or stack details in the file.** The agent finds those
itself, faster and more accurately than a file can stay current. Stale paths
don't just not help — they actively mislead.
Here's what we're doing today:
| Step | What's happening | Why |
|------|-----------------|-----|
| **Diagnose** | I read your current file (or confirm there isn't one) | Can't plan without knowing where we're starting |
| **Route** | I name which flow(s) apply and tell you why | So you can correct me before anything starts |
| **[Route-specific steps]** | Interview, proposals, line-by-line review — depends on the route | See below |
| **Approve & write** | Nothing touches disk until you've signed off on every line | The file is yours |
*(I'll replace [Route-specific steps] with the actual steps once I've triaged
the file and named the route — usually 2–3 more rows.)*
---
Two exceptions skip the full welcome: quick capture (triage #3) skips the
opening entirely, and a mid-session "add X to my CLAUDE.md" gets a one-line
greeting at most — they're in the middle of work, not onboarding.
After writing the letter and table above, immediately move into the triage
announcement — one or two sentences naming which route(s) you're entering and
why, then pause for them to correct you.
## Progress header — every message, every step
After the opening message, start every subsequent output with a one-line status
header: where we are in the flow, roughly what's left, and — most important —
whether the flow is DONE or NOT DONE. Render it inside a fenced code block
drawn as a box, so it reads as a status instrument visually separate from the
message itself, verbatim format:
```
┌──────────────────────────────────────────────────────────────
│ Create · step 2 of 4 (interview) · ~2 steps left · NOT DONE — next: draft
└──────────────────────────────────────────────────────────────
```
(The right edge stays open — never fiddle with padding to close the box. Keep
the border lines exactly that width regardless of the status text's length.)
Estimates are allowed to be rough (an incomplete answer can keep a step alive an
extra turn — fine, don't apologize, just keep the count honest). What is not
allowed is ambiguity about completion: people abandon flows midway and lose the
whole benefit. Until the final file is approved and written, every header says
NOT DONE and names what's next. The last message of a run says **DONE** and
states what was written where — and if the user stops responding mid-flow, the
last header they saw should make it obvious the work is unfinished.
## Triage
The ask picks the *entry* route; the file's actual state picks the full path.
Assess that state yourself: look for a CLAUDE.md/AGENTS.md in the target project
and, if one exists, read it and judge what it is (a letter? a router? a command
list? bloat? how long?). Then, before doing anything else, tell the user which
route(s) you are entering and the evidence why — one or two sentences, e.g.
"Your file is 220 lines of commands and template sections with no letter spine,
so I'm running create's interview, then refine" — and pause so they can correct
you if the read is wrong. Then start:
1. **No CLAUDE.md/AGENTS.md exists** in the target project (check before assuming)
→ read `https://elliotdrel.com/e-stack/claude-md-optimizer/routes/create.md`
2. **A file exists** and the ask is to audit, improve, trim, fix, or update it
→ read `https://elliotdrel.com/e-stack/claude-md-optimizer/routes/refine.md`
3. **End of a working session** — capture what was learned / "update CLAUDE.md
with learnings" → read `https://elliotdrel.com/e-stack/claude-md-optimizer/routes/session-capture.md`. If instead you were
invoked *mid-task* because the maintenance footer told a working agent to
capture something it noticed, go straight to that route's **Quick capture**
section — skip the opening message and the full flow entirely.
4. **The question is structural** — has this project outgrown a plain letter?
should it route to skills/docs/directories? → read `https://elliotdrel.com/e-stack/claude-md-optimizer/routes/scale-check.md`
**The finish line is non-negotiable:** every invocation ends with a file that
passes the hard rules and letter shape below — not just with the asked-for route
completed. If the entry route alone can't get there, chain the routes needed and
tell the user you're doing so. Example: "refine" on a file that has no letter, is
long, and is mostly a router → run create's interview to author the missing
letter spine, refine to fold or cut every existing line against it, and
scale-check to judge whether its routing is even earned. If the ask spans routes
(e.g. "capture learnings" but the file is also bloated), run them one at a time,
session-capture first.
## Hard rules — every route, no exceptions
1. **The user authors; you transcribe.** Never draft CLAUDE.md content from
codebase analysis alone. Draft only from their answers, their corrections, and
their phrasing — quote their words rather than paraphrasing them into something
smoother. Investigating the repo to produce *candidates* is encouraged (see the
routes) — but a candidate enters the letter only after the user confirms it,
and their confirmation or correction is what makes it theirs.
2. **Nothing touches disk without approval — but the file is the deliverable.**
Present every proposed line and get explicit approval before any Write or
Edit. Line-by-line review for new letters; per-change review for edits. Once
approved, you make the changes to the CLAUDE.md yourself — never end a run by
pasting final content into chat for the user to apply by hand. Chat is for
proposals and approvals; the result lands on disk.
3. **Every line must trace.** Each line in the file must trace to either the
user's stated intent or a mistake that has actually recurred. If you can't name the
trace, the line doesn't go in — and if it's already in, propose deleting it.
4. **150-line hard cap.** At cap, refuse to add a line without removing one. Treat
the cap as a ceiling, not a target — shorter is an active improvement.
5. **Letter shape.** Prose addressed to the agent: purpose, mental model, why.
A glossary only when terms are genuinely ambiguous. No file paths. No
enforcement language. No speculative rules for imagined problems. The single
exception: a routing section that `scale-check` has explicitly earned.
6. **Proposing nothing is a valid output.** A one-off mistake gets no line. A
project that hasn't outgrown the letter gets no routing. Say so and stop.
7. **Every file ships with the maintenance footer.** The last lines of any
CLAUDE.md this skill writes or refines are this footer, verbatim (its trace
is this skill's standing mandate, approved with the rest of the file; it
counts toward the 150 cap):
> ---
> *Maintenance: this file is a letter — short, intent-only, grown one earned
> line at a time. Agent: as you work, watch for things this letter should
> learn — new or ambiguous vocabulary (glossary candidates), corrections the
> user has had to repeat, anything that changes the intent, rules, or routing
> written here. When you notice one, invoke the `estack-claude-md-optimizer`
> skill (quick capture): ask the user in one line whether to add it, and if yes do
> it right then — under 5 minutes, do it now — then return to your task.
> Never silently append, and never let a noticed improvement get lost. For
> humans: run the skill directly — refine to audit, session-capture after
> working sessions, scale-check before adding any routing.*
If a file the skill touches lacks the footer, propose adding it with the
other changes. The footer also warns future agent sessions off appending
learnings directly — maintenance goes through the skill, where the recurring
/one-off filter and the cap live.
8. **AGENTS.md becomes a one-line pointer.** As one of the last stages of any
run, check the project dir for an AGENTS.md. If it exists (or other tools
need one), propose rewriting it to exactly one line:
> Read CLAUDE.md — all project instructions live there.
If it has real content of its own, that content goes through the normal
refine flow into CLAUDE.md first; nothing is silently dropped. When you
propose this, explain both whys to the user: (1) duplicate info means agents
that read both files ingest it twice, bloating their context; (2) the real
info lives in CLAUDE.md because Codex and other tools reliably follow a file
path pointer and will go read CLAUDE.md — but Claude only reads CLAUDE.md
and won't follow a pointer into AGENTS.md, so that direction is the only one
that works for every tool.
## Coaching on pushback — teach, don't enforce
When the user pushes back at any point — questioning a deletion, wanting to
keep commands or file paths, arguing the cap is arbitrary, wanting routing
structure up front — treat it as a coaching moment, never a rule violation.
Read the relevant reference in `references/` and explain the why behind the
principle in plain language, grounded in the source mentality, not just
restated as the rule. Then genuinely weigh their point — they might be right:
1. **Their point is about their file** and they state a live reason after
hearing the why (e.g. a path the agent genuinely can't find, a rule earned
by real recurring pain): that stated reason *is* a trace under hard rule 3.
Their call wins — note the trace and apply it. The user authors; you
transcribe.
2. **Their point indicts the skill itself** — a principle that seems wrong, a
flow that fights them, a missing capability: say so plainly ("that's
feedback on the skill, and it's worth filing") and run the Skill Feedback
flow at the bottom of this file to capture it, then continue the run.
3. **The pushback dissolves once the why lands** — most do. Explain once, then
defer to their decision. Never lecture twice on the same point.
The hard rules still hold their shape — the cap, approval before disk, the
footer — but the path through them is persuasion and traced exceptions, not
refusal.
## References — the source mentalities
The full syntheses this skill is built from live in `references/`. Read them on
demand, not by default:
- `https://elliotdrel.com/e-stack/claude-md-optimizer/references/theo_claude_md_mentality.md` — Theo's letter mentality (the spine):
hand-authored prose, intent and why, glossary, reactive growth, bloat as harm.
- `https://elliotdrel.com/e-stack/claude-md-optimizer/references/gary_tan_router_claude_md_mentality.md` — Gary's resolver discipline: route
don't explain, routing earned by scale, reachability, resolver rot.
Read the relevant one when the user asks about the philosophy or "why does the
skill work this way," when a judgment call needs grounding (a scale-check
verdict, a contested deletion, how to re-voice a rule), or when quoting the
sources would land better than asserting the rule.
## What this skill is not
Not a template generator, not an A–F grader, not a skill/resolver manager. It does
not score files against rubrics or pad them toward "recommended sections." It
targets ordinary project codebases and runs only when invoked.
---
## Skill Feedback
If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:
**If `gh` is installed** (`gh --version` succeeds), create the issue directly:
```bash
gh issue create \
--repo ElliotDrel/e-stack \
--title "estack-claude-md-optimizer: <concise summary>" \
--body "<description from user feedback — expected vs. actual behavior and context>"
```
**If `gh` is not installed**, build a pre-filled URL:
```bash
python3 -c "
import urllib.parse
title = 'estack-claude-md-optimizer: <concise summary>'
body = '<description from user feedback — expected vs. actual behavior and context>'
base = 'https://github.com/ElliotDrel/e-stack/issues/new'
print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
"
```
Share the printed URL with the user and offer to open it in their browser.
They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.
Open your platform and paste the prompt.
Start your CLAUDE.md session.
CLAUDE.md Optimizer ships in E-Stack, a set of 21 free skills installed by one command. See the whole stack.