← Back to skills

Configuration

CLAUDE.md Management

Write and maintain CLAUDE.md project configuration files covering file hierarchy, scoped rules, instruction budgets, and AGENTS.md for Codex.

Last reviewed Mar 2, 2026

Install

Create this file in your project:

.claude/skills/claude-md-management/SKILL.md
--- name: claude-md-management description: Use this skill when creating, updating, or maintaining CLAUDE.md files, AGENTS.md files, or cursor rules for a project. --- # CLAUDE.md Management ## When to Use - Setting up a new project with Claude Code or Codex - Updating project configuration after architecture changes - Onboarding a new codebase for AI-assisted development - Reviewing and optimizing existing CLAUDE.md files ## Process 1. **Audit the project** -- Understand the tech stack, build commands, test commands, project structure, and key conventions. 2. **Determine scope** -- Decide which instructions go at which level: - Root `CLAUDE.md` -- Universal project rules, build/test/lint commands, core conventions. - Subdirectory `CLAUDE.md` -- Directory-specific rules (e.g., `frontend/CLAUDE.md` for React patterns). - `AGENTS.md` -- Additional context for Codex agents (permissions, deployment rules). 3. **Write concise instructions** -- Every line costs tokens. Include: - Build, test, lint, and deploy commands - Key architectural decisions and patterns - Common pitfalls specific to this codebase - File naming conventions and project structure 4. **Exclude obvious things** -- Do not document what is obvious from the code itself. Focus on what's surprising, non-obvious, or frequently violated. ## Rules - Keep CLAUDE.md files concise. Aim for under 100 lines per file. - Include exact commands, not descriptions: `npm run test:unit` not "run the unit tests." - Document patterns that are NOT obvious from reading the code. - Use scoped files for directory-specific rules rather than bloating the root file. - Review and prune regularly. Stale instructions are worse than no instructions. - For Codex: put sandbox and permission rules in AGENTS.md, not CLAUDE.md. - Never include secrets, API keys, or credentials in these files.

What this skill does

CLAUDE.md Management helps you create and maintain the configuration files that guide AI coding assistants in your project. These files -- CLAUDE.md for Claude Code, AGENTS.md for Codex -- act as a project-specific instruction manual that tells the AI about your conventions, commands, and constraints.

The skill emphasizes conciseness because these files are read on every interaction, consuming tokens. Every unnecessary line adds cost and noise. The best CLAUDE.md files capture the non-obvious: the build command that needs a special flag, the naming convention that differs from the framework default, the architectural decision that explains why things are structured a certain way.

The hierarchical approach -- root file for universal rules, subdirectory files for scoped rules -- keeps instructions relevant. An AI working in the frontend directory doesn't need to read backend deployment rules, and vice versa.

Example workflow

You ask the agent to set up CLAUDE.md for a Next.js monorepo. The agent will:

  1. Audit the project: find the build system (Turborepo), test framework (Vitest), linter (ESLint), and key conventions.
  2. Create root CLAUDE.md with: build/test/lint commands, monorepo structure overview, shared conventions.
  3. Create apps/web/CLAUDE.md with: Next.js-specific patterns, server component conventions, data fetching approach.
  4. Create packages/ui/CLAUDE.md with: component naming, Storybook commands, export patterns.
  5. Create AGENTS.md with: sandbox permissions, allowed deployment targets.

Tips

  • Start minimal and add rules only when the AI makes a mistake that a rule would prevent
  • Treat CLAUDE.md like code -- review it in PRs, keep it up to date, delete stale entries
  • Test your CLAUDE.md by starting a fresh conversation and seeing if the AI follows the rules
  • The most valuable entries are usually the ones you add after a frustrating debugging session

Best with tools

    Related MCP servers

    • No linked MCP servers yet.

    Related skills

    Claude Automation Recommender

    Analyze a codebase and recommend Claude Code automations: hooks, subagents, skills, custom slash commands, and MCP servers.