How to Configure Claude Code with CLAUDE.md, AGENTS.md, and Skills

Claude Code reads markdown files to understand how it should behave. These aren’t documentation for humans. They’re instructions for the agent. The right configuration files turn Claude from a generic assistant into one that knows your project’s conventions, your team’s preferences, and the specific ways you want work done.

There are three types of configuration files that matter: CLAUDE.md for project instructions Claude Code reads, AGENTS.md for the same instructions in a format any agent reads, and Skills for reusable slash commands.

CLAUDE.md: project instructions

CLAUDE.md is the most important configuration file. It’s a markdown file that Claude Code reads at the start of every session to understand how to work in your project. Think of it as onboarding documentation for an AI teammate.

What goes in a CLAUDE.md

A good CLAUDE.md covers the things a new contributor would need to know:

# Project: Acme API

## Stack
- TypeScript, Express, Prisma, PostgreSQL
- Tests: Vitest with in-memory SQLite

## Conventions
- Use snake_case for database columns, camelCase for TypeScript
- All API responses use the `{ data, error, meta }` envelope
- Keep files under 400 lines

## Commands
- `npm run dev` — start dev server
- `npm test` — run test suite
- `npm run lint` — lint and format

## Rules
- Never modify migration files after they've been committed
- Always add tests for new API endpoints
- Use Zod for request validation, not manual checks

Without a CLAUDE.md, Claude Code still works. It reads your code and makes reasonable guesses. With one, it follows your specific patterns instead of inventing its own. The difference really shows on larger projects where conventions matter.

Where CLAUDE.md files live

Claude Code looks for CLAUDE.md files in several locations, each with a different scope:

• Project root (./CLAUDE.md). Instructions for this specific project. This is the most common location.
• Home directory (~/CLAUDE.md). Global instructions that apply across all your projects. Good for personal preferences like “keep files under 600 lines” or “use descriptive variable names.”
• Subdirectories (./src/CLAUDE.md). Instructions scoped to a specific part of your project. Useful for monorepos where different directories have different conventions.

When multiple CLAUDE.md files exist, Claude reads all of them. Project-level files override global ones for conflicting instructions.

Common mistakes

Too vague: “Write good code” tells Claude nothing. Be specific: “Use early returns instead of nested if-else blocks.”

Too long: A 2,000-line CLAUDE.md is noise. Keep it to the essentials: conventions, commands, and hard rules. Claude can read your code for the rest.

Outdated: If your CLAUDE.md says “use Jest” but your project switched to Vitest, Claude will fight your actual setup. Keep it current.

AGENTS.md: instructions any agent can read

AGENTS.md is the tool-agnostic version of CLAUDE.md. The format describes itself as a README for agents: one predictable place to put the context and instructions an agent needs to work on your project. More than 25 tools read it, including Codex, Gemini CLI, Cursor, Aider, goose, Zed, Jules, and GitHub Copilot’s coding agent. Claude Code reads it too.

AGENTS.md vs CLAUDE.md

The two files hold the same kind of content. The difference is who reads them.

	CLAUDE.md	AGENTS.md
Read by	Claude Code	25+ agent tools, Claude Code included
Scope	One tool	Any agent you run
Contents	Project instructions	Project instructions

Both cover the same ground: what the project is, the setup and build commands, how to run the tests, the code style, and the commit and PR rules.

So which do you write? If Claude Code is the only agent you run, a CLAUDE.md is enough. If you run more than one agent, or expect to, put the instructions in AGENTS.md and have CLAUDE.md point at it:

# CLAUDE.md

Project-specific notes for Claude Code go here.

@AGENTS.md

That way there is one source of truth and no second copy to drift. This site’s own repository is set up exactly that way.

Nested files in a monorepo

AGENTS.md files nest. Put one at the repository root for the shared rules, then add another inside a package or app directory for rules that only apply there. The closest file to the code being edited wins, so a subdirectory can override the root without repeating everything in it.

