Reference Card

The Context Ladder

Where each piece of knowledge lives — and when it costs context.

Rung 4 · Apex

Hook

Deterministic edge

Code that runs when the harness emits a lifecycle event. Lives outside the agent's context.

Loads onLifecycle event

Scoped byEvent + matcher

Context costZero — runs outside the model

In the demo

.claude/hooks/lint-on-edit.sh

PostToolUse · ruff on every *.py edit, surfaced back inside the same turn.

Hooks docs →

Rung 3

Skill

Trigger-fired procedure

Additional context, gated by trigger. Fire it explicitly with /my-skill, or let the agent match its description and choose to load it.

Loads onUser invocation or model match

Scoped byDescription match · /cmd

Context costRegistry only at startup; body lazy

Deeply configurable via SKILL.md frontmatter — model, allowed-tools, context: fork, disable-model-invocation, bundled refs & scripts.

In the demo

.claude/skills/feature-spec-creator/

Anchored Interview — scans the repo, asks questions, writes the spec.

Skills docs →

Rung 2

Hierarchical CLAUDE.md

Position-anchored facts

Same mechanism as rung 1, multiple positions. User and project-local positions load at startup; subdirectory loads lazy — only when Claude touches a file in that folder.

Loads onStartup (user/local) · file touch (folder)

Scoped byFile-system position

Context costAlways-on for most; folder is lazy

Positions: ~/.claude/CLAUDE.md (user) · ./CLAUDE.local.md (project-local, gitignored) · ./tests/CLAUDE.md (folder, lazy)

In the demo

tests/CLAUDE.md

Place-anchored testing conventions. Free until Claude reads a file under tests/.

Memory docs →

Rung 1 · Floor

Root CLAUDE.md

Team contract

The always-loaded baseline at the project root. Every contributor starts here; every session pays for it.

Loads onEvery session, every turn

Scoped byNone — global to project

Context costAlways-on — audit with /context

In the demo

./CLAUDE.md

Architecture, run/test commands, code style — the team contract.

Memory docs →

Pick the right rung — decision flow

If the thing you want to add is…	Place it on…	Where it lives
Always true regardless of task or location	Rung 1 — Root CLAUDE.md	`./CLAUDE.md`
True only inside a particular subdirectory	Rung 2 — Folder CLAUDE.md (lazy)	`./<dir>/CLAUDE.md`
A personal habit you carry across every project	Rung 2 — User CLAUDE.md	`~/.claude/CLAUDE.md`
A personal preference scoped to one repo only	Rung 2 — Project-local (gitignored)	`./CLAUDE.local.md`
A procedure to fire on identified need (phrase / `/cmd`)	Rung 3 — Skill	`.claude/skills/<name>/SKILL.md`
Code to run on a lifecycle event (enforce / verify / observe)	Rung 4 — Hook	`.claude/hooks/<name>.sh`
Same hook, scoped to your sessions only on this repo (e.g., personal `/compact` blocker)	Rung 4 — Hook · personal scope	`.claude/settings.local.json`