iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Use CLAUDE.md for concise project context Claude needs repeatedly, a skill for a reusable procedure, a subagent for a specialized worker, and settings or hooks for configuration that must be applied technically. Keeping those jobs separate avoids bloated always-on instructions and makes it clearer what is shared, when guidance loads, and what Claude can do.
Choose the right home for each kind of guidance
| Need | Put it in | Why |
|---|---|---|
| Shared project facts and recurring instructions needed across sessions | CLAUDE.md or .claude/CLAUDE.md |
Project guidance provides persistent context and can be shared through version control. See Anthropic’s memory guide. |
| Your preferences across projects | ~/.claude/CLAUDE.md |
User-scope instructions apply across your projects. See the memory guide. |
| A repeatable checklist, workflow, or task-specific reference | A skill directory containing SKILL.md and optional support files |
Skill instructions are used when the skill is relevant or invoked, rather than being procedural detail in every session. See Anthropic’s skills guide. |
| A recurring worker with a defined specialty and task boundary | A custom subagent Markdown file | Its description supports delegation decisions; its configuration defines behavior such as tool access. See Anthropic’s subagent guide. |
| A behavior that must run at a particular lifecycle point | A hook | Instructions provide context; they do not guarantee enforcement. See the memory guide and settings guide. |
| Team-wide technical settings such as permissions and hooks | .claude/settings.json |
Shared project settings can be committed for collaborators. See Anthropic’s settings guide. |
| Personal settings for one project | .claude/settings.local.json |
Keep local overrides out of shared project configuration; a manually created local file should be added to .gitignore. See the settings guide. |
What belongs in CLAUDE.md?
Keep CLAUDE.md focused on stable facts and recurring directions that are useful in ordinary work on the project. Good candidates include build and test commands, project conventions, architecture decisions Claude cannot readily infer, naming rules, and recurring workflow expectations.
- Add an instruction when the same correction has recurred, a reviewer finds context Claude should have known, or a teammate would need the information.
- Prefer concrete, verifiable directions over broad goals.
- Avoid duplicating repository facts Claude can easily discover unless they are unusually important or hard to find.
- Move long procedures and guidance that applies only to one area into a skill or path-scoped rule.
This is a context file, not a technical control. If something must happen at a fixed lifecycle point regardless of Claude’s choice, configure a hook rather than relying on an instruction sentence. Anthropic explains the distinction in its memory guide.
A practical outline
# Project instructions
## Build and test
- ...
## Conventions
- ...
## Architecture decisions Claude cannot infer
- ...
## Workflow expectations
- ...This outline is a useful starting point, not an Anthropic-mandated template.
#1 Best Overall
When should a procedure become a skill?
Use a skill for a repeatable process, checklist, or task-specific capability that should be available when it is relevant or invoked, but does not need to occupy every session’s persistent project context. A skill centers on SKILL.md; the skill directory can also contain supporting reference files. Anthropic documents the current format and behavior in Extend Claude with skills.
Skills can be invoked by slash name and may also be selected automatically when relevant. Custom commands have been merged into skills, although existing files in .claude/commands/ continue to work.
Example directory
.claude/skills/release-checklist/
├── SKILL.md
└── references/
└── release-policy.mdDescribe the purpose and procedure in SKILL.md, and add supporting material when it helps carry out the workflow. Make the skill name and description accurately signal when it applies. Consult the live Skills documentation for supported frontmatter fields and invocation controls before relying on a detailed configuration template.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
When should you define a subagent?
Create a custom subagent for a recurring specialized worker with a clear task boundary. Its Markdown definition uses YAML frontmatter; its description helps Claude decide when delegation is suitable, while the focused prompt and tool list should match the assignment. Keep the description concise because it is used in delegation decisions and consumes context. See Anthropic’s current subagent documentation for supported configuration.
Illustrative definition
---
name: code-reviewer
description: Reviews changed code for correctness and project conventions. Use after implementation when an independent review is useful.
tools: Read, Grep, Glob
model: sonnet
---
Review the requested scope. Report specific findings with file and line references.This is an illustrative adaptation of the official code-improver example, not a tested configuration or a recommendation of a particular model. Choose tools, permissions, model, and other fields according to the task and current product support.
How do project, user, and organization scopes fit together?
Choose scope based on who should receive or maintain the material. Project instructions belong with the repository when teammates need them; user instructions are for your own work across projects; managed instructions are for organization-wide policy. Project rules can divide guidance by subject or path, and nested files may be loaded on demand as Claude works in relevant directories. The exact behavior varies by file type, scope, and current product configuration, so do not assume every file under .claude/ loads at startup or that all layers follow one universal override rule.
Project subagents belong in .claude/agents/; user-level subagents in ~/.claude/agents/ are available across projects. The subagent guide also describes managed, session, and plugin scopes, as well as priority behavior for duplicate names. Settings have their own scope system. Check the current memory guide, subagent guide, and settings guide for the particular case.
Example repository layout
repo/
├── CLAUDE.md
├── .claude/
│ ├── settings.json
│ ├── rules/
│ │ └── frontend.md
│ ├── skills/
│ │ └── release-checklist/
│ │ ├── SKILL.md
│ │ └── references/
│ └── agents/
│ └── code-reviewer.md
└── src/
└── ...This is a possible organization, not a required tree. Add only the files the project needs, and verify how the installed Claude Code version loads them.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Keep configuration out of instruction prose
Use settings for technical configuration instead of attempting to enforce it with CLAUDE.md wording. Anthropic describes .claude/settings.json as the shareable project settings file for items including permissions, hooks, plugins, and required environment variables. .claude/settings.local.json is for personal project overrides; ~/.claude/settings.json provides user-wide settings, while managed settings serve organization policy. See the settings guide for current details.
Check what Claude actually loads
Loading behavior is version-sensitive and is not equivalent to “everything under .claude/ loads at startup.” Anthropic’s current memory guide says ancestor CLAUDE.md and CLAUDE.local.md files load at startup, while nested files may load on demand when Claude works in those directories. Rules can be path-scoped.
The guide also documents AGENTS.md support and settings that determine whether Claude reads AGENTS.md, CLAUDE.md, or both. If a repository already uses AGENTS.md, check the current version requirements and project-instructions setting before adding another instruction file: a CLAUDE.md in the relevant path can affect which files are read.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →- Run
/contextto inspect the context currently loaded. - Run
/memoryto review memory files. - Check the current memory documentation for loading behavior and conflicts across instruction files.
These checks help distinguish a misplaced instruction from one that is present but not being read.
Quick Recap
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.
