I cut my agent’s instruction file by 62% and kept every rule

In March I published the rule I use for keeping AI agent instructions manageable: put methodology in skills, while identity and safety invariants stay in the instruction file intended to load every session. I recorded that file at 136 lines and considered the problem handled. By August it had reached 54,825 bytes against a 55,000-byte limit I had set: 99.7 percent full.

My 136 lines had become 465. Each incident brought a rule, its story, a worked example and the rationale that would make a future session take it seriously. Much of the growth was teaching material. I was putting it in the standing instruction layer whether the next task needed that subject or not.

Raising the budget would buy time while the file kept growing. Dropping rules would discard lessons I had already paid to learn. I kept the constraints and gave their procedures and explanations named homes. The rewrite preserved each rule’s operative instruction in the kernel or its designated destination, while reducing the standing file by 62 percent.

The archived source files from August 18 measure 54,825 and 21,026 UTF-8 bytes. That removes 33,799 bytes: (54,825 − 21,026) / 54,825 × 100 = 61.6489%, rounded to 62 percent. The denominator is the original file size. The 55,000-byte figure was my local authoring budget, not a limit set by Claude or OpenAI.

The revised source had 122 lines and used 38.2 percent of that budget. One source generated the instructions for the two clients I used, Claude Code and OpenAI Codex. These are UTF-8 source-file measurements, not token counts.

Three jobs for the smaller file

I think of this short instruction layer as a kernel: the part intended to remain available while detailed procedures load when needed.

Keep operative invariants. These are the constraints that should apply before the agent decides which workflow to use. The kernel keeps their direct rule text, with a pointer to the explanation. My design compressed these rules into one to four lines each; the incident story and worked examples belonged in the destination document.

Map task types to skills. A writing task points to the writing stack; work on a named project points to the project-management stack. The table gives the agent a route from the task to the procedure. Verify that the client exposes the skill and that the task actually triggers its use.

Name mechanical checks and their boundaries. An enforcement declaration identifies the check that backs a rule. A fail-closed check refuses to proceed when it cannot perform its protective function. Before relying on one, verify the path where it runs, the cases it covers and how a failure blocks the action.

Worked examples and procedure detail can then live in skills, mechanical checks in executable guards, and lookup material in reference files.

Classify each obligation before moving it

The migration matrix has 62 entries: 61 from the existing file and one new rule introduced during the work. I assigned each entry a primary class:

Primary classEntriesIntended home
Always-on invariant25Operative text in the kernel, with explanation elsewhere
Task-specific procedure28A skill, with a route from the kernel
Mechanically checked rule6An executable check, named in the kernel
Lookup or reference material3A reference file loaded when needed

A primary class does not mean a rule needs only one home. A never-send rule backed by a hook that recognizes today's messaging tools still needs its prose constraint: a new tool name may fall outside that matcher's coverage. Moving the whole rule into the hook would leave that case unaddressed.

The same reasoning applies to a rule against abandoning authorized work. It has to be available in a session drifting toward abandonment, without depending entirely on that session first choosing a skill about persistence. Some constraints need a kernel remnant even when their detailed procedures have a skill home.

Open the destination and inspect the rule

My migration matrix recorded the obligation, destination, class and evidence that the destination carried its substance. Opening those files changed the plan. Rules I remembered as living in a skill existed only in private lesson notes; one had no home beyond a session log. A migration based on my memory would have dropped them.

For a migration of your own, record the original operative clause before editing it. Then inspect the proposed destination for that clause's meaning, including its conditions and exceptions. A file with the right name may contain an explanation of the subject without the rule you need.

  1. Keep a copy of the original. Give every obligation a stable identifier so it can be traced through the move.
  2. Build the destination homes. Add missing procedures and explanations before removing them from the active file. During the transition, check duplicate wording for conflicts and identify which copy is authoritative.
  3. Review coverage and access. Open each destination, check the operative meaning, and verify the route that is supposed to make it available. Keep placement evidence separate from evidence that an agent actually loaded it.
  4. Exercise the enforcement paths you will rely on. A check's health test is useful, but also inspect the allowed and refused actions at the actual boundary. Different clients and newly introduced tools need their own coverage assessment.
  5. Rewrite the kernel last and retain the archive. Compare the result with the inventory, rather than with a recollection of what the old file said.

