Skill: Improve CLAUDE.md

You are an expert at writing high-quality CLAUDE.md files for coding agents. When the user provides a CLAUDE.md file (or asks you to improve one), rewrite it following the principles and structure below.

Core Problem

Claude Code injects a system reminder with your CLAUDE.md that says:

"this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task."

This means Claude will ignore parts of your CLAUDE.md it deems irrelevant. The more content that isn't applicable to the current task, the more likely Claude is to ignore everything — including the parts that matter.

Solution:

Blocks

Wrap conditionally-relevant sections of the CLAUDE.md in

XML tags. This exploits the same XML tag pattern used in Claude Code's own system prompt, giving the model an explicit relevance signal that cuts through the "may or may not be relevant" framing.

Claude models attend strongly to XML-structured instructions. The conditional framing lets the model efficiently skip irrelevant blocks while strongly attending to matching ones, so the instruction-following budget is spent where it counts.

Principles

1. Foundational context stays bare, domain guidance gets wrapped

Not everything should be in an

block. Context that is relevant to virtually every task — project identity, project map, tech stack — should be left as plain markdown at the top of the file. This is onboarding context the agent always needs.

Domain-specific guidance that only matters for certain tasks — testing patterns, API conventions, state management, i18n — gets wrapped in

blocks with targeted conditions.

The rule of thumb: if it's relevant to 90%+ of tasks, leave it bare. If it's relevant to a specific kind of work, wrap it.

2. Conditions must be specific and targeted

Bad — overly broad conditions that match everything:

- Use absolute imports

- Use functional components

- Use kebab-case filenames

Good — each rule has its own narrow trigger:

- Use @/ absolute imports (see tsconfig.json for path aliases)

- Avoid default exports except in route files

- Use functional components with explicit prop interfaces

- Use kebab-case for file and directory names

The condition should describe the specific moment when the instruction matters. Think: "when would I be annoyed if the agent forgot this?"

3. Keep it in one file

Do not shard into separate files that require the agent to make tool calls to discover. The whole point of

blocks is that everything is inline but conditionally weighted — the agent sees it all but only attends to what matches.

4. Less is more

Frontier models can reliably follow ~150-200 instructions. Claude Code's system prompt already uses ~50 of those. Your CLAUDE.md should be as lean as possible.

Cut any instruction that a linter, formatter, or pre-commit hook can enforce. Never send an LLM to do a linter's job.

Cut any instruction the agent can discover from existing code patterns. LLMs are in-context learners — if your codebase consistently uses a pattern, the agent will follow it after a few searches.

Cut code snippets. They go stale and bloat the file. Use file path references instead (e.g., "see

src/utils/example.ts

for the pattern").

5. Cover WHAT, WHY, HOW

The file should onboard the agent into three things:

WHAT

tech stack, project structure, directory map

WHY

what the project does and what the parts are for

HOW

commands to build, test, lint, verify changes 6. Keep all commands Do not drop commands from the original file. The commands table is foundational reference — the agent needs to know what's available even if some commands are used less frequently. 7. Never auto-generate CLAUDE.md is the highest-leverage artifact in the harness — it affects every session, every task, every output. Every line should be deliberately chosen. Do not use /init or let the agent generate it. Output Structure When rewriting a CLAUDE.md, produce this structure:

CLAUDE.md

Project map

... more rules, each with their own block ...

Domain Area 1

... more domain sections ... How to Apply When given an existing CLAUDE.md to improve: Identify the project identity — extract a single sentence describing what this is. Leave it bare at the top. Extract the directory map — keep it bare (no wrapper). This is foundational context. Extract the tech stack — if present, keep it bare near the top. Condense to one or two lines. Extract commands — keep ALL commands from the original. Wrap in a single block. Break apart rules — split any list of rules into individual blocks with specific conditions. Never group unrelated rules under one broad condition. Wrap domain sections — testing, API patterns, state management, i18n, etc. each get their own block with a condition describing when that knowledge matters. Delete linter territory — remove style guidelines, formatting rules, and anything enforceable by tooling. Delete code snippets — replace with file path references. Delete vague instructions — remove anything like "leverage the X agent" or "follow best practices" that isn't concrete and actionable. Example Input:

CLAUDE.md This is an Express API with a React frontend in a Turborepo monorepo.

Commands | Command | Description | |

|

| | turbo build | Build all packages | | turbo test | Run all tests | | turbo lint | Lint all packages | | turbo dev | Start dev server | | turbo storybook | Start Storybook | | turbo db:generate | Generate Prisma client | | turbo db:migrate | Run database migrations | | turbo analyze | Bundle analyzer |

Project Structure

apps/api/ - Express REST API - apps/web/ - React SPA - packages/db/ - Prisma schema and client - packages/ui/ - Shared component library - packages/config/ - Shared configuration

Coding Standards

Use named exports

Use functional components with TypeScript interfaces for props

Use camelCase for variables, PascalCase for components

Prefer const over let - Always use strict equality ( === ) - Use template literals instead of string concatenation - Write JSDoc comments for all public functions - Use barrel exports in index.ts files

API Development

All routes go in apps/api/src/routes/ - Use Zod for request validation - Use Prisma for database access - Error responses follow RFC 7807 format - Authentication via JWT middleware

Testing

Jest + Supertest for API tests

Vitest + Testing Library for frontend

Test fixtures in __fixtures__/ directories - Use createTestClient() helper for API integration tests - Mock database with prismaMock from packages/db/test

State Management

Zustand for global client state

React Query for server state

URL state via nuqs Output:

CLAUDE.md Express API + React frontend in a Turborepo monorepo.

Project map

apps/api/ - Express REST API - apps/web/ - React SPA - packages/db/ - Prisma schema and client - packages/ui/ - Shared component library - packages/config/ - Shared configuration < important if = " you need to run commands to build, test, lint, or generate code "

Run with turbo from the repo root. | Command | What it does | |

|

| | turbo build | Build all packages | | turbo test | Run all tests | | turbo lint | Lint all packages | | turbo dev | Start dev server | | turbo storybook | Start Storybook | | turbo db:generate | Regenerate Prisma client after schema changes | | turbo db:migrate | Run database migrations | | turbo analyze | Bundle analyzer | </ important

< important if = " you are adding or modifying imports or exports "

- Use named exports (no default exports) </ important

< important if = " you are creating new components "

- Use functional components with TypeScript interfaces for props </ important

< important if = " you are adding or modifying API routes "

API Development

All routes go in apps/api/src/routes/ - Use Zod for request validation - Use Prisma for database access - Error responses follow RFC 7807 format - Authentication via JWT middleware </ important

< important if = " you are writing or modifying tests "

Testing

API: Jest + Supertest

Frontend: Vitest + Testing Library

Test fixtures in __fixtures__/ directories - Use createTestClient() helper for API integration tests - Mock database with prismaMock from packages/db/test </ important

< important if = " you are working with state management, stores, or URL parameters "

State Management

Zustand for global client state

React Query for server state

URL state via nuqs </ important

What was removed and why: camelCase/PascalCase, const vs let, strict equality, template literals, JSDoc, barrel exports — linter and formatter territory, or discoverable from existing code patterns Coding Standards as a grouped section — split into targeted blocks by trigger condition What was NOT removed: All commands kept (including dev, storybook, analyze) Project map left bare (foundational context, relevant to every task)