Mastering Claude Code Customization: CLAUDE.md, Rules, Skills, Hooks & Subagents

Claude Code provides multiple built-in mechanisms to help manage projects: CLAUDE.md, Rules, Skills, Hooks, Subagents, Output Styles, and append system prompt. Although they all appear to be "rules for Claude," they serve different purposes. This article clarifies what each mechanism controls and when to use it.

Quick Overview

CLAUDE.md – Project specification: project background, directory structure, build commands, team conventions.

Rules – Local rules: conventions that specific files, paths, or code types must follow.

Skills – Reusable workflows: code review, release process, security audit, documentation generation.

Subagents – Independent assistants: deep search, log analysis, dependency audit, parallel tasks.

Hooks – Automatic triggers: format on save, block dangerous commands, notify on completion.

Output Styles – Overall response style: make Claude more proactive, explanatory, or change expression style.

append system prompt – Temporary additions: one-time format, tone, or domain context for a single session.

In short: CLAUDE.md makes Claude understand the project; Rules constrain local behavior; Skills package repeatable processes; Subagents handle independent tasks; Hooks automate actions; Output Styles and append system prompt control overall expression and temporary supplements.

01 | CLAUDE.md: Helping Claude Understand Project Context

CLAUDE.md

is the most common configuration file in Claude Code. Think of it as a project specification. It should tell Claude what the project does, how the directory is organized, common commands, basic code style conventions, and team habits.

For example:

# Project Description

- This is a Next.js project
- Uses pnpm
- Local dev command: pnpm dev
- Build command: pnpm build
- Test command: pnpm test
- Main business code in src/
- Check mobile styles after page changes

This information is useful in almost every session, so placing it in CLAUDE.md is reasonable.

However, CLAUDE.md is easily abused. People stuff everything into it: release processes, code review checklists, special rules for subdirectories, personal writing habits, temporary reminders, dangerous command blocklists. Short-term it seems convenient; long-term it becomes a junk drawer.

The root CLAUDE.md loads at session start and stays in context. Every line occupies context regardless of whether the current task needs it. Therefore, the root CLAUDE.md should only contain information the entire project needs.

If a rule only applies to a subdirectory, place a CLAUDE.md in that subdirectory (e.g., app/api/CLAUDE.md). It loads only when Claude reads files in that directory, saving context and avoiding irrelevant interference.

02 | Rules: Adding Rules for Specific Files or Paths

Rules resemble CLAUDE.md but are better suited for specific constraints, especially path- or file-type-related constraints.

For instance, if you have an API directory where all endpoints must validate input, you can write a rule scoped to that path:

---
paths:
  - "src/api/**"
  - "**/*.handler.ts"
---

All API handlers must validate input before processing requests.

This rule should not appear when editing homepage copy, writing README, or adjusting styles. It only appears when handling API files. That is the value of path-scoped rules: they appear when needed, stay silent otherwise.

Suitable content for Rules includes:

API handlers must validate input

Database migrations can only append, not modify historical files

Certain test files must use specified helpers

Components in a directory must follow a specific naming convention

Simply put, CLAUDE.md is like a general project description; Rules are like local traffic regulations. If a rule isn't needed project-wide but only for certain files or paths, prefer Rules.

03 | Skills: Packaging Repeatable Workflows

Skills are reusable operation workflows. For example, code review. You could tell Claude each time: "Check diff, find potential bugs, check test coverage, output issues by severity, don't edit files directly." But if you do code reviews many times a week, you shouldn't repeat that manually.

Better: create a code-review Skill. Then invoking the Skill makes Claude follow the fixed process.

Skills do not load full content into context at session start; only name and description load. The full SKILL.md enters context only when invoked.

Good candidates for Skills share three traits:

They recur repeatedly.

They have relatively stable steps.

They require Claude to deliver against the same standard each time.

Examples:

Code review process

Release checklist

Security audit process

User interview summary process

Data analysis report process

Think of a Skill as packaging "how to do this kind of thing" into a reusable capability.

04 | Subagents: Independent Assistants for Branch Tasks

Subagents (sub-agents) are independent assistants. The difference from Skills: a Skill is a process; a Subagent is the executor of a branch task.

Example: You ask Claude Code to fix a complex bug. The main task: read code, locate issue, modify implementation, run tests. But intermediate steps may include:

Search related historical issues

Analyze a large log segment

Check dependency upgrade records

Compare implementation differences across modules

These tasks generate much intermediate information useful for diagnosis but not all worth keeping in the main session. Delegate them to a Subagent.

A Subagent runs in its own context and returns only the final summary to the main session. That isolation is its key value: the main session avoids being cluttered with search processes, log fragments, and intermediate reasoning, receiving only a curated result.

Suitable tasks for Subagents:

Deep search

Log analysis

Dependency audit

Multi-file scanning

Large-scale information organization

Branch tasks that can run in parallel

If you want Claude to execute a process step-by-step in the main thread, use a Skill. If you want a side task handed to an independent assistant that returns only the result, use a Subagent.

05 | Hooks: Making Certain Actions Automatic

Hooks are easily misunderstood. They are not "remind Claude again." A Hook is an action automatically triggered by a specific event.

For example, I now use a stop hook after every Claude Code task to play a voice notification "Ready to work."

The point: a Hook doesn't let Claude choose whether to act; the system triggers it automatically when the event occurs. So if something must happen reliably, don't just put it in CLAUDE.md; use a Hook.

Examples: "Format code after every edit" suits a Hook. "Never run certain dangerous commands" also suits a Hook or permission control.

Simply: if you write "please remember to do," that's a prompt. If you need "automatically do at the right moment," use a Hook.

06 | Output Styles: Changing Claude's Overall Response Style

Output Styles control Claude's overall response style. For instance, you can make it more proactive, more explanatory, or like a learning mode.

Output Styles inject into the system prompt with high weight. If misconfigured, they may override Claude Code's default software engineering behaviors—like controlling modification scope, when to add comments, handling security, verifying before completion. A strong custom Output Style that doesn't preserve these defaults can turn Claude Code into a generic chat assistant rather than a software engineering assistant.

Therefore, Output Styles are best for "overall expression style," not for piling project rules. Project rules belong in CLAUDE.md or Rules; processes become Skills; automatic actions use Hooks.

07 | append system prompt: Temporary Requirements for a Single Session

append system prompt

adds a temporary system-level instruction when launching Claude Code. Unlike Output Styles, it's a one-time supplement.

Use cases for this session only:

Shorter answers

Fixed output format

Specific domain background

Ad-hoc conventions for this task

It's not for long-term rule accumulation. Adding too many instructions yields diminishing returns: more instructions increase conflict probability, and Claude's reliable compliance may actually decrease. So it fits temporary needs, not a project configuration center.

Final Mnemonic

If unsure where to put something, use this guide:

Project background → CLAUDE.md Local conventions → Rules

Repeatable workflows → Skills

Independent tasks → Subagents

Must happen automatically → Hooks

Overall style → Output Styles

Temporary requirements → append system prompt

This division is essentially Context Engineering: managing what Claude sees in different tasks. Model intelligence or prompt elegance often only sets the floor. The real differentiator is whether you've built a clear, restrained, maintainable context system.

Reference

https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more