Enforce the budget on every write path

My budget had three parts: refuse a source over 55,000 bytes, warn at 85 percent, and validate every path that could install a changed file. The warning begins at 46,750 bytes. A file of exactly 55,000 bytes is permitted; 55,001 is refused.

My installer checked the budget, but the hook that propagated source edits to the installed files did not. The same oversized content could therefore be refused on one path and installed through the other. I added the missing validation to the edit-propagation path.

A useful test of this design supplies the same over-budget candidate to each write path and checks both the refusal and the preservation of the previously installed file.

What loads, according to current client documentation

In documentation checked on September 28, 2026, OpenAI's AGENTS.md guide describes layered instruction files, overrides and the project_doc_max_bytes setting, documented with a 32 KiB default. That is a separate client setting from my 55,000-byte authoring budget.

OpenAI's skills guide describes starting with skill names and descriptions and loading a full SKILL.md when the skill is selected. It supports explicit invocation and selection based on the description.

Claude Code's memory documentation makes a useful distinction for migrations: imported files can still load at launch. Splitting a large CLAUDE.md into files that it imports may organize the material without reducing startup context. Its skills documentation describes regular sessions that carry skill descriptions and load the full content when invoked; invocation settings can change which descriptions are exposed.

For a real migration, inspect what the chosen client loaded in a fresh session, then observe the tasks and denied actions that matter to your rules. Record the client, configuration, task and result.

A five-rule placement workbook

The downloadable workbook contains five fictional obligations, inert text files, a migration table and a Python checker. It checks placement without installing a skill or changing an agent’s configuration.

RulePlacement checkedActual client behavior
preserve-sourceThe kernel says to keep the original source unchanged while preparing a revision.Unmeasured
verify-dateThe kernel forbids inferring a publication date from a file's modification time.Unmeasured
format-responseA report procedure contains its operative clause, and the kernel names a route to it.Unmeasured
choose-workflowA data procedure requires inspecting the input schema, and the kernel names a route to it.Unmeasured
block-invalid-inputThe kernel declares a malformed-JSON guard; a separate record says its execution is unmeasured.Unmeasured

The fixed expectations were written before the checker. That independent list catches an omission even when the edited matrix and destination agree: delete verify-date from both, and the check still fails because the original expectation retains it.

From the extracted workbook directory, run:

python3 -B check.py sample
python3 -B -m unittest -v

The successful sample reports STATIC_CHECKS_PASS, placement: PASS and native_behavior: UNMEASURED. The tests remove individual obligations, remove required text from an existing destination, remove routing entries and exceed the byte budget by one byte. They cover multibyte UTF-8 characters and CRLF line endings, which must be counted as stored bytes.

The workbook also rejects a claimed native PASS, even when accompanied by a file shaped like an execution receipt. It cannot authenticate such a receipt. Its literal checks have another deliberate limit: appending a contradictory instruction leaves the required lines present, so placement still passes. Reviewing meaning and observing behavior remain separate work.

The connection to project memory

I had already used a similar design one layer down. The tiered context architecture put a 150-line budget on a project's CONTEXT.md, moved stable facts to a reference file, and archived session history monthly. Material left the active file only after its destination had been checked. That account called the process garbage collection for context.

It took me longer to apply this to standing instructions because their contents felt too important to touch.

The analogy helped with standing instructions: both systems need a small active layer and a way to recover the material kept elsewhere. Their contents have different jobs, so the move needs different checks. An old session narrative can remain useful in an archive; a safety invariant may need to stay present before any retrieval happens.

My skills catalog had begun with another extraction. In the March account, I described converting 67 private runbooks, over 13,000 lines, into portable skills because the same methodology kept being explained to new sessions. By August, the standing instruction file was showing the same accumulation in a different place.

When you keep pasting the same procedure into prompts, that is a skill trying to be born. Give it a named home, retain the constraints that must apply before it loads, and check the route back to its detail. The public instruction-kernel pattern describes the classes, migration order and budget design.

My file spent five months growing toward its ceiling before I treated that growth as an architectural problem. Yours is growing right now.