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, AGENTS.md for agent personas, 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. But with one, it follows your specific patterns instead of inventing its own. The difference is especially noticeable 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 — agent personas

AGENTS.md defines specialized agent configurations for multi-agent workflows. Each entry describes a role with specific instructions, personality traits, and behavioral parameters. This is especially relevant when running parallel agents that each need to focus on different aspects of your project.

How AGENTS.md works

An AGENTS.md file defines one or more agent personas:

# Frontend Agent

## Instructions
You are a frontend specialist. Focus exclusively on files in src/components, src/pages, and src/styles. Never modify backend code, API routes, or database schemas.

## Conventions
- Use React functional components with hooks
- Style with Tailwind utility classes, no custom CSS
- All components must have TypeScript props interfaces

---

# Backend Agent

## Instructions
You are a backend specialist. Work only in src/api, src/services, and src/db. Never modify frontend components or styles.

## Conventions
- All endpoints return the standard response envelope
- Use Prisma for database access, no raw SQL
- Add request validation with Zod schemas

When you spin up a Claude Code session with a specific agent persona, it inherits those instructions on top of your CLAUDE.md. The CLAUDE.md defines project-wide rules; the agent persona adds role-specific focus.

When to use AGENTS.md

AGENTS.md is most valuable when you’re running multiple agents simultaneously. Without personas, two agents might both try to edit the same files or make conflicting architectural decisions. With personas, each agent stays in its lane.

Crystl’s Quest feature uses agent personas to coordinate parallel development. You assemble a party of agents — each with a defined role — and they work together on a shared goal without stepping on each other’s work.

Even for single-agent work, AGENTS.md is useful when you frequently switch between different types of tasks. Instead of re-explaining “you’re doing code review right now, be critical and thorough” every time, you define a Code Reviewer persona and activate it when needed.

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:

Type the same detailed prompt every time you want a code review, test run, or deployment check
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’s tedious — especially when you’re starting new projects frequently. 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. Instead of writing AGENTS.md entries from scratch, you pick heroes that match the roles you need.

Prompts & commands

Prompts are one-click prompts you can inject into any Claude session. They’re lighter than skills — useful 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:

CLAUDE.md in your project root — Your project’s stack, conventions, and rules. Every Claude session reads this first.
A global ~/CLAUDE.md — Your personal preferences that apply everywhere.
Skills for your common workflows — /review, /test, /commit, whatever you do repeatedly.
Agent personas when running parallel sessions — Defined roles that prevent conflicts and keep each agent focused.

The configuration 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.