Claude Code Has 5 Ways to Customize It — Here's When to Use Each
If you've used Claude Code for more than a week, you've probably noticed it has a lot of knobs. There's CLAUDE.md. There's the ~/.claude/skills/ directory. There's also ~/.claude/commands/ (which feels like skills but isn't quite the same). There's settings.json. There's the /memory command. There are hooks.
Most users learn one or two of these, miss the rest, and end up writing prompts they could have automated months ago.
This is the full map. Five customization layers, what each one is best at, and the decision matrix at the end for "I want X — which knob do I turn?"
The five layers at a glance
| Layer |
Lives at |
Authored by |
Best for |
| CLAUDE.md |
repo root + parents |
Human |
Project-wide context, conventions, file paths |
| Skills / Slash commands |
~/.claude/skills/ + ~/.claude/commands/ |
Human (or auto-generated) |
Multi-step workflows you invoke by name |
| Hooks |
~/.claude/settings.json |
Human |
Automation triggered by tool-use events |
| Memory |
~/.claude/projects/<path>/memory/ |
Model (with your prompting) |
Long-running notes Claude maintains across sessions |
| Settings / permissions |
~/.claude/settings.json + .claude/settings.local.json |
Human |
Tool allowlists, env vars, MCP servers |
Three are project-scoped, two are user-scoped. Three are imperative ("do X"), one is contextual ("here's how things work here"), one is event-driven ("when X happens, do Y").
1. CLAUDE.md — project context
The file Claude Code looks for at the root of your repo (and at every parent directory, walking up to $HOME). Everything inside it gets auto-injected at the top of every session run in that project.
~/code/myrepo/CLAUDE.md ← project-specific
~/code/CLAUDE.md ← shared across all repos under ~/code/
~/CLAUDE.md ← user-wide defaults
The hierarchy merges from top to bottom — more-specific files override more-general ones.
When to use it
- Project conventions — "we use Tailwind, never CSS modules", "the API base URL is X", "all tests must use Vitest"
- File path shortcuts — "auth lives in
app/api/src/handlers/auth.ts", "schemas are in app/db/schema.ts"
- Domain vocabulary — "by 'event' we mean an OTLP-formatted span, not a DOM event"
- Hard constraints — "never write to the prod database from a Cloudflare Worker"
When NOT to use it
- Reusable workflows — those belong in skills (see next)
- Personal preferences that apply across all your repos — put those in
~/CLAUDE.md, not the project's
- Long lists Claude needs to consult sometimes —
CLAUDE.md is read every session, so size matters; for larger references, link out to docs files instead
Common mistakes
- Too long. A 2,000-line
CLAUDE.md burns through context budget on every session. Aim for under 200 lines; link to docs files for detail.
- No structure. Use clear
## Sections. Claude reads them; you'll re-read them; future-you will thank you.
- Stale.
CLAUDE.md rots like any docs file. Re-read it once a quarter.
2. Skills and slash commands — invokable workflows
Two formats, both for "things I want to run by typing /<name>":
- Slash commands (older):
~/.claude/commands/<name>.md — a single markdown file with frontmatter + instructions
- Skills (newer):
~/.claude/skills/<name>/SKILL.md — same idea but each skill gets a directory, so it can include supporting files (templates, scripts, examples) alongside SKILL.md
You can also drop these in .claude/commands/ or .claude/skills/ at the project root for repo-scoped versions. Project-scoped takes precedence.
When to use a skill
- You've prompted the same thing more than three times. "Set up a new feature branch, add a failing test, implement the change, run lint, then summarize." That's a skill.
- The workflow has multiple steps Claude needs to chain. A skill can structure these into a checklist Claude follows.
- You want to share it with teammates. Drop it in
.claude/skills/ and commit it.
Skills vs slash commands — which format
Skills can ship with templates and scripts in their directory; slash commands can't. Skills also have richer frontmatter (more metadata for Claude's planner). For new work, default to Skills. Don't bother migrating old slash commands unless you're already editing them.
When NOT to write a skill
- It's just a single short prompt. Skills are overkill for one-liners; just type the prompt.
- It's project context, not a workflow. Use
CLAUDE.md instead.
- You haven't actually used the pattern yet. Don't author skills for hypothetical workflows.
The hardest part: knowing which patterns deserve a skill
Most teams don't write skills not because skills are hard to author — they're easy — but because nobody notices "I've now done variations of this thing 14 times." Your transcripts have the evidence; nobody's looking at them.
(That's the gap Prompt Conduit closes: it reads ~/.claude/projects/ and writes skill files for the patterns that show up across multiple sessions. Local-only mode requires no account. More on this at the end.)
3. Hooks — automation on tool-use events
Hooks live in ~/.claude/settings.json (user-wide) or .claude/settings.json (per-project). They fire when Claude Code does specific things:
- PreToolUse — before any tool call. Useful for permission gates or input validation.
- PostToolUse — after a tool call completes. Useful for logging, formatting, or kicking off external work.
- Stop — when Claude finishes its turn. Useful for end-of-session notifications, summaries, or sync hooks (this is what
promptconduit install claude-code registers).
- SubagentStop — when a sub-agent (
Task tool) completes.
Hook handlers are shell commands. Claude Code pipes JSON about the event to stdin; your handler does whatever, writes JSON to stdout if it wants to influence the next step.
When to use a hook
- You want X to happen automatically. Not "when I type a command" — when Claude does something. E.g. "after every
Edit, run pnpm lint --fix on the file."
- You want to capture/observe Claude's behavior. This is how telemetry tools like PromptConduit work.
- You want to gate something. PreToolUse can reject a tool call by returning a specific JSON shape, e.g. "block any
Bash command containing rm -rf."
When NOT to write a hook
- You want it to fire when YOU do something. Hooks fire on Claude's events, not yours. For your-action automation, use a skill.
- The action is expensive. Hooks run synchronously and add latency to every event. Offload heavy work to background processes.
4. Memory — model-managed persistent context
Different from CLAUDE.md. CLAUDE.md is you telling Claude facts. Memory is Claude taking notes that persist across sessions, prompted by you (e.g. via the /memory command) or by your CLAUDE.md instructing it to.
Memory entries live as files under ~/.claude/projects/<encoded-path>/memory/. Each is a small markdown file with a name (slug), description, and content. The full set is automatically loaded back into context in future sessions for that project.
When to use memory
- You learn something Claude should remember. "Daisy's local timezone is Pacific" or "this codebase uses pnpm even though there's a
package-lock.json left over from years ago."
- You're debugging a tricky issue across multiple sessions. Each session, the model can note what it tried.
- Your project has facts that change too often for
CLAUDE.md but matter session-to-session.
When NOT to use memory
- The fact is true forever and unambiguous. That's
CLAUDE.md territory.
- You're trying to give the model a workflow. Memory is for facts, not procedures.
CLAUDE.md vs memory in one line
CLAUDE.md is your project's documentation. Memory is your collaboration history with the model. Both contribute context; you should have both.
5. Settings and permissions — the guardrails
~/.claude/settings.json (user-wide) and .claude/settings.local.json (per-project, gitignored) hold:
- Permissions — which tools Claude can use without prompting, which require confirmation, which are blocked.
allow, ask, deny lists.
- Environment variables — values injected into Claude Code's environment, e.g.
MAX_THINKING_TOKENS, ANTHROPIC_LOG.
- MCP servers — Model Context Protocol server configurations (databases, APIs, custom tool servers).
- Hooks (covered above).
When to use settings
- Allowlist commands you trust.
Bash(pnpm test) always runs; Bash(rm -rf) always prompts (or denies).
- Reduce permission fatigue. If you find yourself hitting "yes" on the same command 50× a day, allowlist it.
- Wire up MCP servers. Connect Claude Code to your databases, internal APIs, or design tools.
When NOT to put it in settings
- Anything secret.
.claude/settings.local.json is gitignored but settings.json (user-wide) and .claude/settings.json (project, committed) are not.
- Project context. Settings is for permissions and connections, not for telling Claude how the codebase works.
Decision matrix
| What you want |
Use this |
| Claude to know how the codebase is laid out |
CLAUDE.md |
To run the same multi-step thing by typing /<name> |
Skill |
Something to happen automatically after every Edit |
Hook (PostToolUse) |
| Claude to remember a fact about you between sessions |
Memory (/memory) |
To never get prompted for pnpm test again |
Settings (permissions allowlist) |
| To connect Claude to your internal database |
Settings (MCP server) |
| Claude to know your team's review checklist |
Skill (/review) |
| Claude to know what "event" means in your domain |
CLAUDE.md |
If you find yourself thinking "I keep telling Claude the same thing" → it's either CLAUDE.md (if it's a fact) or a skill (if it's a procedure).
The thing nobody mentions: skills go stale fast
A skill is a snapshot of how you solved a class of problem at one moment in time. Three things age them out:
- Your tools change. You migrated from npm to pnpm; the skill still says
npm test.
- The codebase changes. The skill references a file path that got refactored last month.
- Your taste changes. What looked like a good
/ship workflow in March feels clunky by August.
The cure isn't to write fewer skills. It's to regenerate them from your recent transcripts every couple of months. The patterns Claude has been helping you with recently are different from the patterns you had six months ago, and the skill library should reflect that.
Prompt Conduit does this in one command, fully local:
brew install promptconduit/tap/promptconduit
promptconduit skills generate --local
It reads ~/.claude/projects/ (your transcripts), detects the workflows you've used multiple times recently, and writes them as Claude Code Skills in ~/.claude/skills/. Add --dry-run to preview. Add --since=30d to only consider the last 30 days. Full docs at /docs/local-skills.
FAQ
Where is CLAUDE.md supposed to go?
At the root of your repo. Claude Code also reads parent directories, all the way up to your home folder, so you can stack a user-wide ~/CLAUDE.md underneath a project-specific one.
What's the difference between a slash command and a skill?
Slash commands are the older single-file format (~/.claude/commands/<name>.md); Skills are the newer directory format (~/.claude/skills/<name>/SKILL.md) and can carry supporting files. Both are invoked the same way (/<name>). For new work, default to Skills.
Can I use both CLAUDE.md and memory?
Yes, and you should. CLAUDE.md is for facts you know in advance. Memory is for facts the model learns or that you tell it ad-hoc during sessions.
Are hooks the same as PostToolUse in settings.json?
PostToolUse is one type of hook. Hooks are configured under the hooks key in settings.json and include PreToolUse, PostToolUse, Stop, and SubagentStop.
Do hooks slow Claude Code down?
Yes — they run synchronously between Claude's actions. Light hooks (logging, file appends) are negligible. Heavy ones (running tests, calling APIs) add measurable latency. For heavy work, fire-and-forget to a background process.
Where does Claude Code store memory entries?
Under ~/.claude/projects/<encoded-project-path>/memory/. Each memory entry is its own file. The structure mirrors how transcripts are stored (see the transcripts post for the path encoding scheme).
Can I share skills with my team?
Yes — drop them in .claude/skills/ at the project root and commit. Anyone who clones the repo gets them automatically when running Claude Code in that directory.
Further reading