Claude Code Templates: CLAUDE.md, Subagents, Skills, Hooks, and MCP

When to use it: a personal project or a small repo. Start here, then add a line each time you correct Claude on the same thing twice.

CLAUDE.md is guidance Claude reads every session, not enforced configuration. Anthropic's advice is to keep it to what Claude can't work out from the code: the exact commands to check work, places where the code is misleading, and decisions that live outside the repo. Leave out your folder layout and generic advice like "write clean code". /init generates a first draft from your codebase if you'd rather edit than write.

When to use it: a shared repository where several people (and Claude) need the same ground rules. Commit it as ./CLAUDE.md or ./.claude/CLAUDE.md.

The docs recommend staying under 200 lines per file, and this one is about 35. A few notes on what's in it:

• @docs/api-conventions.md imports another file. Imports keep things organized but still load every session, so they don't save context.
• A rule that only matters in one folder belongs in .claude/rules/<topic>.md with paths: frontmatter, so it loads only when Claude touches matching files.
• A multi-step procedure, like writing a migration, belongs in a skill (template below), not here.
• Your personal preferences go in CLAUDE.local.md, added to .gitignore.
• Run /context all in a session to confirm the file loaded.

When to use it: a task that produces a lot of output you don't want in your main conversation, like running tests or searching a large codebase. The subagent works in its own context window and hands back a summary.

Save it in .claude/agents/ for the project or ~/.claude/agents/ for all your projects. Only name and description are required. Claude decides when to delegate based on the description, and the docs suggest adding "use proactively" if you want it used without being asked. You can also name it in your prompt or @-mention it.

• tools limits what it can do. This one has no Edit or Write, so it can't change files. Omit the field to inherit all tools.
• model takes sonnet, opus, haiku, fable, a full model ID, or inherit. A cheaper model suits a narrow job like this.
• Other documented fields include disallowedTools, permissionMode, maxTurns, skills, memory, effort, and isolation: worktree. Field names are camelCase and must match exactly: Claude Code silently ignores a field it doesn't recognize.

When to use it: a procedure or a piece of team knowledge that only matters for some tasks. Until it's needed, only the description sits in context, so a skill costs far less than the same text in CLAUDE.md.

A skill is a folder with a SKILL.md file: .claude/skills/<name>/SKILL.md for the project, ~/.claude/skills/<name>/SKILL.md for you. Claude loads it when a request matches the description, and you can run it yourself as /db-migrations. All fields are optional, but write a description with the words people actually use, because that's what Claude matches against.

• allowed-tools pre-approves tools for the turn the skill runs. It doesn't block other tools.
• Supporting files like reference.md sit next to SKILL.md and load only when Claude follows the link. The docs suggest keeping SKILL.md under 500 lines.
• Add disable-model-invocation: true for anything with side effects, like a deploy, so only you can start it. Add user-invocable: false for background knowledge only Claude should load.
• Skill field names are lowercase with hyphens (allowed-tools, not allowedTools). The cheat sheet has a manual-only release skill as a second example.

When to use it: a prompt you type over and over and always want to start yourself, like committing.

Custom commands were merged into skills. A file at .claude/commands/commit.md still works and creates /commit, and it accepts the same frontmatter as a skill except name and paths. The docs recommend a skill folder (.claude/skills/commit/SKILL.md) for new work because it can hold supporting files, but the content is identical either way. If both exist with the same name, the skill wins.

• disable-model-invocation: true means Claude can't run it on its own.
• argument-hint shows in autocomplete. $ARGUMENTS is replaced with whatever you type after /commit. $0, $1 and so on pick out single arguments.
• A line starting with ! followed by a command in backticks runs that command before Claude sees the prompt and inserts its output, so Claude starts with the real diff. If one of these commands fails, the whole command is cancelled.

When to use it: you want routine commands to run without a prompt and some things blocked outright, the same way for everyone on the team.

Save it as .claude/settings.json and commit it. For rules that are just yours, use .claude/settings.local.json (choosing "Yes, and don't ask again" in a prompt saves there) or ~/.claude/settings.json for all projects. Settings files are strict JSON, so no comments or trailing commas.

