Split Memory

What it does

When your agent uses it

• Mentions split CLAUDE.md
• Modular instructions
• Organize instructions
• Multiple CLAUDE files

Example prompts

• “split CLAUDE.md”
• “modular instructions”
• “too long”
• “/split-memory”

Requirements

• Docker

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

1. 1Start monolithic, split when it hurts — A single CLAUDE.md is simpler to maintain, easier to understand, and has no conflict risk. Only…
2. 2Root CLAUDE.md is the index — After splitting, the root CLAUDE.md becomes a concise index that points to detailed files. It contains only…
3. 3Claude auto-discovers .claude/ files — Claude Code automatically reads files in the .claude/ directory. Use this to your advantage: place…
4. 4No conflicting instructions across files — When instructions span multiple files, contradictions cause unpredictable behavior. Establish…
5. 5Split by a single axis — Split by concern (architecture, testing, API) OR by module (Orders, Catalog, Identity) OR by team. Never mix axes…

What it can do on your machine

Read from SKILL.md and the folder at commit a31015f. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown).

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Split Memory loads about 2.3k tokens when it runs. Until then it costs about 127 tokens; SKILL.md has 522 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~127

When it runs · the whole SKILL.md, loaded when a task matches

~2.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from Resgrid/Core at commit a31015f, republished under its Apache-2.0 licence (© Resgrid). 522 words, ~2,293 tokens.

name

split-memory

description

Modular CLAUDE.md management strategy for projects that outgrow a single instruction file. Covers when and how to split a monolithic CLAUDE.md into multiple files, organizing by concern, module, or team. Includes precedence rules to prevent conflicting instructions. Load this skill when CLAUDE.md exceeds 300 lines, when multiple teams need different instructions, when the user mentions "split CLAUDE.md", "modular instructions", "too long", "organize instructions", or "multiple CLAUDE files".

project-root/
├── CLAUDE.md              # Everything in one file (under 300 lines)
├── src/
└── tests/

project-root/
├── CLAUDE.md                          # Index + universal rules (~50 lines)
├── .claude/
│   └── instructions/
│       ├── architecture.md            # Architecture patterns, module boundaries
│       ├── coding-standards.md        # C# conventions, naming, formatting
│       ├── testing.md                 # Test strategy, fixtures, conventions
│       ├── api-design.md             # Endpoint patterns, versioning, auth
│       ├── data-access.md            # EF Core patterns, migrations
│       └── deployment.md             # Docker, CI/CD, environments

# [Project Name]

## Universal Rules
- .NET 10 / C# 14 — use modern language features everywhere
- TimeProvider over DateTime.Now — always
- No repository pattern over EF Core

## Detailed Instructions
See `.claude/instructions/` for topic-specific guidance:
- `architecture.md` — Project structure, module boundaries, patterns
- `coding-standards.md` — C# conventions, naming, formatting rules
- `testing.md` — Test strategy, fixtures, what to test and how
- `api-design.md` — Endpoint patterns, versioning, authentication
- `data-access.md` — EF Core usage, query patterns, migrations
- `deployment.md` — Docker, CI/CD pipeline, environment config

project-root/
├── CLAUDE.md                          # Index + cross-cutting rules
├── src/
│   ├── Modules/
│   │   ├── Orders/
│   │   │   ├── CLAUDE.md              # Orders-specific patterns and rules
│   │   │   └── ...
│   │   ├── Catalog/
│   │   │   ├── CLAUDE.md              # Catalog-specific patterns and rules
│   │   │   └── ...
│   │   └── Identity/
│   │       ├── CLAUDE.md              # Identity-specific patterns and rules
│   │       └── ...
│   └── Shared/
│       └── CLAUDE.md                  # Shared kernel rules

# Orders Module

## Architecture
This module uses Vertical Slice Architecture. Each feature is one file under Features/.

## Domain Rules
- OrderId is a strongly-typed ID (not raw Guid)
- All monetary values use decimal, never double
- Order state transitions: Draft → Confirmed → Shipped → Delivered → Cancelled

## Integration Events Published
- OrderCreated, OrderConfirmed, OrderShipped, OrderCancelled

## Integration Events Consumed
- ProductPriceChanged (from Catalog), PaymentCompleted (from Billing)

HIGHEST PRIORITY:
1. Root CLAUDE.md — universal rules override everything
2. .claude/instructions/*.md — concern-specific rules
3. Module-level CLAUDE.md (src/Modules/X/CLAUDE.md) — module-specific rules
LOWEST PRIORITY:
4. Team-level files (.claude/teams/*.md) — team conventions

CONFLICT RESOLUTION:
- If root says "use TimeProvider" and module says "use DateTime.Now"
  → Root wins. Module file is wrong and should be fixed.
- If root is silent on a topic and module defines a rule
  → Module rule applies within its scope.
- If two module files contradict each other
  → Each applies only within its own module. No cross-module conflicts.

// BAD — same topic defined differently in two files
# .claude/instructions/api-design.md
"Use Results.Ok() for all endpoint return types"

# .claude/instructions/coding-standards.md
"Use TypedResults.Ok() for all endpoint return types"
*Claude gets contradictory instructions. Behavior is unpredictable.*

// GOOD — one owner per topic
# .claude/instructions/api-design.md
"Use TypedResults.Ok() for all endpoint return types — provides OpenAPI metadata"

# .claude/instructions/coding-standards.md
(no mention of API return types — that's api-design.md's domain)

// BAD — files scattered without a map
project/
├── CLAUDE.md (doesn't mention the other files)
├── .claude/
│   └── instructions/
│       ├── architecture.md
│       ├── testing.md
│       └── data-access.md
*Claude may not know these files exist or how they relate*

// GOOD — root CLAUDE.md is the table of contents
project/
├── CLAUDE.md (lists all instruction files and their scope)
├── .claude/
│   └── instructions/
│       ├── architecture.md
│       ├── testing.md
│       └── data-access.md

// BAD — split by concern AND by module simultaneously
.claude/
├── instructions/
│   ├── architecture.md       # talks about Orders module
│   └── testing.md            # also talks about Orders module
├── modules/
│   └── orders/
│       └── instructions.md   # also talks about architecture and testing
*Three files all have opinions about Orders testing. Who wins?*

// GOOD — pick one axis
# Option A: Split by concern (if cross-cutting rules dominate)
.claude/instructions/architecture.md
.claude/instructions/testing.md

# Option B: Split by module (if module-specific rules dominate)
src/Modules/Orders/CLAUDE.md
src/Modules/Catalog/CLAUDE.md

© Resgrid, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .forge/skills/split-memory of Resgrid/Core.

Open the folder on GitHubat commit a31015f