Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

The .claude/ folder is Claude Code’s project-level customization area: it can hold shared settings, rules, skills, agent definitions, hooks, and output styles. It works alongside CLAUDE.md, which supplies durable project context that Claude reads automatically. The right place for an instruction depends on whether it should apply broadly, only to certain files, only when a task calls for it, or as a deterministic action.

What is the .claude folder?

In a Claude Code repository, .claude/ is where a project can keep customization files. These shape how Claude works in that repository; they are not application runtime code. A project can use only the parts it needs—there is no requirement to create every supported subdirectory.

The root CLAUDE.md file is a closely related project instruction file, but it sits beside .claude/, not inside it. Anthropic describes it as a Markdown file Claude reads automatically at the start of a session in its directory. See Anthropic’s CLAUDE.md guidance.

Where do CLAUDE.md files belong?

Use CLAUDE.md for durable context Claude should have when working in a project or part of it: build and test commands, architecture, naming conventions, constraints, and known gotchas. Anthropic recommends keeping it short and signal-dense—roughly under 200 lines—and reviewing any initial draft from /init for accuracy before adopting it. See Anthropic’s project memory guide.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
  • ~/.claude/CLAUDE.md: personal guidance that can apply across projects.
  • <repo-root>/CLAUDE.md: conventions for the repository.
  • <subdir>/CLAUDE.md: guidance for a particular module or subtree; subdirectory files are loaded on demand when Claude works in that area.

Claude combines guidance from broader and more specific scopes. Avoid putting every detail into the root file: broadly applicable context belongs there, while genuinely local instructions belong closer to the files they govern.

What belongs in each .claude location?

Location Best fit How it is used
.claude/settings.json Team-shared project settings, permissions, and hook configuration Commit it when the project should share and review the policy.
.claude/settings.local.json Personal or machine-specific project overrides Keep it uncommitted when the settings should not become team policy.
~/.claude/settings.json User-wide settings Applies at the user level; project settings take precedence over user-level settings, according to Anthropic’s settings documentation.
.claude/rules/ Reusable conventions or constraints, including path-specific guidance Markdown rules can apply broadly or use a paths frontmatter field to target matching files.
.claude/skills/ Repeatable procedures and runbooks Each skill is a folder with SKILL.md and optional resources or scripts; its full instructions load when relevant or invoked.
.claude/agents/ Focused delegated roles Agent definitions provide metadata at session start; the larger role instructions load when an agent is called.
.claude/commands/ Legacy custom slash commands The legacy command-file path remains supported.
.claude/output-styles/ Optional output-style customization Use only if the project needs a distinct output style.

Rules without path conditions behave like always-loaded instruction content. When a rule is only relevant to a portion of the codebase, path-scoping it helps avoid injecting unrelated guidance into other work. Skills instead package a procedure for selective use: Claude discovers the skill’s name and description at startup, then loads the full content when the skill is invoked or matched to a task. See Anthropic’s skills and commands documentation.

How should you choose between rules, skills, agents, and hooks?

  • Use CLAUDE.md for durable project facts and conventions Claude should routinely know.
  • Use rules for constraints that apply across tasks or only to a set of paths.
  • Use skills for procedures Claude should load when a particular task calls for them, such as a release runbook.
  • Use agents for delegated work that benefits from a focused, isolated context, such as a review or dependency audit.
  • Use hooks for actions that must happen reliably, rather than instructions the model might overlook.

These mechanisms differ in scope and authority. A Markdown instruction guides model behavior; a hook can execute a command at a lifecycle event. Anthropic staff’s customization overview identifies CLAUDE.md files, rules, skills, subagents, hooks, output styles, and system-prompt additions as distinct ways to customize Claude Code.

What do hooks do, and what are the risks?

Hooks are configured in settings and can run on events such as prompt submission, tool use, edits, or session start. Depending on the configuration, a hook can run a command, call an HTTP endpoint or MCP tool, or use a prompt or agent handler. They are useful for dependable automation—for example, formatting after edits or blocking a disallowed command—but they are not merely passive instructions.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Hooks receive JSON on standard input containing session and event data. Exit code 0 indicates success; exit code 2 blocks the action and returns the hook’s standard error as the error. The default timeout is 60 seconds, and matching hooks run in parallel. These details are version-sensitive; check Anthropic’s hooks reference for the current supported events and behavior.

Security matters: hooks execute with the user’s permissions and can run arbitrary shell commands. Review hook scripts as you would other executable code, and keep sensitive actions narrowly scoped. Storing a command under .claude/ does not make it safe.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

What might a practical repository layout look like?

repo/
├── CLAUDE.md
└── .claude/
    ├── settings.json
    ├── settings.local.json       # usually ignored by git
    ├── rules/
    │   └── api.md
    ├── skills/
    │   └── release/
    │       └── SKILL.md
    ├── agents/
    │   └── code-reviewer.md
    ├── commands/                 # legacy custom commands
    └── output-styles/

This is an example, not a required scaffold. A small project may need only a root CLAUDE.md and a settings file. Create directories only when they contain a real customization you intend to maintain.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.