Claude Code Mastery: CLAUDE.md, Skills, Subagents, and MCPs

Claude Code as a Daily Driver

The difference between a casual Claude Code user and someone who internalizes it is enormous. The casual user types prompts and accepts suggestions. The daily driver treats Claude as a programmable agent with memory, custom commands, parallel sessions, and a project setup that compounds over time.

This guide assumes you already know what claude does in a terminal. It's for the developer who wants to move from prompt-and-wait to delegate-and-verify.

Beyond the Basics: Shift Your Mental Model

Once you stop thinking of Claude Code as a chatbot and start treating it as an autonomous agent needing guardrails, your workflow shifts. The single most important principle from Boris Cherny and the Anthropic team: give Claude a way to verify its own work. Without that, you are the only feedback loop. With it, Claude iterates until things actually work. Boris says this alone gives a 2-3x quality improvement.

Key Patterns

• Explore, then plan, then code. Plan mode (Shift+Tab twice) puts Claude into read-only exploration. Read files, trace flows, understand the data model. Then get a plan. Then execute. Skip planning for small fixes; use it for anything touching more than one file.
• Use plan mode like a design document. Have one Claude write the plan, then spin up a second Claude in a fresh session to review it as a staff engineer, with no context bias.
• Reference, do not describe. Instead of "look at the auth module", type @src/auth/login.py. Instead of pasting an error, pipe it: cat error.log | claude.
• Delegate, do not pair-program. Cat Wu (Claude Code team): "The model performs best if you treat it like an engineer you're delegating to, not a pair programmer you're guiding line by line."
• Edit plans inline: Press Ctrl+G to open Claude's plan in your editor and tweak it before Claude proceeds.
• Learn from mistakes: When Claude makes a mistake, end your prompt with "Update CLAUDE.md so you do not repeat this." Boris calls Claude "eerily good at writing rules for itself" from its own failures. This habit compounds more than any other.

The .claude Directory: A Layered Configuration System

Most people open .claude/ once, see CLAUDE.md, and never look further. It is actually a layered configuration system with two scopes:

• Project scope lives in .claude/ inside your repo, committed to git so your team shares it.
• Global scope lives in ~/.claude/ and applies across every project on your machine.

File types and their purposes

