---
title: "The Right Layer: Deciding Where Knowledge Lives in Claude Code"
author: Frederic Ferrera
url: https://fredferre.com/en/blog/claude-code-context-layers
license: CC BY 4.0
---

# The Right Layer: Deciding Where Knowledge Lives in Claude Code

A decision framework for structuring Claude Code's context layers: **WHEN** to create **WHAT** and **WHY**.

---

## The 5 Layers at a Glance

| Layer | Question it answers | Advisory or Enforced? |
|-------|--------------------|-----------------------|
| **CLAUDE.md** | "Who is this project?" | Advisory |
| **Rules** | "What structural guidance does Claude need?" | Advisory |
| **Skills** | "What does Claude need to know about X?" | Advisory |
| **Agents** | "Who should handle this type of work?" | Enforced (tools) |
| **Hooks** | "What must happen every time, no exceptions?" | Enforced (code) |

---

## Decision Flow

```mermaid
flowchart TD
    START["I have knowledge or guidance<br/>I want Claude to use"] --> SCOPE

    SCOPE{"Where does it belong?"}
    SCOPE -->|"Applies to this repo only"| REPO["<b>.claude/</b><br/>Project-level, tracked in git"]
    SCOPE -->|"Useful across all my projects"| USER["<b>~/.claude/</b><br/>User-level, portable"]

    REPO --> KIND
    USER --> KIND

    KIND{"What kind of knowledge is it?"}
    KIND -->|"Project identity<br/>(stack, structure, conventions)"| CLAUDE_MD["<b>CLAUDE.md</b>"]
    KIND -->|"Structural guidance<br/>(layout, architecture refs, central docs)"| RULE["<b>Rule</b>"]
    KIND -->|"Technology expertise<br/>or repeatable workflow"| SKILL["<b>Skill</b>"]
    KIND -->|"Specialized role<br/>with different permissions"| AGENT["<b>Agent</b>"]
    KIND -->|"Mechanical guarantee<br/>(must execute, no exceptions)"| HOOK["<b>Hook</b>"]

    style CLAUDE_MD fill:#1e293b,color:#fff
    style RULE fill:#334155,color:#fff
    style SKILL fill:#475569,color:#fff
    style AGENT fill:#64748b,color:#fff
    style HOOK fill:#94a3b8,color:#1e293b
```

---

## Each Layer in Detail

### CLAUDE.md — "Who is this project?"

- **When**: Always. First thing you create.
- **What**: Project identity in <200 lines. Tech stack, build commands, file structure, conventions that can't be inferred from code.
- **Why**: Sets the baseline context for every session. It's the README for Claude.

**Litmus test**: "Would a new team member need this on day 1?" &rarr; CLAUDE.md

**Anti-pattern**: Putting detailed technology guidance here (that's a skill). Putting structural/layout guidance here (that's a rule).

---

### Rules — "What structural guidance does Claude need?"

- **When**: You need to encode layout patterns, architecture references, or pointers to central documentation — especially in large, complex projects.
- **What**: Modular `.md` files in `.claude/rules/`. Can be path-scoped with `paths:` frontmatter. Can reference external architecture docs, ADRs, or wiki pages.
- **Why**: Rules bridge Claude to your wider knowledge base. They provide structural context — how code should be organized, which patterns to follow, where to find authoritative references — without bloating every session.

**Litmus tests**:
- "Is this about how code should be structured or laid out?" &rarr; Rule
- "Does this reference architecture decisions or central documentation?" &rarr; Rule
- "Should this guidance only apply when touching specific files?" &rarr; Rule with `paths:`

