The CLAUDE.md that grew a line every time the agent got something wrong

Picture the agent getting a deploy wrong: it skips the database backup, and you catch it before anything breaks. So you open CLAUDE.md, the file Claude Code reads at the start of every session, and you add the deploy steps. Now they are written down.

Most of us have done this before. The migration checklist goes in after a bad migration. The release routine goes in after a messy release. The brand colors go in after the agent invents a new shade of blue. Each addition is reasonable, and a month later the file holds everything you have ever had to explain to the agent, most of it about jobs it isn't doing right now.

So what belongs in that file, and where does the rest go?

One question for every line

Seth put our view of the big-file habit plainly: "A lot of people are still treating their agent as one global configuration. And that's something that we reject in our principles."

The question we ask of each line in CLAUDE.md is this: would it be true no matter what the agent is doing? "Write American English" passes. So does "never put a password in a commit." Those apply whether the agent is renaming a variable or drafting a customer email, so they are worth reading every time.

The deploy steps fail the question. They matter on deploy day and nowhere else. Our bet, and it is a bet rather than something we have measured, is that every line about some other job is one more thing between the agent and the task in front of it. So a task-specific procedure can move into a skill. For a step that must happen on every deploy, such as checking the backup, put the check in the deploy script or a hook as well.

What moving one section looks like

In Claude Code, a project skill lives in its own folder as .claude/skills/<task>/SKILL.md (the folder can hold supporting files too). The file starts with a short description of what the skill does and when to use it, and the steps follow. According to Claude Code's documentation, the agent sees only the name and description of each skill until a task matches one, and then it reads the whole file.

Here is an example deploy section, moved:

---
name: deploy
description: Deploys this app to production. Use when asked to deploy, ship or release, or before any command that touches the production server.
---

1. Back up the database and confirm the backup file exists.
2. Run the full test suite; stop if anything fails.
3. Run the deploy script and watch for the health check.
4. Open the live site and check one page you changed.

The description does much of the work. Claude Code lists it alongside the skill's name before deciding whether to load the full instructions. We write it in two halves: what the skill does, then when to use it. A description that only says "deploy helper" leaves the agent guessing about when it applies.

What stays in CLAUDE.md is short. In the free PER kit, the smallest example we publish, the rules that always apply fit on about one printed page, and the four job procedures wait in skills. Seth's own setup has the same shape at a bigger size: about two pages of rules that hold everywhere, and 31 separate skills for jobs like building the website, writing Crystal code and designing a blog page.

Skills can also belong to one folder. The notes folder where we plan our work has its own plan and reflect skills, so work started there picks up the versions of those procedures that fit it.

The weak spot

Skills have one weakness worth knowing before you rely on them. A long session eventually fills the agent's memory, and Claude Code then replaces the conversation with a summary. When we checked what those summaries kept, almost none of the wording of the skills the agent had loaded made it through (the evidence note has the counts and the limits). Claude Code adds some skills back after a summary, though not all of them in our sample. So for long work, we write down which skills the job depends on, and the agent reloads them. That is its own post.

Try this today

Open your CLAUDE.md and find the longest section that only matters for one kind of job. Ask Claude Code: "Move this section into .claude/skills/<name>/SKILL.md, with a description that says what it does and when to use it, and delete it from CLAUDE.md." Then ask for that job once and see whether the agent picks the skill up. Step 1 of the lesson walks through the full split.

The file the agent reads every time should hold only what is true every time. Everything else can wait until it is called.

How we tested it

This post describes how we arrange our own setup; it does not report a test of whether a long CLAUDE.md makes an agent worse. What we can state exactly:

• The PER kit's split: CLAUDE.md is 53 lines with 11 rules; the skills are plan (94 lines), execute (50), reflect (70) and run-task (87). Release v0.1.0, checked against its published hashes on November 1, 2026.
• Seth's setup: 107 lines in his global CLAUDE.md and 31 skills holding 7,317 lines, counted with wc -l on November 1, 2026. This is our own machine, so you can't check it, and it changes often.
• How skills load: taken from Claude Code's documentation, not measured by us. Loading depends on the agent matching your request to the description, so a vague description can be missed; that is why we write the "when to use it" half with care.
• Compaction: in 42 summaries from 15 of our sessions, we found 28 cases where a skill had been loaded before the summary. In 21 of those 28, the summary kept no five-word phrase from the skill word for word. That measures wording in the summary only: it misses paraphrase, and skills Claude Code attached again afterward. The evidence note has the full counts and limits.

Next in the series: You wrote the late-fee rule. What does it mean now?