How to Set Up CLAUDE.md, SKILL.md, and PITFALLS.md

Turn repeated project rules, workflows, and mistakes into reusable files so Claude Code and other AI coding agents stay consistent instead of guessing.

Quick Answer

CLAUDE.md is best for always-on project context: architecture, commands, coding standards, and the rules Claude Code should remember every session. SKILL.md is best for reusable workflows, like adding a guide, creating a tool entry, reviewing SEO content, or fixing a specific type of bug. PITFALLS.md is a useful custom companion file for repeated mistakes and warnings, such as “do not change global styles” or “do not create broken internal links.” Together they turn one-off prompts into a repeatable AI coding system, and they pair naturally with portable context and model routing.

Why These Files Matter

An AI coding tool is only as good as the context it receives. If Claude does not know your build command, it guesses. If it does not know your content format, it invents a new one. If it does not know your common mistakes, it repeats them. And if it does not know your workflow, you end up typing the same long prompt again and again.

Picture a content site owner adding new guides. Every time, they explain the frontmatter shape, the category system, the internal linking rules, the SEO style, the validation commands, and “please do not redesign the site.” That is a lot of typing for something that never changes. It belongs in reusable project instructions and skills, written down once.

The payoff is consistency. When the rules live in files the agent actually reads, you stop being the memory of the project and the agent starts behaving like it has been here before.

The Simple Mental Model

Three files, three jobs. CLAUDE.md is the project operating manual. SKILL.md is a reusable workflow for one kind of task. PITFALLS.md is the “please stop doing this” file.

Another way to see it: CLAUDE.md is what a new teammate reads on day one. SKILL.md is the checklist they follow for a repeated job. PITFALLS.md is the notebook of painful lessons the team learned the hard way. You would give all three to a new hire, and for the same reasons you give them to an AI agent.

What Is CLAUDE.md?

CLAUDE.md is a Markdown file that gives Claude Code project-level instructions. Claude Code loads it automatically when it works in your repository, so anything in it acts like always-on memory: the project overview, coding standards, commands, architecture notes, preferred patterns, validation steps, and the restrictions that matter. You can read more about the file itself in our CLAUDE.md glossary entry.

The most common mistake is treating it as a dumping ground. A CLAUDE.md that runs for hundreds of lines gets skimmed, not followed. Keep it short enough to stay useful and focused on instructions that apply almost every time the agent works in the project. Task-specific detail belongs elsewhere.

What to Put in CLAUDE.md

In plain terms, CLAUDE.md should answer the questions a capable stranger would ask before touching your code: what is this project, what is the stack, where do things live, how do I build and test it, what conventions do you follow, and what must I not break. If it is a content site, that includes writing style, frontmatter shape, SEO rules, and internal linking rules.

Here is a starter template you can adapt:

# Project Instructions

## Project overview
[What this project is and who it serves.]

## Tech stack
[Framework, language, styling, content system, deployment notes.]

## Important folders
[Where content, components, data, assets, and routes live.]

## Development commands
- Build: [command]
- Test: [command]
- Dev server: [command]
- Lint: [command]

## Coding standards
[Preferred patterns, naming, components, styling, state, architecture.]

## Content standards
[Writing style, frontmatter, SEO requirements, internal linking, formatting.]

## Validation
Before finishing:
- run the build
- check changed routes
- check internal links
- check images or assets
- summarize files changed

## Hard rules
- Do not redesign unrelated pages.
- Do not change global styles unless asked.
- Do not create broken links.
- Do not invent data.
- Do not store secrets in this file.

What Is SKILL.md?

SKILL.md is the main file of an Agent Skill, a saved workflow the agent can pull in for a specific recurring task. Where CLAUDE.md is broad project context, a skill is narrow task context.

A skill is a folder containing a SKILL.md file. That file starts with YAML frontmatter holding a name and a description, followed by Markdown instructions. According to Anthropic’s Agent Skills documentation, the description is the primary signal the agent uses to decide when to load a skill, since it pre-loads each skill’s name and description and reads the full instructions only when relevant. Optional pieces like scripts/, references/, and assets/ folders can sit beside SKILL.md for code, extra docs, and templates.

The practical rule: do not stuff every “how to add a new guide” instruction into CLAUDE.md. Make a skill for it. That keeps CLAUDE.md lean and gives the workflow room to be detailed without slowing down every other task.

What to Put in SKILL.md