File	Scope	Commit?	What it does
CLAUDE.md	Project and global	Yes	Instructions loaded every session
CLAUDE.local.md	Project only	No, gitignore it	Your private project notes
settings.json	Project and global	Yes	Permissions, hooks, env vars, model defaults
settings.local.json	Project only	No	Personal overrides, auto-gitignored
.mcp.json	Project only	Yes	Team-shared MCP servers
skills//SKILL.md	Project and global	Yes	Reusable prompts invoked with /name
commands/*.md	Project and global	Yes	Single-file slash commands
agents/*.md	Project and global	Yes	Subagent definitions
rules/*.md	Project and global	Yes	Topic-scoped instructions, optionally path-gated

A typical layout:

my-repo/
├── .claude/
│   ├── settings.json
│   ├── agents/
│   │   ├── pr-review.md
│   │   └── test-writer.md
│   ├── skills/
│   │   └── api-conventions/SKILL.md
│   └── rules/
│       ├── frontend.md        # path-gated to src/frontend/
│       └── migrations.md      # path-gated to db/migrations/
├── CLAUDE.md                  # checked in, team-shared
├── CLAUDE.local.md            # gitignored, personal
└── .mcp.json                  # team-shared MCP servers

Key details easy to miss

• CLAUDE.md files cascade. In a monorepo, both root/CLAUDE.md and root/services/billing/CLAUDE.md load when you work in the billing service.
• rules/*.md is path-gated. Guidance specific to your migrations folder belongs in .claude/rules/migrations.md with a glob.
• Skills over commands. .claude/commands/*.md and .claude/skills//SKILL.md both create slash commands, but skills support supporting files, disable-model-invocation, allowed-tools, and agent overrides. New work should go in skills/.
• Run claude project purge ~/path/to/repo --dry-run to see exactly what local state Claude holds for a project.

CLAUDE.md: The Way Boris Writes It

CLAUDE.md is loaded at the start of every session. Get it wrong and Claude repeats the same mistakes. Get it right and the same prompt produces dramatically better output.

Boris is direct about two things:

1. Keep it short. For every line, ask: "Would removing this cause Claude to make a mistake?" If not, cut it.
2. Let Claude write rules for itself. Any time Claude does something wrong, tell it: "Update CLAUDE.md so you do not repeat this."

The Real CLAUDE.md From the Claude Code Team

Boris has shared the actual CLAUDE.md the Claude Code team checks into their own repo. The whole team contributes multiple times a week:

# Development Workflow
**Always use `bun`, not `npm`.**
# 1. Make changes
# 2. Typecheck (fast)
bun run typecheck
# 3. Run tests
bun run test -- -t "test name" # Single suite
bun run test:file -- "glob" # Specific files
# 4. Lint before committing
bun run lint:file -- "file1.ts"
bun run lint
# 5. Before creating PR
bun run lint:claude && bun run test

That's the entire file. Build commands Claude cannot guess, the exact order to run things, single-test invocations, the pre-PR ritual. No style preferences. No codebase tours.

Boris also uses @claude in PR comments to have Claude commit a rule directly:

nit: use a string literal, not a ts enum
@claude add to CLAUDE.md to never use enums, always prefer literal unions

He calls this "Compounding Engineering," where every PR review becomes a CLAUDE.md improvement.

A fleshed-out template:

# Code style
- Use ES modules (import/export), not CommonJS (require)
# Workflow
- Always use `bun`, not `npm`
- Run `bun run typecheck` before claiming done
- Never push to main directly. Always open a PR.
# Architecture
- All API routes go through src/api/middleware/auth.ts
- New database queries go in src/db/queries/. No inline raw SQL.
# Gotchas
- `User` and `UserRecord` are distinct types. UserRecord is the DB row, User is the runtime object.
- `formatCurrency` assumes USD. For international use `formatCurrencyByLocale`.

The "Gotchas" section is the magic. Every entry is a mistake Claude made, captured the moment it happened.

What does not belong in CLAUDE.md: standard language conventions, file-by-file codebase descriptions, long tutorials, API docs, anything that changes frequently.

Pro tip: Words like IMPORTANT or YOU MUST improve adherence. Use them sparingly so they carry weight. You can import other files using @path syntax to keep CLAUDE.md short while pulling in details:

See @README.md for project overview and @package.json for scripts.
@~/.claude/my-preferences.md

Popular CLAUDE.md Files Worth Studying

• mattpocock/skills CLAUDE.md: conventions for how skills should be written and tested
• anthropics/claude-code-action: Anthropic's own repo, treated the same as internal tools
• awesome-claude-code: links to dozens of public CLAUDE.md files across language ecosystems
• claudelog.com: community-curated examples organized by stack

CLAUDE.local.md as a Daily Driver

CLAUDE.local.md lives alongside CLAUDE.md, gets loaded the same way, but never leaves your machine. Add it to .gitignore.

The way I use it: after every PR I open, reviewers leave comments. Instead of trying to remember them, I dump them into CLAUDE.local.md the moment I see them. Over time it becomes a personalized rule file for exactly the feedback I get most often.

# Personal review notes (private)
# From PR feedback
- New SQS consumers need a DLQ and alarms in the same PR
- Use `Optional` over null returns
- Tests for new endpoints must include the auth-failure case
- Prefer named tuples over plain dicts for return types with 3+ fields
# My own quirks to correct
- Stop using `console.log`; use the project logger instead
- Always update the OpenAPI spec when adding endpoints

Loaded every session, Claude already knows to include auth-failure tests and update the OpenAPI spec without me mentioning it. Nitpick comments on my PRs dropped noticeably within a couple of weeks.

Pro tip: Keep two sections clearly separated: project-specific feedback and personal habits to correct. Prune after a few weeks — things that have become muscle memory can go.

Skills, In Depth

Skills let Claude Code go from "an agent that can do anything" to "an agent that does specific things really well for your project." They are the unit of reusable expertise.

What Skills Actually Are

A skill is a folder under .claude/skills// (project) or ~/.claude/skills// (global) containing a SKILL.md with frontmatter and instructions. The folder name becomes the slash command.

The simplest possible skill:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes in two or three bullet points, then list any risks: missing error handling, hardcoded values, tests that need updating.

Save to ~/.claude/skills/summarize-changes/SKILL.md and /summarize-changes is available in every session.

Three things that make Skills powerful:

1. Progressive disclosure. Claude loads only frontmatter descriptions at session start (~100 tokens each). Full SKILL.md and helper files load only when the skill is actually needed.
2. Skills are folders, not files. Bundle templates, reference docs, scripts, config. SKILL.md is just the entry point.
3. Inline shell. Lines starting with ! run a command and inject the output at invocation time.

Frontmatter supports useful extras:

---
name: my-skill
description: When to use this skill
disable-model-invocation: true # only runs when user explicitly types /my-skill
allowed-tools: Read, Grep, Bash
agent: read-only
---

Pro tip: Use disable-model-invocation: true for skills with side effects. You want /ship to deploy only when explicitly typed, not when Claude decides it is relevant.

Writing a Real Skill: Go API Conventions

A complete skill for a Go service team, covering conventions, gotchas, and scaffolding for a new HTTP handler:

.claude/skills/go-handler/
├── SKILL.md
├── templates/
│   └── handler.go.tmpl
└── examples/
    └── healthz.go

---
description: Scaffolds a new HTTP handler in our Go service following team conventions for routing, validation, error handling, and tests. Use when the user asks to add a new endpoint, a new handler, or extend an existing route group.
---
# Go HTTP Handler Skill
## Stack
- Go 1.22 with net/http
- chi router for routing
- go-playground/validator for validation
- testify for tests
## Conventions
...

Next Steps

Start today: create a CLAUDE.md in your project with build commands and a gotchas section. Next time Claude makes a mistake, tell it to update the file. Within a week, you'll have a curated list of project-specific rules. Then add a skill for your most common task. The compounding effect is real.