**Anti-pattern**: Treating rules as CLAUDE.md overflow (they serve a different purpose). Putting reusable tech knowledge here (that's a skill).

---

### Skills — "What does Claude need to know about X?"

- **When**: You have deep knowledge about a technology, workflow, or domain that Claude should reference when relevant.
- **What**: `SKILL.md` files with frontmatter. Auto-invoked by description matching, or manually via `/skill-name`.
- **Why**: Loaded on-demand, not every session. Keeps base context clean while making deep expertise available.

**Litmus tests**:
- "Would this be useful across multiple projects?" &rarr; Skill in `~/.claude/skills/`
- "Is this tech knowledge or a repeatable process?" &rarr; Skill

**Anti-pattern**: Putting project-specific conventions in a portable skill. Skills are project-agnostic; rules handle project specifics.

#### Two kinds of skills

```mermaid
flowchart LR
    SKILL["Skill"] --> KNOWLEDGE["<b>Knowledge skill</b><br/>How does tech X work?<br/><i>e.g., Vite config patterns,<br/>Playwright locators,<br/>pnpm workspaces</i>"]
    SKILL --> WORKFLOW["<b>Workflow skill</b><br/>How do we do process Y?<br/><i>e.g., create GitLab issue,<br/>submit merge request,<br/>run Event Storming</i>"]

    style KNOWLEDGE fill:#475569,color:#fff
    style WORKFLOW fill:#64748b,color:#fff
```

---

### Agents — "Who should handle this type of work?"

- **When**: A recurring task benefits from a specialized persona with restricted tools and preloaded skills.
- **What**: Agent `.md` files defining role, allowed tools, preloaded skills, and behavioral instructions.
- **Why**: Isolation. A code-reviewer doesn't need Write access. A researcher doesn't need Edit. Agents scope context and permissions to a role.

**Litmus tests**:
- "Does this task need a different tool set or mindset than general coding?" &rarr; Agent
- "Do I keep giving Claude the same role instructions?" &rarr; Agent

**Anti-pattern**: Creating agents that are just skills with no tool/permission differences. If it's just knowledge, it's a skill.

#### Skill vs Agent — the distinction

```mermaid
flowchart TD
    Q["I want Claude to be better at testing"]
    Q --> KNOW["Does it just need<br/><b>knowledge</b>?"]
    Q --> ROLE["Does it need a different<br/><b>role and permissions</b>?"]

    KNOW -->|"Yes"| SK["<b>Skill</b><br/>Playwright best practices,<br/>testing patterns, fixtures"]
    ROLE -->|"Yes"| AG["<b>Agent</b><br/>test-writer persona +<br/>preloads testing skill +<br/>restricted to test files"]

    SK -.->|"consumed by"| AG

    style SK fill:#475569,color:#fff
    style AG fill:#64748b,color:#fff
```

> **The skill is the WHAT** (technology knowledge).
> **The agent is the WHO** (a specialist who uses that knowledge).

---

### Hooks — "What must happen every time, no exceptions?"

- **When**: You need guaranteed, deterministic execution — not advisory guidance.
- **What**: Shell commands triggered on lifecycle events (`PreToolUse`, `PostToolUse`, `SessionStart`, etc.).
- **Why**: Rules and CLAUDE.md are advisory — Claude might skip them. Hooks are code that runs.

**Litmus tests**:
- "Would it be a problem if Claude occasionally forgot to do this?" &rarr; Hook
- "Is this a shell command, not judgment?" &rarr; Hook

**Anti-pattern**: Using hooks for things that require reasoning (that's a rule or skill). Hooks are mechanical.

---

## Advisory vs Enforced

```mermaid
flowchart LR
    subgraph ADVISORY["Advisory — Claude should"]
        CM["CLAUDE.md"]
        RU["Rules"]
        SK["Skills"]
    end

    subgraph ENFORCED["Enforced — Claude must"]
        HK["Hooks<br/><i>deterministic shell</i>"]
        AT["Agent tool restrictions<br/><i>permission boundaries</i>"]
    end

    style ADVISORY fill:#1e293b,stroke:#475569,color:#fff
    style ENFORCED fill:#334155,stroke:#64748b,color:#fff
```

Claude can choose to ignore advisory layers (though it usually follows them). Enforced layers execute mechanically — no discretion involved.

---

## How Layers Relate

```mermaid
flowchart TD
    CMD["<b>CLAUDE.md</b><br/>Project identity + stack"] -->|"stack triggers<br/>auto-invocation"| SKILL["<b>Skills</b><br/>Tech knowledge"]
    RULES["<b>Rules</b><br/>Project constraints"] -->|"add project-specific<br/>constraints on top of"| SKILL
    SKILL -->|"preloaded into"| AGENT["<b>Agents</b><br/>Specialized roles"]
    RULES -->|"scope behavior of"| AGENT
    HOOKS["<b>Hooks</b><br/>Mechanical guarantees"] -->|"guarantee what<br/>rules can only advise"| RULES

    style CMD fill:#1e293b,color:#fff
    style RULES fill:#334155,color:#fff
    style SKILL fill:#475569,color:#fff
    style AGENT fill:#64748b,color:#fff
    style HOOKS fill:#94a3b8,color:#1e293b
```

---

## Scope Hierarchy

```mermaid
flowchart TD
    subgraph MANAGED["Managed (org-wide, IT-enforced)"]
        M_CMD["CLAUDE.md"] ~~~ M_SET["settings"]
    end

    subgraph MARKETPLACE["Marketplace (team-shared, installed to ~/.claude/)"]
        MK_SKILLS["skills/"]
        MK_AGENTS["agents/"]
    end

    subgraph USER["User (~/.claude/, personal)"]
        U_CMD["CLAUDE.md"]
        U_RULES["rules/"]
        U_SET["settings.json"]
    end

    subgraph PROJECT["Project (.claude/, tracked in git)"]
        P_CMD["CLAUDE.md"]
        P_RULES["rules/"]
        P_SKILLS["skills/"]
        P_AGENTS["agents/"]
        P_SET["settings.json"]
    end

    subgraph LOCAL["Local (.claude/, gitignored)"]
        L_CMD["CLAUDE.local.md"]
        L_SET["settings.local.json"]
    end

    MANAGED -->|"overrides"| MARKETPLACE -->|"installed into"| USER -->|"overrides"| PROJECT -->|"overrides"| LOCAL

    style MANAGED fill:#0f172a,color:#fff
    style MARKETPLACE fill:#1e293b,color:#fff
    style USER fill:#334155,color:#fff
    style PROJECT fill:#475569,color:#fff
    style LOCAL fill:#64748b,color:#fff
```

Higher scopes override lower ones. More specific always wins.

### Marketplace: Team-Shared Skills & Agents

Skills and agents in `~/.claude/` are **not personal** — they are distributed across the team via a **marketplace**. Any team member can install the same set of skills and agents, ensuring consistent behavior regardless of which project they're working on.

```mermaid
flowchart LR
    AUTHOR["Skill/Agent author"] -->|"publishes to"| MP["Marketplace"]
    MP -->|"installed by"| DEV1["Developer A<br/>~/.claude/skills/<br/>~/.claude/agents/"]
    MP -->|"installed by"| DEV2["Developer B<br/>~/.claude/skills/<br/>~/.claude/agents/"]
    MP -->|"installed by"| DEV3["Developer C<br/>~/.claude/skills/<br/>~/.claude/agents/"]

    style MP fill:#1e293b,color:#fff
```

This means:
- **Skills and agents are project-agnostic by design** — they carry technology knowledge and workflows, not project opinions
- **The team shares the same toolbox** — everyone has the same Playwright skill, the same code-review agent
- **Projects don't track skills/agents** — the repo's `.claude/` contains only project-specific context (CLAUDE.md, rules, settings)
- **Updates propagate via the marketplace** — fix a skill once, everyone gets the update

---

## Examples

### Knowledge skills (marketplace, team-shared)

| Skill | What it knows | Why it's a skill |
|-------|--------------|------------------|
| `vite` | Config patterns, plugins, dev server, library mode | Any Vite project benefits |
| `vitest` | Test setup, mocks, coverage, Testing Library | Vitest patterns are universal |
| `playwright` | E2E testing, locators, fixtures, Page Object Model | Playwright knowledge is project-agnostic |
| `biome` | Linting/formatting config, ESLint migration | Biome expertise applies everywhere |
| `pnpm` | Workspaces, lock files, .npmrc, CI caching | pnpm knowledge, not project-specific |
| `gitlab-ci` | Pipeline design, review apps, caching | GitLab CI patterns apply to any GitLab project |

### Workflow skills (marketplace, team-shared)

| Skill | What it does | Why it's a skill |
|-------|-------------|------------------|
| `start-work` | Create branch from issue with naming convention | Same workflow on every project |
| `submit-work` | Push branch, create MR linked to issue | Repeatable, project-agnostic |
| `review-mr` | Structured code review with acceptance criteria | Same protocol everywhere |
| `create-issue` | Create issues using templates | Templated workflow |

### Agents (marketplace, team-shared)

| Agent | Preloaded skills | Tool restrictions | Why an agent? |
|-------|-----------------|-------------------|---------------|
| `frontend-developer` | vite, biome, vitest | Full tools | Needs to write code |
| `frontend-tester` | playwright, vitest | Full tools | Different mindset than feature dev |
| `product-manager` | gitlab | **No Write/Edit** | Defines WHAT, never touches code |
| `software-architect` | architecture | **No Write/Edit** | Read-only research and design |
| `ci-engineer` | gitlab-ci | Full tools | Pipeline specialist |

### Rules (project-level, tracked)

| Rule file | `paths:` scope | What it provides |
|-----------|---------------|-----------------|
| `frontend-architecture.md` | `src/components/**/*.tsx` | "Follow Atomic Design, use PageShell wrapper, see ADR-012" |
| `database-migrations.md` | `src/migrations/**` | "Use Flyway naming, reference migration guide in docs/database.md" |
| `api-contracts.md` | `src/api/**/*.ts` | "Validate with zod, error format in src/lib/errors.ts" |

### Hooks (project or user-level)

| Hook | Event | What it does | Why not a rule? |
|------|-------|-------------|-----------------|
| `biome check` | PostToolUse (Edit/Write) | Lint after every file change | Must happen every time |
| `pnpm test` | PreToolUse (git commit) | Run tests before committing | Can't risk forgetting |
| `format` | PostToolUse (Edit/Write) | Auto-format changed files | Deterministic, no judgment |

---

## Quick Decision Cheat Sheet

```
"Would a new team member need this on day 1?"
  --> CLAUDE.md

"Is this about layout, structure, or architecture references?"
  --> Rule

"Should this guidance only load when touching specific files?"
  --> Rule (with paths: frontmatter)

"Is this reusable tech knowledge or a repeatable process?"
  --> Skill

"Does this need different tools or a different persona?"
  --> Agent

"Would it be a problem if Claude forgot to do this?"
  --> Hook

"Is it just knowledge with no permission difference?"
  --> Skill, not Agent
```

---

## File System Layout

```
~/.claude/                        (user-level)
  CLAUDE.md                       "I always prefer..." (personal)
  settings.json                   permissions, hooks, MCP (personal)
  rules/                          personal default constraints
  skills/                         installed from marketplace (team-shared)
    vite/SKILL.md
    playwright/SKILL.md
    start-work/SKILL.md
  agents/                         installed from marketplace (team-shared)
    frontend-developer.md
    product-manager.md

.claude/                          (project-level, tracked in git)
  CLAUDE.md                       "This project is..."
  settings.json                   team permissions, hooks
  settings.local.json             machine-specific (gitignored)
  rules/                          project-specific constraints
    api-contracts.md
    ui-components.md
  skills/                         project-specific workflows (rare)
  agents/                         project-specific specialists (rare)
```

---

*By [Frederic Ferrera](https://fredferre.com) — [Read the interactive version](https://fredferre.com/en/blog/claude-code-context-layers)*