A good skill is specific. It should say when to use it, what the goal is, the steps to follow, the checks that matter, the output format, and the things to avoid. A vague description is the top reason a skill never gets used, because the agent cannot tell when it applies.

Here is a reusable template:

---
name: add-project-guide
description: Use when creating or adding a new SEO guide to this project, including research, structure, frontmatter, internal links, FAQ, and build validation.
---

# Add Project Guide Skill

Use this skill when the user asks to create a new guide or article.

## Goal
Create a complete, useful, SEO-friendly guide and add it to the existing
project structure.

## Workflow
1. Inspect existing guide files.
2. Match the current frontmatter and formatting.
3. Research current facts when the topic is recent or fast-changing.
4. Write the guide in a human, practical style.
5. Add internal links only to routes that exist.
6. Run validation.
7. Report files changed and the final route.

## Quality standards
The guide should be clear, useful, current, and not robotic.

## Things to avoid
- Do not invent a new structure.
- Do not create broken links.
- Do not overuse bullet lists.
- Do not make unsupported claims.

## Final output
Report the guide file created, route, category, internal links,
build result, and files changed.

What Is PITFALLS.md?

Here is where accuracy matters. PITFALLS.md is not an official Anthropic file, and nothing loads it automatically. It is a useful custom convention: a place to record repeated mistakes, project gotchas, edge cases, and “do not do this again” notes. It only takes effect if you reference it from CLAUDE.md or a skill, or paste it into a prompt.

Its value shows up when an agent keeps making the same error, whether that is creating broken internal links, editing unrelated files, overusing bullet lists, inventing pricing, ignoring existing categories, rewriting a whole component instead of making a one-line fix, changing global styles, adding fake routes, or skipping the build.

The clean way to think about it: if SKILL.md describes what good work looks like, PITFALLS.md describes what bad work has looked like before, so it does not happen a third time.

What to Put in PITFALLS.md

Keep each pitfall concrete, and pair it with the correct behavior so the note actually redirects the agent rather than just scolding it.

# Pitfalls

Use this file to avoid repeated mistakes.

## Pitfall: Creating broken internal links
Do not link to pages that do not exist.
Correct behavior: inspect the route or content file first, then link
only to confirmed pages.

## Pitfall: Changing unrelated files
Do not edit unrelated components, styles, or data for a scoped task.
Correct behavior: make the smallest safe change that completes the task.

## Pitfall: Robotic writing
Do not write in a repetitive heading, one sentence, bullet list pattern.
Correct behavior: use natural paragraphs, and lists only when they help.

## Pitfall: Inventing current AI facts
Do not invent model names, pricing, benchmarks, or availability.
Correct behavior: verify current facts from official or trusted sources.

Recommended Folder Structure

A tidy layout keeps the always-on rules separate from the task-specific ones:

project-root/
├── CLAUDE.md
├── CLAUDE.local.md
├── AGENTS.md
├── .claude/
│   └── skills/
│       ├── add-guide/
│       │   ├── SKILL.md
│       │   └── PITFALLS.md
│       ├── add-ai-tool/
│       │   ├── SKILL.md
│       │   └── PITFALLS.md
│       └── seo-review/
│           ├── SKILL.md
│           └── PITFALLS.md

CLAUDE.md is the shared project memory that belongs in git. CLAUDE.local.md can hold private local preferences and should usually be gitignored so your personal notes do not ship to teammates. AGENTS.md helps other coding agents if you use tools that read it. Skills live in their own focused folders, and a PITFALLS.md can sit beside a skill when the mistakes are specific to that workflow, or live at the root when they apply project-wide. Before you rely on any of these being read automatically, confirm the behavior for your specific tool, since it varies.

CLAUDE.md vs SKILL.md vs PITFALLS.md

The pattern is simple: CLAUDE.md and AGENTS.md stay lean because they load often, while a skill can afford more detail because it loads only when its task comes up.

Example Setup for a Content Website

For a content site, CLAUDE.md defines the site’s purpose, content structure, writing style, SEO rules, internal linking rules, and validation commands. That is the layer every task shares.

The skills are where the repeated jobs live: an add-guide skill, an add-ai-tool skill, an add-glossary-term skill, a review-seo-content skill, a humanize-article skill, and a check-internal-links skill. Each one encodes a workflow you would otherwise re-explain. PITFALLS.md then captures the recurring content mistakes: broken links, duplicate slugs, invented tool pricing, generic AI writing, and unrelated style changes. If you want to see a skill-driven workflow in action, our guide on running Claude Code like a team of agents is a good companion.

Example Setup for a Coding Project