AGENTS.md in crystl

Starter files seed an AGENTS.md into every new gem, so each project begins with the same agent guidelines instead of a copy-paste from the last repo.

crystl also maintains a section of its own inside AGENTS.md, between two crystl-cli markers. That section documents the crystl CLI for whichever agent is reading the file, and it is rewritten when crystl updates, so the command reference an agent sees never falls behind the app. Everything outside the markers belongs to you and is left alone.

If what you actually want is a role, not a project instruction file, that is a different feature. See hero shards for a single specialist agent and crystl quest for a party of them, each with its own persona.

Skills: reusable slash commands

Skills are markdown files that define custom slash commands for Claude Code. When you type /review or /test in a Claude session, it reads the corresponding skill file and follows its instructions.

What a skill looks like

A skill is a markdown file saved to ~/.claude/skills/<skill-name>/SKILL.md:

# /review — Code Review

Review the staged changes in this repository. For each file:

1. Check for bugs, edge cases, and logic errors
2. Verify error handling is complete
3. Flag any security concerns (injection, auth, data exposure)
4. Note style issues only if they affect readability

Format your review as:
- **File:** path
- **Issues:** bulleted list
- **Verdict:** approve, request changes, or needs discussion

Be direct. Don't praise code that's merely correct.

When you type /review in Claude Code, it reads this file and follows the instructions. Skills turn multi-paragraph prompts into single commands.

Why skills matter

Without skills, you either:

1. Type the same detailed prompt every time you want a code review, test run, or deployment check
2. Give a vague instruction like “review this” and get inconsistent results

Skills solve both problems. You write the detailed prompt once, save it as a skill, and invoke it with a slash command from that point forward. The quality stays consistent because the instructions are always the same.

Useful skill categories

Code quality: /review, /lint-check, /simplify, /refactor

Testing: /test, /write-tests, /coverage-check

Workflow: /commit (with your preferred commit message format), /changelog, /deploy-check

Documentation: /document, /explain, /write-readme

Managing configuration files with crystl

Creating and maintaining these files by hand works, but it gets tedious, especially when you start new projects often. This is where the crystl Library comes in.

Starter files

The library includes CLAUDE.md starter files tailored to different stacks and project types. When you create a new gem in crystl, you can select a starter bundle and it drops a pre-configured CLAUDE.md into your project. You start with sensible defaults instead of a blank file.

Skills library

The skills library is a browsable collection of pre-built slash commands. Each one is a tested, ready-to-use SKILL.md that you can import into your Claude Code setup. Instead of writing your own /review skill from scratch, you grab one from the library and customize it.

Heroes

Heroes are pre-built agent personas for crystl quest. Each hero has defined stats (strength, intelligence, wisdom, dexterity) that map to behavioral parameters: how persistent the agent is, how deeply it analyzes problems, whether it asks before acting, and how fast it works. Where AGENTS.md tells every agent about the project, a hero decides who the agent is, so the two sit side by side rather than replacing each other.

Prompts & commands

Prompts are one-click prompts you can inject into any Claude session. They’re lighter than skills, handy for things you do often but don’t need a full slash command for. “Explain this function,” “write tests for the current file,” “suggest three ways to simplify this.” Commands are executable shortcuts that run common multi-step operations like committing, rebasing, or deploying.

Putting it together

A well-configured Claude Code setup looks like this:

1. CLAUDE.md in your project root. Your project’s stack, conventions, and rules. Every Claude session reads this first.
2. A global ~/CLAUDE.md. Your personal preferences that apply everywhere.
3. An AGENTS.md if you run more than one agent. The same project instructions in the format Codex, Cursor, Aider, and 20-odd other tools read. Point CLAUDE.md at it with @AGENTS.md so there is one copy.
4. Skills for your common workflows. /review, /test, /commit, whatever you do repeatedly.

These files are the difference between Claude Code as a generic tool and Claude Code as a teammate that knows how you work. The time you spend writing them pays back on every session.