• Rules are checked in the order deny, then ask, then allow, and the first match wins. An allow rule can't carve an exception out of a deny rule.
• Bash(npm test *) matches npm test and anything after it. Put the * after the subcommand, not before it.
• deny rules hold in every permission mode, including auto and bypassPermissions. A Read deny also blocks cat .env, but not a script that opens the file, so turn on the sandbox (/sandbox) when it really matters.
• Read-only commands like ls, grep, and git diff already run without a prompt, so they don't need allow rules.
• A teammate's Claude Code applies this file's allow rules only after they accept the folder's trust dialog. deny and ask rules apply right away.
• defaultMode (for example "acceptEdits" or "plan") sets the starting permission mode. auto and bypassPermissions don't take effect from project or local settings, so set those in ~/.claude/settings.json.

The $schema line gives you autocomplete and validation in editors that support JSON schema.

When to use it: a rule with zero exceptions. CLAUDE.md works most of the time. A hook is run by Claude Code itself, so it fires every time.

This template sets up two hooks. Put the hooks block in the same .claude/settings.json as your permissions, as a sibling of permissions.

• Stop runs when Claude tries to finish its turn. If the typecheck fails, exit 2 blocks the stop and the compiler errors (redirected to stderr) go back to Claude, which keeps working until tsc passes. If the hook blocks eight stops in a row with no tool call in between, Claude Code lets the turn end anyway.
• PreToolUse with the matcher Edit|Write runs before every file edit and calls the script in the next section. Exit code 2 blocks the edit, and the script's message tells Claude why.

Check what's registered with /hooks. A few other examples worth knowing: a PostToolUse hook that runs your formatter after every edit (in the cheat sheet), a Notification hook in ~/.claude/settings.json that pings your desktop when Claude needs input, and a SessionStart hook with the matcher compact that re-adds key context after compaction.

When to use it: files Claude should never edit directly: secrets, lockfiles, generated migrations. This is adapted from the docs' protect-files example.

The hook receives the tool call as JSON on stdin, so the script reads tool_input.file_path with jq (install it if you don't have it). Make the script executable with chmod +x .claude/hooks/protect-files.sh, then ask Claude to add a comment to .env to see it blocked.

A permission deny rule like Edit(./db/migrations/**) can do the same job with no script. The script is worth it when you want a custom message back to Claude or logic that a rule can't express.

When to use it: your team should share the same external tools. .mcp.json at the project root is the project-scope MCP file, meant to be committed. Servers that are only for you go in ~/.claude.json, which claude mcp add writes to by default.

• An http server needs a url. A stdio server needs a command and args, and can take an env object.
• ${VAR} and ${VAR:-default} expand from each person's environment, so tokens stay out of git. Use a variable name of your own: Claude Code deliberately reads some credential variables, such as ANTHROPIC_API_KEY and NPM_TOKEN, as empty in a remote server's url and headers.
• The first time an interactive session sees a server from .mcp.json, Claude Code asks you to approve it, so a cloned repo can't start processes on your machine without your consent.
• Each connected server adds tool definitions to context. Turn off the ones you aren't using with /mcp.

The Playwright server gives Claude a browser and needs no account. The GitHub server takes a fine-grained personal access token. To build a server of your own, see how to build an MCP server.

Most of these files fail quietly. A misspelled frontmatter field is ignored without an error, and a YAML mistake in a skill loads the body with no settings. Check each one after you add it:

• CLAUDE.md and rules: /context all lists them under Memory files.
• Settings: /status shows which settings files loaded. /permissions lists every rule and the file it came from.
• Hooks: /hooks lists them grouped by event.
• Skills and commands: /skills lists them, or type / and look for the name.
• Subagents: type @ and look for the name, or ask "what subagents are available?".
• MCP servers: /mcp in a session, or claude mcp list from your shell.
• Anything else: run claude --debug and read the debug log, which shows YAML parse errors and names subagent fields Claude Code doesn't recognize. /doctor prompt-audit reviews your instruction files for outdated or conflicting content.

• Need the commands and shortcuts that go with these files? The Claude Code cheat sheet covers them, plus a manual-only release skill and a formatter hook.
• Want something to build with your new setup? 10 Claude Code projects has starter prompts, including one where Claude writes a skill and a subagent for you.
• New to Claude Code? Start with the Claude Code tutorial.