For a software project, CLAUDE.md carries the stack, architecture, commands, testing approach, folder structure, and coding standards. Skills handle the recurring engineering tasks: fix-bug, add-component, write-tests, review-pr, refactor-safely, and performance-audit.

PITFALLS.md earns its place fast in code. It can warn the agent not to rewrite a whole component for a small change, not to alter API contracts, not to add dependencies without approval, not to edit tests just to make them pass, and not to strip accessibility attributes. These are exactly the kinds of shortcuts an AI coding agent takes when it is optimizing for “make it pass” rather than “make it right.” For more on getting cleaner results from these tools, see how to get better results from AI coding tools.

How This Connects to Portable Context

CLAUDE.md and SKILL.md are really one instance of a bigger idea: portable context. Instead of keeping project knowledge trapped in one chat history, you store it in files. That makes your setup easier to move between Claude Code, Codex, Cursor, ChatGPT, and other tools, because the context is yours, not the app’s.

The same habit extends beyond these three files. Many people keep a project-context.md, a writing-voice.md, a content-rules.md, a coding-standards.md, and a workflow-notes.md. All of it is context engineering: deciding what the model needs to know and putting it somewhere reusable. The reward is a smaller re-teaching tax every time you switch tools or open a fresh session.

How This Connects to Model Routing

Once your instructions live in files, routing work between models gets much easier. A strong model can read CLAUDE.md and the relevant skill, then produce a plan. A cheaper or faster model can follow the SKILL.md workflow to do the execution. The strong model can come back and review the result against your success criteria and PITFALLS.md.

That is the planner, executor, reviewer pattern, and it maps directly onto model routing and model fallback. We cover the cost side of it in how to make cheaper AI models work smarter. The files are what make the handoff clean, since every model in the chain reads from the same shared context instead of your memory.

Setup Workflow: Start Small

You do not need the full system on day one. Build it in the order the work reveals.

1. Create a basic CLAUDE.md.
2. Add only the project rules you repeat often.
3. Pick one recurring task.
4. Turn that task into a SKILL.md.
5. Add a PITFALLS.md once you notice repeated mistakes.
6. Run one real task using the skill.
7. Update the files after the task finishes.
8. Keep every file short and current.

Resist the urge to design a perfect setup up front. The files get good by being corrected. Start with the rules you keep repeating, then let the project teach you what the agent gets wrong and fold each lesson back in.

Common Mistakes

The biggest one is length. A CLAUDE.md that tries to cover everything becomes background noise the agent skims past, so keep it to the always-on essentials and push detail into skills. Closely related is cramming every workflow into CLAUDE.md instead of giving each its own skill.

On the skill side, the usual failures are vague instructions and weak descriptions. If the description does not clearly say when the skill applies, the agent will not know to reach for it. Skills also go stale when you never update them after a mistake, which is the whole reason to keep PITFALLS.md close by.

The rest are smaller but real. Do not store secrets in any of these files, since they are usually committed and read by tools. Do not assume every tool reads the same files, because they genuinely differ. Do not spin up a dozen skills before you need them. And do not skip the build check or forget to notice whether the agent actually followed the instructions, because a rule nobody verifies is a rule nobody keeps. For sharper prompts inside these files, how to write better AI prompts helps.

Beginner Checklist

Before you save something into CLAUDE.md, SKILL.md, or PITFALLS.md, ask:

• Is this instruction useful often enough to save?
• Should this be always-on context or a task-specific skill?
• Is the skill description specific about when to use it?
• Did I include examples?
• Did I include what not to do?
• Did I include validation steps?
• Did I remove secrets and private data?
• Is the file short enough to stay useful?
• Did I test it on a real task?
• Did I update it after the agent made a mistake?

Key Takeaways

• CLAUDE.md is for always-on project instructions Claude Code loads every session.
• SKILL.md is for reusable task workflows, with a clear name and description.
• PITFALLS.md is a useful custom file for repeated mistakes, not an official one.
• Together these files cut re-explaining and make AI coding agents more consistent.
• Start small, test on real work, and update the files as the project teaches you.

The best AI coding setup is not one giant prompt. It is a small system of reusable context. Use CLAUDE.md for project memory, SKILL.md for repeatable workflows, and PITFALLS.md for the mistakes you do not want repeated. When those files are clear, the agent stops acting like a stranger in your codebase and starts acting like a teammate who knows the rules. For more practical AI coding guides, workflow tutorials, and tool comparisons, explore more resources across Ainanza.