Claude Code Configuration and Workflows

Mechanism reference

This section documents every mechanism in the hierarchy with full field names, ordering rules, value spaces, and boundary conditions. Each subsection traces ownership to the layer that actually enforces the guarantee.

Mechanism reference: 1. The CLAUDE.md tiers and what travels

Claude Code discovers CLAUDE.md in four documented locations plus enterprise delivery, each with a distinct scope, storage tier, and sharing contract.

Two points that are tested by distractor phrasing deserve emphasis. First, both ./CLAUDE.md and ./.claude/CLAUDE.md count as project tier and both can be active simultaneously; a project with both has two active project files at once, not a conflict. Second, CLAUDE.local.md is not a fourth settings tier; it is memory with the same concatenation semantics and the same lack of guarantee as any other CLAUDE.md. Reading last does not confer precedence.

Secrets and sensitive paths illustrate the sharing boundary. The lessons state plainly not to put secrets in project CLAUDE.md because it is committed; API keys, passwords, and tokens belong in environment variables or in gitignored CLAUDE.local.md. The operational consequence is that any secret written to project memory leaks to every clone and to the model's context that is sent to the API, so the correct pattern is a reference such as STAGING_DB_URL via env, not a literal value in Markdown.

Size and token budget interact with tier choice. Files over roughly 200 lines consume proportionally more of the context window and reduce adherence; a checked-in file over 4 MiB is skipped entirely. The guide's remedy for a 600 to 900 line monolith is not a larger file but decomposition into .claude/rules/ with paths or into a skill that loads on demand, because those surfaces allow conditional loading while every tier of CLAUDE.md is always-loaded or lazily-always within its subtree.

Mechanism reference: 2. Load walk, concatenation, and order

The guides are consistent on three facts that together defeat every "which wins" distractor.

All discovered files are concatenated into context rather than overriding each other is stated verbatim. The walk collects CLAUDE.md and CLAUDE.local.md from the current working directory and every directory above it, ordering content from filesystem root down to working directory, so instructions closer to launch are read last. Within each directory, CLAUDE.local.md is appended after CLAUDE.md so personal notes are the last text at that level.

What this means operationally is that three files can be active at once for a developer working in packages/api under a repository that keeps both project locations: root CLAUDE.md, .claude/CLAUDE.md, and packages/api/CLAUDE.md all contribute text, with packages/api/CLAUDE.local.md appended after the package file if present.

No override, no silent discard, no recency tie-break. If two files contradict - single versus double quotes, 2 versus 4 space indentation, snake_case versus camelCase - both strings remain in context and if two rules contradict each other, Claude may pick one arbitrarily with there is no guarantee of strict compliance. The channel is a user message after the system prompt, which is probabilistic guidance, not a system instruction.

Subdirectory files and path-scoped rules are lazy. The walk-up chain loads at launch. Subdirectory CLAUDE.md under the working directory and any .claude/rules/*.md with paths frontmatter load only when Claude reads a file that the scope covers. A session that never touches packages/payments/ never pays for packages/payments/CLAUDE.md. This is the mechanism that makes per-package rules economical and explains why a file can appear to vanish after /compact and then reappear on the next matching read.

Block-level HTML comments <!-- maintainer notes --> are stripped before injection, which saves tokens; comments inside code blocks are preserved and remain visible when opening the file with Read.

Mechanism reference: 3. Example: layered memory layout for a monorepo

The first required substantial example shows a realistic monorepo with all tiers active, how the discovery walk concatenates, and where the "last word" actually sits versus where the guarantee sits. It is the connected layout that the later enforcement examples will reuse.

# File: ~/.claude/CLAUDE.md (user tier, personal, not committed)

Personal defaults

• Prefer verbose, descriptive variable names over short abbreviations.
• Always add JSDoc comments to exported functions.
• For TypeScript: strict mode, no any types, explicit return types.

# File: /Library/Application Support/ClaudeCode/CLAUDE.md (managed, org policy) # Deployed via MDM, cannot be excluded via claudeMdExcludes

Organization standards

• Never log raw PII; use structured logger with redaction.
• All API handlers must validate input with Zod.

# File: ./CLAUDE.md (project tier, committed, shared)

Tech Stack

• Framework: Next.js 15 with App Router
• Styling: Tailwind CSS with shadcn/ui components
• Testing: Vitest + Testing Library

Commands

• Build: npm run build
• Test: npm test
• Lint: npm run lint
• Typecheck: npm run typecheck

Conventions

• Components: one file per component in src/components/
• API routes: src/app/api/[route]/route.ts
• State: Zustand stores in src/stores/, not component useState

# File: ./.claude/CLAUDE.md (also project tier, committed)

Architecture notes

• src/lib/api.ts is the only place that makes fetch calls.
• Error handling: wrap with AppError and include code.

# File: ./packages/api/CLAUDE.md (directory tier, committed, lazy) # Loads only when Claude reads a file under packages/api/

API package

• Express.js with TypeScript, Zod validation on every endpoint.
• Routes in packages/api/src/routes/, services in packages/api/src/services/.
• Endpoints require authMiddleware; request and response schemas use camelCase with error.details array.

# File: ./packages/api/CLAUDE.local.md (local, gitignored, appended last at that level)

Local scratch

• Test account: [email protected], staging DB at localhost:5433.
• Temporary: verbose logging for this week's auth debugging.

How this loads for a developer who runs claude from packages/api and then opens a file under that package: text Load order (concatenated into one user message, root down to working dir, local appended after its sibling at each level): 1 Managed /Library/Application Support/ClaudeCode/CLAUDE.md 2 User ~/.claude/CLAUDE.md 3 Project ./CLAUDE.md 4 Project ./.claude/CLAUDE.md 5 Dir ./packages/api/CLAUDE.md (lazy: on first Read inside packages/api) 6 Local ./packages/api/CLAUDE.local.md (appended after dir file at that level) 7 Rules ./.claude/rules/*.md without paths (loaded at launch alongside .claude/CLAUDE.md) 8 Rules ./.claude/rules/*.md with paths (lazy: when a matching file is touched) Active set while editing inside packages/api: 1 plus 2 plus 3 plus 4 plus 5 plus 6 plus 7 plus any matching 8. Active set while editing inside packages/web: 1 plus 2 plus 3 plus 4 plus 7, sibling dir files stay unloaded.

What this example proves and where it fails. It proves that personal preferences stay personal via ~/.claude/CLAUDE.md or CLAUDE.local.md and that team conventions become durable only at project or directory tier via committed files. It proves that splitting a long project file into package files reduces cross-package noise only because directory files are lazy, not because concatenation was avoided. Its failure boundary is enforcement: if the project file says never write to config/ or always run prettier, that phrasing is still guidance that the model may miss on a busy turn; deterministic guarantees belong in settings.json or hooks, not in any tier of CLAUDE.md.

Local scratch: 4. @path import composition: eager, relative, bounded, and span-safe

Imports are the composition mechanism for CLAUDE.md. The guide's syntax is bare @path/to/file anywhere in prose such as See @README for project overview and @package.json for available npm commands and git workflow @docs/git-instructions.md.

Four rules govern the mechanism.

Relative resolution. Both relative and absolute paths are allowed, and relative paths resolve against the directory containing the importing CLAUDE.md, not the working directory where claude was launched. A file at .claude/CLAUDE.md that imports @./standards/naming.md therefore looks beside .claude/, not at repository root, which is the common source of "import exists but never loads" reports.

Eager inlining, same context cost. Imported files are expanded and loaded into context at launch alongside the containing file. Whether the text lives in one 600-line file or six 100-line files, the model sees the same total tokens; the split is an authoring win, not a token win. If the goal is to shrink per-session context, the tool is .claude/rules/ with paths or a skill.

Maximum depth of four hops. Imported files can recursively import others, up to a maximum depth of four hops; beyond that, further imports are silently not resolved. Deeply layered shared-config chains lose content past the bound without an error.

Code span and fence safety. Import parsing skips Markdown code spans and fenced code blocks, so @README inside backticks is literal text and is not imported, while bare @README in prose is imported. This is the boundary that distinguishes accidental mention from intentional import.

Silent skip on missing targets is a further boundary. A directive whose path does not exist is silently skipped and the session starts without that block. The practical consequence is that a typo or an uncommitted filename produces a silent gap that is visible only via /context or /memory.

Local scratch: 5. Example: import composition with depth and span safety

The second required example shows a publishable import graph that respects relative resolution, the four-hop bound, and code-span safety, and it evolves the layered layout into a maintainable standards tree.

# File: .claude/CLAUDE.md (project tier, imports resolve relative to .claude/) # Coding standards @./standards/naming-conventions.md @./standards/error-handling.md @./standards/testing-requirements.md # Architecture notes (local to this file, not imported) - src/lib/api.ts is the only place that makes fetch calls. - Commit format [TICKET-ID] Brief description; use 4 space indentation. # Reference material exposed via import (not via pasted prose) See @README for project overview and @package.json for available npm commands. Mention literal paths safely: use @docs/api-private.md in comments, not @docs/api-private.md. # File: .claude/standards/testing-requirements.md (imported, committed)

Testing

• Run npm test before committing; tests live in __tests__/ adjacent to source.
• Use describe and it blocks, not test() directly.
• Imported by: .claude/CLAUDE.md hop 1
• Also imports: @./fixtures/shared-fixtures.md hop 2 (still within four-hop budget)

# File: .claude/standards/fixtures/shared-fixtures.md (hop 2)

Fixtures

• Fixture factory lives in tests/fixtures/factory.ts; do not duplicate factories per package.
• Hop chain: .claude/CLAUDE.md (0) -> standards/testing-requirements.md (1) -> fixtures/shared-fixtures.md (2)
• Any file that writes @ inside fences is safe:

# Example inside imported file - fenced block below is NOT an import Here the author mentions @./should-not-import.md inside a code block.

# File: packages/api/CLAUDE.md (directory tier, selective import) # This package only needs API conventions, not frontend standards @../../.claude/standards/api-conventions.md

Package scope

• Routes in packages/api/src/routes/, services in packages/api/src/services/.
• All endpoints require auth middleware and Zod validation.

Observable outcome. Running /context from repository root shows the project tier plus all three imported standards inlined as if their text lived inside .claude/CLAUDE.md; running from packages/api and reading a file inside that subtree also adds the directory tier and its selective import. Mentioning @README inside backticks or inside a fenced block does not create an extra Memory files entry. A fifth hop such as an import inside shared-fixtures.md that points to yet another file that itself imports further would be silently dropped once the depth budget is exceeded, which is visible as missing text in /context, not as an error.

Package scope: 6. .claude/rules/ and claudeMdExcludes

.claude/rules/*.md is the companion to directory CLAUDE.md for larger projects. Rules are discovered recursively, and a rule without paths frontmatter loads at launch with the same priority as .claude/CLAUDE.md; a rule with paths loads only when Claude works with files matching the specified patterns.

Path patterns use glob syntax. The guide documents single and multiple patterns plus brace expansion such as src/*/.{ts,tsx} and a shared expansion budget of 1,000 expanded patterns and 4 MiB per rule, with bracket expression rules like escaping literal [ as \[. Lessons emphasize that permission rules (allow, ask, deny) never belong in rules files; those arrays live in settings.json.

claudeMdExcludes is the discovery filter that removes noisy targets from the walk. It is an array of glob patterns matched against absolute file paths, set in any settings.json tier, merging across tiers, and its most consequential boundary is that managed policy files cannot be excluded.

// File: .claude/settings.local.json (local tier, gitignored, personal)
// Discovery filter: skip other teams' CLAUDE.md that leak into this walk
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**",
    "**/vendor/**",
    "**/__generated__/**"
  ]
}

The rule-level companion to walk-level exclusion is negation inside a path-scoped rule. The guide explicitly groups paths: ["/.ts", "/.tsx", "!/__generated__/", "!vendor/**"] as type glob with exclusions inside the rules tier, which is a distinct stage from walk exclusion, applied only after discovery, not instead of it.

--add-dir adds extra directory roots. By default their CLAUDE.md chains are not loaded; setting CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 opts into loading them alongside the primary working directory walk. Whether claudeMdExcludes also filters those added walks when the gate is enabled is the single point that remains not independently confirmed for lack of a combined example in documentation or lessons.

Package scope: 7. What survives compaction and what reloads

Block-level HTML comments aside, the compaction story is deliberately narrow. The conversation history is summarized and replaced, but CLAUDE.md at the project root is re-read from disk and re-injected after /compact because it was never part of the history to compress, so its instructions return intact. Nested CLAUDE.md files in subdirectories and rules with paths frontmatter do not return immediately; they reload the next time Claude reads a matching file rather than at the moment compaction ends.

Any instruction that only ever existed in conversation is free for the summariser to compress, which is why the durable fix for "vanished after compact" is to move the instruction into a tier that survives: project CLAUDE.md for universal, directory CLAUDE.md for subtree, or path-scoped rule for file-type scope. The InstructionsLoaded hook and /context are the two verification surfaces for whether a file did in fact reload in the current session.

Ownership map

Which layer owns which guarantee is the pivot for every diagnostic and every exam trap. Memory and settings are separate contracts with different enforcement positions.

Ownership map: Model and context delivery

The model owns probabilistic weighing of guidance that arrives as a user message. CLAUDE.md at any tier - managed, user, project, local, directory, and .claude/rules/ - is injected as context after the system prompt, before the conversation turns begin. The model decides how strongly to apply that guidance relative to existing code style and explicit user requests, with specificity and brevity increasing adherence. The client owns whether the text is present at all, which files are discovered, and in what order they are concatenated, but the model owns the per-token decision of whether to follow them on a given turn, and may pick arbitrarily when they conflict.

Ownership map: Claude Code client and CLI

The Claude Code client owns discovery, ordering, and lifecycle. It walks the filesystem from root down to working directory, appends CLAUDE.local.md after CLAUDE.md at each level, eagerly inlines @path imports respecting depth and code-span rules, applies claudeMdExcludes before concatenation, and gates --add-dir roots behind CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD. It reloads project-root CLAUDE.md after /compact, watches settings.json files for live reload, and exposes /memory as the file browser and auto-memory toggle and /context as the loaded-set reporter. Infrastructure such as MDM or Group Policy owns deployment of managed CLAUDE.md and managed-settings.json, which the client treats as non-excludable and top-ranked.

Ownership map: settings.json and permission evaluation

The client owns deterministic enforcement via settings.json. The permissions object with allow, ask, deny plus hooks is evaluated before the model acts, with deny evaluated first so a matching permissions.deny blocks even if another scope allows. The precedence stack is managed policy at the top, then --settings command-line JSON, then .claude/settings.local.json, then .claude/settings.json, then ~/.claude/settings.json at the bottom; lists merge instead of replacing for most array keys. Application code does not override these rules at runtime; it requests tools and the client decides.

Ownership map: Hooks

The client owns hook dispatch as a lifecycle gate. Events such as PreToolUse, PostToolUse, PostToolUseFailure, SessionStart, InstructionsLoaded, FileChanged, CwdChanged, Stop and roughly thirty others fire at fixed points, matching on tool name or literal filename, and invoking one of five handler types: command, http, mcp_tool, prompt, or agent. A PreToolUse hook can deny a tool before the model sees success, and a PostToolUse hook can rewrite tool_output via updatedToolOutput or inject additionalContext. Where multiple hooks conflict, the merge order is deny above defer above ask above allow. This position before or after the tool call is what makes hooks deterministic while memory is not.

Ownership map: Agent SDK

The Agent SDK owns which settings.json tiers an embedded agent sees via the settingSources selector, and which system prompt preset the session uses. The lesson and the forensics file agree that the SDK default loads no filesystem settings, so project CLAUDE.md, rules, and skills remain invisible unless the caller explicitly includes project and optionally user. Application code that embeds the SDK therefore owns the scope decision, while the client still owns enforcement once the scope is selected.

Ownership map: Summary table

Version and terminology currency

Three vocabulary shifts matter for interpreting both documentation and exam distractors.

Managed versus enterprise versus organization-wide. The reference page phrases top-tier governance as managed policy sits above all memory tiers and cannot be overridden by project or user. Current guides use managed policy, managed settings, and managed-settings.json interchangeably, delivered via MDM, Group Policy, or server-managed settings, and describe claudeMd as the key that embeds managed CLAUDE.md content inside managed-settings.json itself. The exam guide's phrasing is therefore current, not legacy, and the lesson diagrams that show managed at the ceiling of both memory and settings remain the correct mental model.

settings.json hierarchy wording. Older discussion sometimes described settings as project, local, user in ambiguous order. The fetched settings guide resolves this unambiguously as managed above command line above project local above shared project above user, with the explicit note that command-line --settings JSON sits between managed and local. Lessons mirror this as managed or server-managed above settings.local.json above settings.json above ~/.claude/settings.json, with scalars overriding and permission arrays concatenating. The exam trap that swaps local and project in the chain is therefore stale and should be answered with the client precedence above.

Diagnostic command naming. The split between /memory and /context is the only terminology fork that is recent. Earlier Claude Code versions placed loaded-file reporting under /memory; current builds place it under /context under Memory files and reserve /memory for browsing, editing, and toggling auto memory. Lessons capture both surfaces and note the exam keys /memory while the keyboard shows /context. The exam tip on the reference page that On the exam, answer /memory is therefore version-accurate for keyed scoring; at the actual keyboard the proof step is /context.

Gate and key introductions. Two flags that appear as distractors precisely because older material omitted them are now fully documented. claudeMdExcludes is the documented walk-level filter with glob against absolute paths and cannot exclude managed files. CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 is the explicit opt-in to loading CLAUDE.md chains from --add-dir roots. A third set of enterprise keys - companyAnnouncements, disableBundledSkills, skillOverrides, availableModels, and $schema - gate what project files can do and surface validations in the editor when $schema points at https://json.schemastore.org/claude-code-settings.json, but do not change the memory hierarchy itself.

Import limits and span rules. The four-hop import depth and the code-span and fence skip are both current, not a recent tightening, and appear identically in the fetched guide and both lessons. Any material claiming unlimited depth or that backtick wrapping still imports is stale.

Official versus community divergence

Where community-written tutorials contradict the fetched guides, the guides control the keyed answer and the tutorial phrasing should be treated as a distractor.

A final divergence is the permissions syntax itself. Community examples sometimes scope built-in tools with a wildcard tool name. The lessons clarify that for built-in tools like Bash and Read, you scope with a parenthesized pattern such as Bash(npm test) or Read(./.env), with wildcard tool name only after a literal mcp__<server>__ prefix. The guide's settings example uses the same parenthesized form. The parenthesized pattern is the documented, testable form.

Beyond the task statement

The lessons cover several adjacent topics that the reference page omits entirely. Each matters for diagnosing hierarchy issues in production and for avoiding traps in sibling tasks.

.claude/rules/ with paths frontmatter and the rules-vs-skills boundary. The memory guide introduces --- YAML frontmatter with a paths array such as /.ts, src/api//.ts, or src/*/.{ts,tsx} that limits a rules file to sessions touching those files, and documents a shared budget of 1,000 expanded patterns plus 4 MiB per rule and bracket-escape rules like \[. The lessons connect this to the broader rule that permission arrays never belong in rules files and to the boundary that task-specific, conditional knowledge belongs in a skill that loads on demand rather than in always-loaded CLAUDE.md. For this task it matters because the reference page's correct fix for cross-directory type scoping and for 600 plus line bloat is not another directory CLAUDE.md but a path-scoped rule or a skill.

Auto memory as distinct from authored CLAUDE.md. The guide describes a separate auto-memory system that Claude writes itself at ~/.claude/projects/<project>/memory/ with MEMORY.md as the index and per-topic files such as user_role.md or feedback_testing.md, toggled via /memory and the autoMemoryEnabled and autoMemoryDirectory settings. Its load contract is that the first 200 lines or 25KB of MEMORY.md enter every session while topic files load on demand. It matters because troubleshooting that conflates missing user feedback with missing CLAUDE.md will misdiagnose the wrong store, and because subagents by default do not inherit main auto memory except for a fork.

$schema, enterprise keys, and the managed-settings.json shape. Lessons add a schema hint at https://json.schemastore.org/claude-code-settings.json for validation, and enterprise keys companyAnnouncements, disableBundledSkills, skillOverrides, availableModels, and claudeMd that gate models and skills at the managed tier and restrict how model and availableModels in user or project files are applied. This is adjacent because the reference page's managed policy overrides both project and user is the correct hierarchy intuition, but the exact mechanism is the managed settings.json ceiling plus the claudeMd string key that can replace a managed CLAUDE.md file.

Permission modes at runtime and AGENTS.md interop. The core capabilities lesson documents runtime permission modes default, plan, acceptEdits, auto, dontAsk, and bypassPermissions with per-mode tables for read, edit, write, and shell behavior, plus the /permissions live toggle. The memory guide adds that Claude Code reads CLAUDE.md, not AGENTS.md, and treats @AGENTS.md or a symlink as the interop path. Both are adjacent because exam scenarios often pair a hierarchy diagnosis with a permission-mode or interop distractor that this task alone does not explain.

Worked production examples

Each example traces a full diagnostic or rollout story with concrete files, observable proof points, and the failure mode that the correct tier avoids.

Worked production examples: Example A: new teammate receives inconsistent naming despite same branch

Starting state. A team of four has a repository with a 400 line project CLAUDE.md at the root that covers naming conventions, error patterns, architecture, and testing. One senior member's Claude sessions respect REST endpoint naming GET /api/v1/resources, camelCase with error.details, and Vitest with supertest, while a new hire who cloned last week sees PascalCase endpoints and jest snippets on the same branch. Code review catches the drift only after merge requests.

Diagnosis chain. Check sharing contract: project CLAUDE.md at ./CLAUDE.md or ./.claude/CLAUDE.md is committed and reaches every clone, while ~/.claude/CLAUDE.md does not travel through git. Run /context in both developers' sessions and compare the Memory files list. The senior member's list shows an extra entry such as ~/.claude/CLAUDE.md that the new hire lacks, or the project file is an empty stub. Run /memory to open each side's actual files and confirm the naming block lives only in the senior member's home directory file. The root cause is therefore scope mismatch, not a model or tool difference.

Fix with import composition to avoid future copy. Move the naming block into a single canonical file such as .claude/standards/api-conventions.md committed alongside the repository, then point the project file at it via a relative import, and verify via /context. Because imports are eager and relative to the containing file, the path must be relative to .claude/CLAUDE.md, not to root, and the file must be committed so future clones resolve it.

The before and after layout is visible in the canonical layer example above, but the diagnostic proof is what matters on the exam: if the convention were truly at project tier, /context would list the project file for both developers; if it appears only for the author, it is at user tier. The correct fix always moves the text to project tier and commits, rather than distributing a paste into every teammate's ~/.claude/CLAUDE.md or asking teammates to run /memory to activate it, because /memory does not trigger loading and user files still would not travel.

Failure avoided. Without the move, every new clone reintroduces the inconsistency, and any attempt to "strengthen" the user file with IMPORTANT or YOU MUST cannot guarantee the result because memory remains probabilistic and may be picked arbitrarily on conflict. The durable fix converts guidance into shared, committed context that every session loads at start, not into a personal file that only its owner loads.

Worked production examples: Example B: monorepo with colliding package conventions

Starting state. A monorepo has packages/api and packages/web under a single root. The root CLAUDE.md contains roughly 800 lines that try to hold both API rules (Express.js, Zod validation, authMiddleware) and frontend rules (React 19, Next.js, Tailwind CSS) with conditional prose such as When working in backend, apply these settings. Developers working in packages/web report that sessions occasionally suggest Express patterns, and sessions working in packages/api sometimes emit React component scaffolds with shadcn/ui phrasing that does not belong.

Diagnosis chain. The conditional prose anti-pattern is flagged explicitly: writing When in backend/, apply these settings: inside the root file does not gate anything, because the file is always loaded for every session regardless of working directory. Check /context from two working directories: from root and from inside packages/api. The root list shows only the walk-up chain, while the packages/api session after reading a file inside that directory also shows packages/api/CLAUDE.md. With a single monolithic root file, both rule families are always present and the model bleeds conventions across packages, quantified in review notes as a noticeable share of edits showing cross-application even after header sharpening.

Fix with directory tier plus selective imports versus path-scoped rules. The correct split depends on which axis the conventions follow.

• If relevance follows the directory tree, keep package-specific guidance in that package's CLAUDE.md and keep only genuinely universal text at the root; directory files load lazily only when Claude reads inside that package, so a session working only in packages/web never pays for packages/api/CLAUDE.md.
• If relevance follows file type across non-contiguous locations such as */migrations/.sql scattered across db/migrations, services/auth/migrations, and tools/data/migrations, a directory file per folder duplicates guidance and still misses files; the correct mechanism is .claude/rules/ with paths frontmatter scoped by extension.

A publishable split therefore looks like a thin project root that holds only universal commands and state placement, a committed packages/api/CLAUDE.md with API conventions, a committed packages/web/CLAUDE.md with frontend conventions, and shared linting standards imported selectively so each package pulls only what it needs rather than duplicating a single source of truth.

Failure avoided. The monolithic conditional approach leaves both families in context for every session, which is exactly the shape that produces arbitrary bleed. The decomposed shape keeps each session's context proportional to the package it is touching, and the lazy loading also preserves the /compact guarantee: only the root returns automatically, package files return on next matching read rather than polluting the post-compact context for an unrelated package.

Worked production examples: Example C: noisy discovery and the excludable versus non-excludable boundary

Starting state. A platform team shares an orchestrator script that invokes claude --add-dir ../shared-lib to make a shared library reachable, and a polyglot monorepo that carries vendored SDK copies under vendor/ and generated GraphQL clients under __generated__. Developers report that Claude sessions in unrelated packages occasionally quote conventions from a vendored CLAUDE.md and from another team's CLAUDE.md that appeared via an ancestor directory, while the shared library's conventions never appear despite --add-dir.

Diagnosis chain. Discovery is governed by two separate filters. Walk-level exclusion via claudeMdExcludes suppresses paths from the walk before concatenation, matched against absolute file paths, merging across tiers, and unable to exclude managed policy. Per-file gating via paths inside .claude/rules/ is the post-discovery gate that loads authored type conventions only when touched files match. --add-dir itself only extends the walk to additional roots; by default those roots' CLAUDE.md chains are not loaded until the environment gate CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 is set.

Fix with explicit opt-in rather than silent expectation. Three concrete changes close the gap. First, make the walk exclusion explicit in a local or project settings.json so vendored and generated trees never enter discovery. Second, set the --add-dir gate variable when the shared library's conventions should be part of the session. Third, where a convention should follow a type wherever it appears, such as */.ts except generated, use a path-scoped rule with negation rather than a walk exclusion, because that decision is about authored type conventions, not about noisy discovery. The distinction between the two exclusion stages is explicitly called out in the walk example in the mechanism section.

Failure avoided. Relying on .gitignore or on an imagined .claudeignore does not suppress discovery; the real control is claudeMdExcludes. Expecting --add-dir alone to load memory leaves the session with reachable code but missing instructions, and the fix is a one-variable opt-in, not a change of working directory or a manual paste into the primary CLAUDE.md.

Worked production examples: Example D: determinism boundary where memory alone fails

Starting state. A project adds Always run clang-format after editing or Never modify config/ to CLAUDE.md or to a path-scoped rule, yet pull requests occasionally arrive with unformatted diffs or with writes inside config/. Attempts to reinforce the prose with IMPORTANT or repeated emphasis do not close the gap, and the oversized guidance file grows past 500 lines, further reducing adherence.

Diagnosis chain. CLAUDE.md is guidance shaped probabilistically as a user message, not deterministic enforcement, and oversized files lose adherence even when IMPORTANT is present. The guide's explicit fix is to use a hook that fires at a fixed lifecycle event regardless of what the model decides. Settings-level permissions.deny is the companion for blocking. Choosing between the two is a lifecycle question: PreToolUse to block before execution versus PostToolUse to auto-fix after a successful edit.

Fix as two required patterns. This task requires both settings-based and hook-based enforcement examples to be shown as substantial, language-tagged blocks. The next section provides the complete settings.json and hooks configurations that the team should have committed instead of relying on memory. The observable outcome is that a blocked write never executes and a formatting run normalizes the diff before the model reports completion, which prose instructions alone cannot promise.

Settings-based enforcement, hook-based enforcement, and Agent SDK embedding

These three examples are the enforcement half of the hierarchy. Each is a complete, language-tagged configuration with an explanation of what it proves, where it fails if miswired, and what the observable output looks like.

Settings-based enforcement, hook-based enforcement, and Agent SDK embedding: Example 3: settings-based enforcement with permissions rules in settings.json

This example encodes the "must never" and "must ask" guarantees that CLAUDE.md cannot provide, using the permissions object that the client evaluates deny-first before the model acts. It commits at project tier as .claude/settings.json so the policy travels via git, with a local override layer at .claude/settings.local.json for personal exceptions that should not ship to teammates.

// File: .claude/settings.json  (project tier, committed, shared via git)
// Purpose: deterministic guarantees for tool, network, and scope boundaries
// Enforcement: client evaluates `deny` before anything else; lists merge across tiers
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Read(**/*)",
      "Grep(**/*)",
      "Glob(**/*)",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(npm run typecheck)",
      "Bash(ls *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "ask": [
      "Bash(npm install *)",
      "Bash(rails db:migrate*)",
      "Bash(rake db:migrate*)",
      "Edit(**/*)",
      "Write(**/*)"
    ],
    "deny": [
      "Bash(scp *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Bash(nc *)",
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(chmod 777 *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/prod.json)",
      "Write(./config/**)",
      "Edit(./config/**)"
    ]
  },
  "claudeMdExcludes": [
    "**/vendor/**",
    "**/__generated__/**",
    "**/monorepo/other-team/.claude/rules/**"
  ],
  "model": "team-default",
  "hooks": {}
}

// File: .claude/settings.local.json  (local tier, gitignored, personal)
// Purpose: personal overrides for this project on this machine without affecting teammates
// Precedence: local above project; a local `allow` does not outrank a managed or project `deny`
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm test -- --watchAll=false)"
    ],
    "deny": []
  },
  "claudeMdExcludes": [
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

What this proves. Read and search tools are safe and cheap, so they are allowed without prompt; writes and package installs stay behind ask so a human confirms; destructive and network tools are denied permanently even if a permissive acceptEdits mode or a local allow would otherwise auto-approve them. Sensitive files such as .env and ./secrets/** are unreadable regardless of what CLAUDE.md suggests, which is the correct answer whenever an option proposes to "add a CLAUDE.md instruction to never read .env". The claudeMdExcludes array keeps vendored and generated instructions out of discovery so they never reach concatenation, with managed files explicitly non-excludable.

Failure boundaries. A bare Bash(scp *) style pattern blocks the subcommand class; the parenthesized pattern is the documented form for built-in tools, not a wildcard tool name except after mcp__<server>__. An allow entry added locally via "Yes, and do not ask again" writes to .claude/settings.local.json and therefore does not outrank a project or managed ask or deny for the same tool, which is visible when the prompt reappears despite the prior approval; the fix is to put the rule at the correct tier or to use the destination picker to write to the project's shared file where appropriate. Lists merge, so adding a project deny does not erase a user allow; the deny still wins for that pattern because of deny-first evaluation, not because the array replaced.

Observable output. Launch claude from the repository root and run /status; the Setting sources line shows User settings, Project settings, and Project local settings as loaded files, and for a managed deployment also shows the managed source. Attempt Bash(scp file host:) or Read(./.env) in a session; the client blocks before execution and surfaces a decision rather than asking the model, which is the direct contrast with CLAUDE.md phrasing that shapes behavior but is not a hard layer.

Settings-based enforcement, hook-based enforcement, and Agent SDK embedding: Example 4: hook-based enforcement for formatting and blocking

Hooks are the lifecycle guarantee that survives per-turn model variation. They run at fixed points such as PreToolUse, PostToolUse, PostToolUseFailure, SessionStart, InstructionsLoaded, FileChanged, CwdChanged, PreCompact, and Stop, and each handler type - command, http, mcp_tool, prompt, or agent - is declared under hooks.<EventName> with a matcher that filters by tool name or literal filename.

// File: .claude/settings.json  (project tier, committed, enforcement via hooks)
// Two hooks replace two CLAUDE.md phrases that cannot guarantee per-run behavior
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Read(**/*)", "Grep(**/*)", "Glob(**/*)"],
    "deny": ["Bash(scp *)", "Bash(curl *)", "Bash(rm -rf *)"]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/deny-config-write.sh"
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-network-and-rm.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format-after-edit.sh"
          }
        ]
      }
    ],
    "InstructionsLoaded": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/log-instructions.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# File: .claude/hooks/deny-config-write.sh  (PreToolUse, blocks Write or Edit under config/)
# Reads hook JSON on stdin, denies writes to ./config/** deterministically
set -euo pipefail
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty')
if [[ "$FILE_PATH" == *"config/"* ]]; then
  jq -n --arg reason "Writes to config/ are not allowed; use the approved config pipeline." '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: $reason
    }
  }'
  exit 0
fi
exit 0

#!/bin/bash
# File: .claude/hooks/block-network-and-rm.sh  (PreToolUse on Bash)
# Separate handler so matcher plus `if` grouping is explicit; see hook resolution diagram
set -euo pipefail
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$COMMAND" | grep -Eq 'scp |curl |wget |nc |rm -rf'; then
  jq -n --arg reason "Destructive or network command blocked by hook" '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: $reason
    }
  }'
  exit 0
fi
exit 0

#!/bin/bash
# File: .claude/hooks/format-after-edit.sh  (PostToolUse, reactive fix after Write or Edit)
# Runs formatter deterministically; rewriting tool output is not needed here
set -euo pipefail
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty')
if [[ -z "$FILE_PATH" || ! -f "$FILE_PATH" ]]; then
  exit 0
fi
case "$FILE_PATH" in
  *.ts|*.tsx|*.js|*.jsx|*.json|*.md)
    npx prettier --use-tabs=false --tab-width=4 --write "$FILE_PATH" >/dev/null 2>&1 || true
    ;;
esac
jq -n --arg msg "PostToolUse: formatted $FILE_PATH if applicable" '{
  hookSpecificOutput: {
    hookEventName: "PostToolUse",
    additionalContext: $msg
  }
}'

#!/bin/bash
# File: .claude/hooks/log-instructions.sh  (InstructionsLoaded)
# Logs which CLAUDE.md and .claude/rules/*.md were loaded and why
set -euo pipefail
INPUT=$(cat)
echo "$INPUT" | jq -r '[.hook_input // .] | @json' >> "${CLAUDE_PROJECT_DIR}/.claude/logs/instructions.log" 2>/dev/null || true
exit 0

What this proves. PreToolUse with a Write|Edit matcher that inspects tool_input.file_path deterministically blocks modifications under config/ even when CLAUDE.md says the same thing, because the hook fires before execution regardless of model choice. PostToolUse with the same matcher guarantees that prettier runs after every successful edit, replacing always run formatter after editing prose that is occasionally skipped with normalization that cannot be skipped. InstructionsLoaded gives a persistent record of which instruction files were loaded and when, which is the audit alternative to repeatedly running /context during a long session.

Failure boundaries. A missing or too-broad matcher is the most common miswiring: a Bash-matcher hook that is supposed to gate writes never fires for Write calls, and a FileChanged matcher that uses a glob or regex never matches because that event matches literal filenames only. Hooks run in parallel per event and merge by deny above defer above ask above allow, so a single deny from one handler wins over an allow from another. Exit codes matter: 0 means no hard block (with optional JSON body for structured deny, ask, defer, or allow and optional updatedInput or updatedToolOutput and additionalContext), 2 is a hard block via stderr feedback, and any other code is treated as a hook error that still allows the operation but logs a warning. Inspect live wiring with /hooks to confirm matcher, type, and recent firings before adding log statements.

Observable output. After committing the hook directory and settings.json, run claude --debug-file /tmp/hooks.debug and trigger a Write under config/; the debug log shows hook execution details including exit code and stdout and stderr, and an attempt to write inside config/ is denied with the permissionDecisionReason visible in the transcript. A successful Write outside config/ shows the PostToolUse formatter running and the file normalized to four-space, no-tabs output regardless of the write's initial indentation, which is the deterministic counterpart to the probabilistic CLAUDE.md rule.

Settings-based enforcement, hook-based enforcement, and Agent SDK embedding: Example 5: Agent SDK embedding with explicit settingSources selection

When Claude Code is embedded via the SDK, the caller chooses which filesystem tiers the agent sees. The default of no sources is the reason an SDK agent that ignores project CLAUDE.md and skills is not broken, it simply was never given those layers.

// File: src/agent/run-team-agent.ts  (TypeScript, Agent SDK)
// Purpose: spawn an SDK session that sees project team standards but not personal defaults,
//          keeps the Claude Code system prompt, and caps cost for the whole session.

import { query } from "@anthropic-ai/claude-agent-sdk";

type AgentMessage = unknown;

export async function runTeamAgent(prompt: string): Promise<void> {
  const messages: AgentMessage[] = [];

  for await (const msg of query({
    prompt,
    options: {
      // No filesystem settings are loaded by default; select explicitly.
      // "project" makes .claude/CLAUDE.md, .claude/rules/, and committed hooks visible.
      // "user" would add ~/.claude/CLAUDE.md and ~/.claude/rules/; omitted here to isolate team policy.
      // "local" would add .claude/settings.local.json; also omitted for reproducibility.
      settingSources: ["project"],

      // Keeps the standard Claude Code system prompt rather than a bare model prompt.
      systemPrompt: { preset: "claude_code" },

      // Evaluation order reminder: hooks run before deny rules, permission mode, and canUseTool
      // so a PreToolUse hook that returns permissionDecision "ask" still surfaces for approval
      // even when an allow rule would otherwise auto-approve.
      permissionMode: "default",

      // Dollar cap for the whole agentic session; hitting it reports error_max_budget_usd
      // rather than silently truncating.
      maxBudgetUsd: 25,

      // Keep model selection and provider routing in docs or settings, not hardcoded here.
      // Selecting a model string that is not available to the caller's API key fails the session
      // rather than silently falling back, which is the correct strict behavior for reproducibility.
    }
  })) {
    messages.push(msg);
    // handle message: assistant text, tool call, hook output, or cost footer
  }

  // Post-loop: verify what the agent actually saw via transcript
  // In automation, start with --bare or inspect the transcript rather than relying on
  // conversational memory, because the SDK session's context is scoped to this invocation.
}

// Companion variant: isolated personal workflow that must not see team policy
export async function runPersonalAgent(prompt: string): Promise<void> {
  for await (const msg of query({
    prompt,
    options: {
      settingSources: ["user"],
      systemPrompt: { preset: "claude_code" },
      permissionMode: "default",
      maxBudgetUsd: 10
    }
  })) {
    void msg;
  }
}

// Companion variant: fully reproducible automation that sees both but with team above user
export async function runFullAgent(prompt: string): Promise<void> {
  for await (const msg of query({
    prompt,
    options: {
      settingSources: ["user", "project"],
      systemPrompt: { preset: "claude_code" },
      permissionMode: "acceptEdits",
      maxBudgetUsd: 50
    }
  })) {
    void msg;
  }
}

What this proves. Selecting settingSources: ["project"] is how a team-scoped automation isolates project conventions, rules, and committed hooks from personal verbosity and shortcuts in ~/.claude/CLAUDE.md; the SDK's isolation is the code-level equivalent of claudeMdExcludes at the filesystem tier for human sessions. Adding "user" or "local" back widens the scope predictably, and omitting them keeps the session clean, which is the documented fix for "SDK agent ignores my CLAUDE.md". Using systemPrompt: { preset: "claude_code" } preserves the agent prompt that expects the hierarchy and permission shape described in the earlier sections, while cost routing via maxBudgetUsd caps spend and returns a typed error_max_budget_usd subtype on exhaustion. Provider routing comments reflect the CLAUDE_CODE_USE_BEDROCK and CLAUDE_CODE_USE_VERTEX environment variables without hardcoding them in the source, which keeps the snippet accurate regardless of cloud configuration.

Failure boundaries. Treating settingSources as additive rather than selective is the common mistake: passing ["project"] does not include user by default, so a personal rule that fixes formatting for a human will not appear for the embedded agent unless "user" is added. Conversely, an agent that loads project while the project settings.json still holds path-sensitive or interactive-only keys may behave differently than a human session because a committed permissions.allow that waits for workspace trust does not apply until the folder is trusted; the SDK session in a fresh clone may therefore prompt where a human's long-trusted session does not.

Observable output. Running the first variant against a prompt such as Summarize the repo conventions produces output grounded in the committed .claude/CLAUDE.md plus any .claude/rules/*.md that the gate permits, while the second variant's output is grounded in ~/.claude/CLAUDE.md and personal rules; diffing the two transcripts makes the scope choice visible, which is the SDK analog to diffing /context between two developers in human mode.

Build exercise material

Reproducible steps for the six sub-tasks on the reference page, with the observable proof after each. Perform these from a clean checkout so that missing commits are caught rather than papered over by prior state.

Build exercise material: 1. Create project-level .claude/CLAUDE.md with universal standards

Write CLAUDE.md at the repository root with at least three sections: naming conventions, error handling patterns, and a code review checklist, plus build, test, lint, and typecheck commands.

# File: ./CLAUDE.md (project tier, committed)

Commands

• Build: npm run build
• Test: npm test
• Lint: npm run lint
• Typecheck: npm run typecheck

Conventions

• Naming: camelCase for variables, PascalCase for types, file per component in src/components/
• Error handling: wrap with AppError carrying code and details; never throw raw Error from handlers
• Architecture: Zustand stores in src/stores/, never inline useState for shared state

Code Review Checklist

• Zod validation on every endpoint input
• No any without comment explaining why
• Tests in __tests__/ adjacent to source, describe and it blocks only

Proof. Run /context from the project root; under Memory files the list shows ./CLAUDE.md as loaded. Opening /memory and selecting the project file reveals the three sections plus commands. Commit the file and clone to a second directory; the clone's /context also shows the project file, confirming team distribution via git.

Code Review Checklist: 2. Create directory-level CLAUDE.md in packages/api

Create CLAUDE.md inside packages/api with REST endpoint naming and request and response schema requirements. Keep the root thin so only universal text lives at root.

# File: ./packages/api/CLAUDE.md (directory tier, committed, lazy) # Loading note: only when Claude reads a file inside packages/api/

API package

• REST endpoints: GET /api/v1/resources, POST /api/v1/resources, error.details array on failures
• Validation: authMiddleware plus Zod on every endpoint; schemas use camelCase
• Routes in packages/api/src/routes/, services in packages/api/src/services/

Proof. From the project root, run /context before touching any file in packages/api; the directory file does not yet appear. Read a file under packages/api, then run /context again; the list now shows both the project file and packages/api/CLAUDE.md as active. The reverse holds in packages/web: that sibling directory file is absent until a file there is read.

API package: 3. Create .claude/rules/testing.md with test-specific conventions

Place a rules file with at least three conventions in .claude/rules/testing.md. Without paths it loads unconditionally alongside .claude/CLAUDE.md; with paths it would load only for matching files.

# File: ./.claude/rules/testing.md

Testing conventions

• Test naming pattern: *.test.ts colocated in __tests__/ adjacent to source
• Assertion style: use Vitest expect plus toMatchInlineSnapshot for golden outputs
• Fixture usage: shared factory at tests/fixtures/factory.ts; do not duplicate factories per package

Proof. Run /context at project root; the rules file appears under Memory files alongside .claude/CLAUDE.md. If the file used --- frontmatter with paths: ["*/.test.ts"], it would appear only after reading a test file, which is the conditional variant used for the token-efficiency story.

Testing conventions: 4. Use @path import in project CLAUDE.md to reference shared standards

Add a bare @ line relative to .claude/ that points at a committed standards file, and ensure the target exists at the relative path.

# Append inside ./.claude/CLAUDE.md (project tier) # Shared standards imported eagerly at load @./standards/naming.md # Mention without importing: wrap in backticks Reference literal @./standards/not-imported.md in prose; it stays literal. # File: ./.claude/standards/naming.md (committed, shared single source of truth)

Naming conventions

• PascalCase for exported types and components, camelCase for variables and functions
• File names: kebab-case for routes, camelCase for utilities
• State stores: createFooStore pattern, one file per store in src/stores/

Proof. Run /context; the imported content appears inline as if its text lived inside .claude/CLAUDE.md and does not create a separate top-level entry. An import written inside backticks or inside a fenced code block does not produce an entry, confirming span safety. A missing target at the import path silently produces a gap rather than an error, which is visible as missing text rather than a diagnostic.

Naming conventions: 5. Run /context in different directories to verify the loaded set

From three working directories - repository root, packages/api, and packages/web - run /context and record the Memory files list.

Expect in root: managed policy if deployed, user ~/.claude/CLAUDE.md where present, project CLAUDE.md, .claude/CLAUDE.md, rules without paths, and the inlined import content as part of the project tier. Expect in packages/api after reading a file inside it: the same plus packages/api/CLAUDE.md and any packages/api/CLAUDE.local.md. Expect in packages/web after reading there: root plus that sibling's directory file instead, never both package files at once. This demonstrates that the diagnostic commands reveal the loaded set while the loading itself happens automatically by location, not by running the command.

Naming conventions: 6. Move one convention to user level ~/.claude/CLAUDE.md and confirm the scoping boundary

Cut one convention, for instance Indentation: 4 spaces, no tabs, run prettier on save, from the project file into ~/.claude/CLAUDE.md on your machine, then compare two sessions.

# File: ~/.claude/CLAUDE.md (user tier, personal, not committed)

Personal override for this machine

• Indentation: 4 spaces, no tabs; local formatter alias fmt is npx prettier --tab-width 4 --write

# Observer step from a clean second clone or teammate machine # Their /context shows project CLAUDE.md but not the user entry above # Your /context shows both

Proof. Your own /context continues to list the user file plus the project file, while a fresh clone or a second user session that does not share your home directory shows only the project file and never the personal entry. This is the exact boundary that the new-teammate scenario tests: team standards that live in ~/.claude/CLAUDE.md never reach a clone, so the fix is to move them back to project tier and commit. A companion verification for deterministic versus advisory is to place never run scp in ~/.claude/CLAUDE.md for the session that blocks, then check that a tool request is still probabilistically shaped rather than hard denied; the durable block requires permissions.deny with Bash(scp *) in settings.json at project or managed tier, not a memory line.

Mechanism reference: M1: The unified two-path equivalence

The Skills system collapses what were previously two separate concepts (slash commands and skills) into one registry. A flat file at .claude/commands/deploy.md and a directory at .claude/skills/deploy/SKILL.md both register a /deploy command that behaves identically at invocation time. The discovery layer scans both locations, normalizes them into the same internal command registry, and exposes them through the same slash-command picker. The body content of either form becomes the prompt instructions that Claude follows when the command runs.

The equivalence holds for the resulting behavior of the command, not for the feature set. The .claude/commands/ form is a strict subset: the same slash command appears, but it cannot carry a supporting-files directory, cannot be auto-discovered by intent matching, and loses the collision precedence that the directory form enjoys. A question that assumes the two paths differ in command behavior or availability is wrong; they do not, except through the extra capabilities the directory form attaches.

The merge exists because both surfaces answer the same need: a reusable, named block of instructions the agent executes on request. Treating them as one registry removes the cognitive overhead of remembering which folder a given workflow must live in. Backward compatibility is explicitly preserved so existing .claude/commands/ files keep working without migration.

Mechanism reference: M2: Skill is a directory with SKILL.md; command is a flat .md file

The two paths differ in on-disk shape. A command is a single flat Markdown file whose name minus extension is the command: .claude/commands/review.md becomes /review. A skill is a directory named after the command that contains a required entrypoint file called SKILL.md: .claude/skills/review/SKILL.md becomes /review. The presence of a directory plus an internal SKILL.md is what lets the skills form carry extra siblings such as a supporting-files folder.

The directory shape is the enabling constraint for the richer features. A flat file has no room for sibling assets; a directory does. By requiring a fixed entrypoint name SKILL.md, the loader always knows which file to read for the instructions, while any other files in the directory are treated as supporting material rather than instructions. The recurring literals are SKILL.md as the required entrypoint, the directory name matching the command (review), and the flat file .md extension. A proposed entrypoint name such as COMMAND.md or index.md is wrong; the fixed name is SKILL.md.

Mechanism reference: M3: A loose flat file dropped into .claude/skills/ creates no command

Because skills are directories with an internal SKILL.md, the loader only treats a directory entry under .claude/skills/ as a candidate skill. If a developer drops a flat Markdown file directly into that folder, for example .claude/skills/review.md, the scanner sees a file where it expected a directory and skips it. No /review command is registered. The file is effectively invisible to the command system.

The loader's contract is "directory under skills/ containing SKILL.md." A loose file violates the directory expectation, so it is not even inspected for frontmatter or content. This is the single most repeated trap in the tested material. The nearby opposite case is placing that same content at .claude/commands/review.md, where the flat form is exactly correct and produces /review. The boundary is purely the parent folder: flat file is valid in commands/, invalid in skills/. A directory .claude/skills/review/ without a SKILL.md also fails, but for a different reason (missing entrypoint) rather than wrong shape.

Mechanism reference: M4: .claude/skills/ is the canonical, feature-rich path; .claude/commands/ is a backward-compatible alias

Both folders yield commands, but the documentation designates .claude/skills/ as the canonical location and .claude/commands/ as an alias kept for compatibility. The canonical path is the one that gains new capabilities as the system evolves. Questions that ask for "the canonical location" point unambiguously at .claude/skills/; answers naming .claude/commands/ are marked wrong even though the command would still function.

Canonical status reflects where future features land. By steering new projects to .claude/skills/, the maintainers concentrate capability (supporting files, discovery, precedence) in one place while keeping the old path working so existing repositories are not broken. The alias is a courtesy, not a recommendation. The recurring trio is .claude/skills/ (canonical), .claude/commands/ (backward-compatible alias), and ~/.claude/skills/ (user-scoped personal).

Mechanism reference: M5: The skills path adds supporting files, automatic discovery, and name-collision precedence

The directory form unlocks three capabilities the flat alias lacks. First, supporting files: any sibling files next to SKILL.md are available to the skill as reference material, and scripts can resolve their location with the ${CLAUDE_SKILL_DIR} substitution so they work whether the skill is installed at the personal, project, or plugin level. Second, automatic discovery: the system reads a skill's description and can auto-load it when the user's intent matches, without an explicit slash invocation. Third, precedence: when a skill and a command share a name, the skill (directory form) wins. These are the reasons the canonical path is preferred.

Supporting files need a container, which only a directory provides. Auto-discovery needs structured metadata (the description) that the skills form is designed to carry. Precedence resolves ambiguity in favor of the richer form so that the feature-complete definition is the one that survives a name clash. The nearby opposite case is a command defined only in .claude/commands/: it gets none of the three capabilities. If two same-named definitions exist, one in each path, the skills form wins regardless of which was authored first.

Mechanism reference: M6: Project scope shares via version control; user scope is personal

Scope is decided by the parent directory. Anything inside the repository's .claude/ tree is project-scoped: committed to version control and propagated to every developer who clones or pulls. Anything inside the user-level ~/.claude/ tree is user-scoped: it lives on one machine, is never committed, and is invisible to teammates. This single axis, repository path versus home directory path, decides whether a command is a team asset or a personal one.

The distribution mechanism is version control. Files under the project root travel with the repo; files under the home directory do not. The system reads both trees and merges them, but only the project tree is shared. A command that "works for me but not my teammates" is the classic symptom of user-scope placement. The boundary is the leading path: .claude/ (relative to repo root) is shared; ~/.claude/ (home) is personal.

Mechanism reference: M7: The full frontmatter value space

Every SKILL.md begins with an optional YAML frontmatter block between --- markers. Most fields are optional; only description is recommended. The Agent Skills standard defines name, description, license, compatibility, metadata, and allowed-tools; every other field below is a Claude Code extension. The complete documented value space, with the value each field accepts, is:

• name (optional, defaults to the directory name). The display name in skill listings. The docs note .claude/commands/ files ignore this field because the command name comes from the file name.
• description (recommended). What the skill does and when to use it. Claude uses it to decide when to apply the skill automatically. Combined with when_to_use, the listing text is capped at 1,536 characters; lead with the key use case. Omitting it degrades the skill to explicit-only invocation.
• when_to_use (optional). Additional trigger phrases or example requests, appended to description for matching.
• argument-hint (optional). Autocomplete hint for expected arguments, e.g. [issue-number]. Surfaces a label in the / picker.
• arguments (optional). Named positional arguments for $name substitution in the skill body.
• disable-model-invocation (optional, default false). Set true to stop Claude from auto-invoking the skill; it then only runs when you explicitly type /name. This also removes the description from context entirely.
• user-invocable (optional, default true). Set false to hide the skill from the / menu; Claude can still auto-load it. Use for background knowledge. Note: setting both user-invocable: false and disable-model-invocation: true makes the skill unreachable.
• allowed-tools (optional). Tools Claude may use without a permission prompt while the skill is active. Accepts a space- or comma-separated string, or a YAML list, and supports per-tool argument patterns such as Bash(git add *). It does NOT restrict the pool.
• disallowed-tools (optional). Tools removed from Claude's available pool while the skill is active. Accepts the same string or list format. The restriction clears when you send your next message. The deny side complement to allowed-tools; it dominates allowed-tools for any overlapping tool.
• context (optional). Set to fork to run the skill in an isolated subagent context.
• agent (optional, default general-purpose). Which subagent type to use when context: fork is set; built-in values include Explore, Plan, general-purpose, or any custom subagent from .claude/agents/.
• background (optional, default true, requires v2.1.218+). Only applies with context: fork. Set false to wait for the forked subagent's result in the turn that invoked the skill.
• model (optional, default inherit). Model to use while the skill is active, for the rest of the current turn; accepts the same values as /model or inherit. The session model resumes after the skill completes.
• effort (optional). Effort level while active: low, medium, high, xhigh, max (availability depends on model).
• paths (optional). Glob patterns that limit automatic activation to matching files. Accepts a comma-separated string or YAML list. Ignored in a .claude/commands/ file.
• hooks (optional). Lifecycle hooks scoped to this skill's execution.
• shell (optional, default bash). Shell for !command dynamic-injection blocks: bash or powershell.
• mcp (optional). MCP servers scoped to the skill.
• license, compatibility, metadata, version (Agent Skills standard fields, indexed by the catalog rather than controlling Claude Code invocation).

A skill can be pure reference content (runs inline so Claude can apply conventions alongside the conversation) or a task (step-by-step instructions, usually invoked with /name or disable-model-invocation: true). Reference content with no task and context: fork produces no output, because the subagent receives guidelines but no actionable prompt.

Mechanism reference: M8: Pre-approving tools versus restricting them

The allowed-tools frontmatter field names tools the skill may use. In current behavior it functions as a pre-approval list: the listed tools run without a permission prompt while the skill is active, but the field does not structurally remove unlisted tools. Every other tool remains callable under the session's normal permission settings. The exam guide, however, presents allowed-tools as a restriction that removes other tools from the skill's reach, describing a read-only analysis skill configured with allowed-tools: [Read, Grep, Glob] as "cannot use Write or Bash."

The two framings converge on intent: a read-only skill should never write files or run shell commands. They diverge only when reasoning precisely about what a tool not on the list can still do. Under live behavior, a tool not named in allowed-tools is still callable subject to normal permissions; allowed-tools only suppresses the approval prompt for the named tools. The actual restriction is disallowed-tools, which removes the listed tools from Claude's available pool while the skill is active. disallowed-tools dominates allowed-tools for any tool named in both, because a removed tool cannot be approved.

The durable or org-wide boundary lives in permission deny rules (permissions.deny in settings, or /permissions), not in skill frontmatter. disallowed-tools is turn-scoped: the restriction clears when the user sends the next message, so it is a convenience for least privilege during one skill run, not a persistent lock. Skills that declare allowed-tools or hooks are treated as elevated-permission requests and require user approval before first use. A prompt instruction inside the skill body never removes a capability; only disallowed-tools plus permission settings enforce a boundary.

Mechanism reference: M9: context: fork isolates verbose skill output

The context: fork frontmatter field instructs the skill to run in an isolated subagent context. The skill's intermediate and verbose output, file trees, grep results, partial reasoning, and candidate evaluations, is produced inside that forked context and never enters the main conversation. Only the skill's returned summary reaches the main thread, preserving the main context window. The skill content becomes the prompt that drives the subagent and the forked subagent has no access to the conversation history.

Exploratory skills are noisy by nature; they enumerate, search, and weigh many options before concluding. Without isolation, all that noise consumes the finite context budget of the main conversation, degrading the quality of subsequent responses. Forking moves the noise to a side context whose budget does not compete with the main thread. The skill runs in the background by default (you keep working while it runs, and its result arrives when it completes); set background: false to wait in the invoking turn. In non-interactive mode, when background tasks are disabled, or when an earlier invocation is still running, Claude Code waits for the result regardless.

The nearby opposite case is a skill that is short and clean by design, where forking adds no value, or a skill whose whole point is to show the user the exploration rather than a summary; there, omitting context: fork is correct. A recurring distractor is to "fix context clutter" with allowed-tools or argument-hint; those change capability or input, not where output lands. Forking is the only frontmatter mechanism that relocates output.

Mechanism reference: M10: description drives the menu and automatic discovery

The description field serves two roles. In the slash-command menu it populates the tooltip or summary users see when browsing commands via /help or the / picker. In the skills system it is the text the discovery layer reads to decide whether a skill matches the user's intent and should be auto-invoked. A skill without a useful description only ever fires when the user types its name explicitly. The fallback when description is omitted is the first paragraph of the skill body, which the docs call a weaker summary than a hand-written one.

Discovery needs a searchable summary of what the skill does; description is that summary. The when_to_use field appends additional trigger phrases or example requests to widen matching. Descriptions are loaded into a context listing whose character budget scales at 1% of the model's context window; when the listing overflows, descriptions of the least-used skills are shortened or dropped, which can strip the keywords Claude needs to match. Run /doctor for an estimate of the listing's context cost. Write the description in the third person, lead with the key use case, and list the phrases users actually say.

Mechanism reference: M11: Invocation control with disable-model-invocation and user-invocable

Two fields control who may invoke a skill. disable-model-invocation: true removes the skill from automatic discovery so Claude never auto-loads it; the user must invoke it explicitly by name. It also removes the description from context entirely, which both prevents auto-loading and frees listing budget. user-invocable: false hides the skill from the / menu but lets Claude still auto-load it; use it for background knowledge that is not a meaningful command. The combination matters: disable-model-invocation: true plus user-invocable: false makes the skill unreachable (hidden from the menu and from automatic loading), so choose one or the other.

The exam repeatedly tests the "destructive workflow" framing: a deploy or data-migration skill should set disable-model-invocation: true so it only runs on explicit /name, never because Claude judged it relevant. The default (neither field set) means both the user and Claude can invoke it, the description stays in context, and the body loads on invocation.

Mechanism reference: M12: Path-scoped auto-loading with the paths field

The paths frontmatter field is a real, documented capability (resolving the forensics OPEN flag). It holds glob patterns that limit a skill's automatic activation to matching files. When you edit or operate on a file that matches a declared path pattern, the skill is loaded automatically. This is a file-driven variant of intent matching distinct from the description match. In a .claude/commands/ file, paths is ignored because command names come from file names, not frontmatter.

Path-scoped loading matters because some skills are relevant due to which file is open, not due to the wording of the request. A paths: ["/.test.ts"] declaration attaches the skill to test files so the expertise appears exactly when a matching file is in play. Glob correctness is a common pitfall: /.tsx and *.tsx are not the same pattern, because the latter matches only the working directory, not nested ones. For global conventions that apply to matching files automatically, .claude/rules/ is the better home than a skill; paths is for skill auto-loading, not for applying a rule to every matching file unconditionally.

Mechanism reference: M13: Model and effort overrides

The model field overrides the model used while the skill is active, for the rest of the current turn; it accepts the same values as /model or the literal inherit (which matches the main conversation's model and is the default). The session model resumes after the skill completes. The effort field sets the reasoning effort while active, with the value space low, medium, high, xhigh, max (availability depends on the model in use). Override these only when justified; most skills should inherit from the session. Both fields are skill-scoped conveniences, not session-level configuration, which lives in settings.json or the model: line of CLAUDE.md.

Mechanism reference: M14: Argument passing through $ARGUMENTS and named arguments

Inside a command or skill body, the token $ARGUMENTS is replaced at invocation time with whatever the user typed after the command name. This lets a single file accept variable input, a target file, a diff, a version string, without separate definitions per value. The placeholder is resolved by the command runner before the instructions are passed to the agent. When the body does not reference $ARGUMENTS, extra text is simply ignored. The arguments frontmatter field provides named positional arguments for $name substitution in the skill body, a richer alternative to the single $ARGUMENTS catch-all.

A second substitution mechanism is dynamic context injection: a line of the form !command is executed and replaced with its output before Claude sees the skill content, so instructions arrive grounded in live data. For example !git diff HEAD inlines the current working-tree diff. Injected commands never prompt for permission; if a permission check returns anything other than allow, the invocation aborts. A matching ask or deny rule still aborts regardless of allowed-tools. Scripts bundled with a skill resolve their own location with ${CLAUDE_SKILL_DIR} so they work at any install level.

Mechanism reference: M15: Name-collision precedence

Two distinct precedence rules apply. Across the two file shapes, when a skill (directory form) and a command (flat form) share a name, the skill takes precedence and becomes the active /command; the directory form is preferred because it is the canonical, feature-complete definition. Resolution is by form, not by timestamp, so "the later one wins" is wrong, and "both run concatenated" is wrong.

Across scopes, the current documentation resolves the forensics contradiction (Rule 25): "Across levels, enterprise overrides personal, and personal overrides project." So for a same-named skill living in both ~/.claude/skills/ and the project's .claude/skills/, the personal one wins locally. A skill at any of these levels also overrides a bundled skill with the same name (but not the bundled skill's aliases, so a project code-review skill does not run when you type the bundled alias /review). Plugin skills use a plugin-name:skill-name namespace and cannot collide.

Because the documented personal-over-project rule surprised earlier guidance that called same-name collisions "ambiguous," the defensible recommendation that satisfies either reading is the distinct-name pattern: give the personal variant a different name (e.g. /commit-mine mirroring a shared /commit) so the two definitions never collide. The forensics OPEN flag about a skills list in CLAUDE.md is not corroborated by current documentation; the real surfaces are the .claude/skills/ discovery plus skillOverrides in settings, not a frontmatter list inside CLAUDE.md.

Mechanism reference: M16: The boundary between always-loaded memory, conditionally loaded rules, and on-demand skills

Three layers carry guidance, and the exam tests the distinction directly. CLAUDE.md loads always, for every session, automatically, with no invocation step; it holds universal standards that must shape every action. .claude/rules/ files are conditionally loaded: path-scoped rules load as always-on context alongside matching files, combining the automaticity of CLAUDE.md with path specificity it lacks. Skills are on-demand: their description is always in context so Claude knows they exist, but the full body loads only when invoked, explicitly or by intent or path matching.

The decision test is: is this a universal standard that must apply to every action, or a task-specific procedure invoked occasionally? Universal standards (naming conventions, export styles, prohibited patterns) go in CLAUDE.md or .claude/rules/; task-specific procedures (code review checklists, analysis routines, brainstorming templates) go in skills. A convention that applies only to a specific file type or path belongs in path-scoped .claude/rules/, not in global CLAUDE.md and not in a skill. context: fork does not convert a CLAUDE.md procedure into on-demand behavior; forking only relocates a skill's output and never suppresses CLAUDE.md, which loads for every session regardless.

Mechanism reference: M17: Agent Skills standard fields versus Claude Code extensions

The SKILL.md format follows the open Agent Skills standard, which works across multiple AI tools, so a skill written for Claude Code can be portable to other compliant runtimes. The standard defines a small set of fields: name, description, license, compatibility, metadata, and allowed-tools. Everything else documented above (when_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, disallowed-tools, context, agent, background, model, effort, paths, hooks, shell, mcp) is a Claude Code extension. This split matters when a skill is meant to travel: a portable skill should rely only on the standard fields for its core behavior, while Claude Code-specific conveniences (isolation, invocation control, path scoping, model and effort overrides) enhance behavior only inside Claude Code.

The allowed-tools field is marked experimental in the standard and its support varies across implementations, but in Claude Code it is fully supported as a pre-approval mechanism. The metadata field carries arbitrary catalog metadata (author, tags, and so on) that is indexed by registries but does not control Claude Code invocation. A skill that depends on context: fork or paths to function correctly is, by definition, Claude Code-specific and will not gain those behaviors in a runtime that implements only the standard. Authors distributing a skill broadly should therefore keep the invocation-critical logic in the body and the standard fields, and treat Claude Code extensions as progressive enhancement.

Ownership map

This section assigns each guarantee in the Skills system to the layer that owns it, so a candidate can reason about where a behavior is enforced.

• File shape and discovery: owned by the Claude Code CLI loader. It enumerates .claude/skills/, .claude/commands/, ~/.claude/skills/, plugin skills/ directories, and .claude/skills/ up the parent chain to the repo root. The loader decides that a directory with SKILL.md is a skill and that a flat .md file in commands/ is a command.
• Frontmatter parsing: owned by the CLI. Malformed YAML loads the body with empty metadata, so /name still works but no description is available for matching; run with --debug to see the parse error, or claude plugin validate on the skills directory (v2.1.233+) to find unparseable files.
• Invocation decision (explicit vs automatic): the description is loaded into context by the CLI, but the intent match is performed by the model, which decides whether a skill applies to the current request. disable-model-invocation: true and user-invocable: false are CLI-enforced gates on that decision.
• Tool pre-approval and denial: allowed-tools and disallowed-tools are interpreted by the CLI's permission layer, but the baseline approval for every other tool is governed by the session's permission settings (permissions.allow/ask/deny), which is a config layer above the skill. A matching ask or deny rule in settings overrides allowed-tools.
• Subagent fork execution: owned by the CLI plus the agent runtime. context: fork plus agent selects the subagent type (model, tools, permissions); the forked subagent runs in the background by default and applies its edits outside session checkpoints, so /rewind does not undo them.
• Scope distribution: owned by the filesystem and version control. Placement under .claude/ vs ~/.claude/ decides sharing; git propagates project files on clone or pull. No registration step exists; placement and filename are sufficient.
• Durable security boundaries: owned by settings.json permission deny rules and managed settings, not by skill frontmatter. disallowed-tools is turn-scoped and clears on the next message.

Version and terminology currency

Several behaviors the exam guide describes as current are stable, but the field set has grown. The merge of custom commands into skills is current product behavior; the exam guide's v1.0 framing still separates "slash commands and skills" as if distinct systems, while the product has unified them. A candidate should answer using the unified model: both paths produce one /command.

Key version milestones that affect this task: context: fork arrived in v2.1.0; disallowed-tools shipped in v2.1.152 (2026-05-27), making the deny-side complement to allowed-tools real rather than the settings-only workaround older docs describe; skillOverrides gained the "off" state that also hides a skill from Remote Control and Agent SDK command lists in v2.1.199; /doctor became a bundled skill (still typable when disableBundledSkills is on) in v2.1.205; the background field for forked skills defaulted to background in v2.1.218; and claude plugin validate over a skills directory requires v2.1.233.

Terminology drift to watch: the canonical location is .claude/skills/ today, but many older examples and some community posts treat .claude/commands/ as primary. The exam guide's "three critical frontmatter options" (context: fork, allowed-tools, argument-hint) are the ones a question will key on, yet the live field list also includes description, when_to_use, disallowed-tools, disable-model-invocation, user-invocable, model, effort, paths, agent, background, hooks, shell, and arguments. A candidate should not treat description as optional even though the docs label it "recommended," because it is the discovery hook.

Official versus community divergence

Where community material contradicts Anthropic documentation, documentation wins. The divergences that matter for this task:

1. allowed-tools as restriction versus pre-approval. Community and exam-guide posts describe allowed-tools as restricting the skill to the listed tools ("cannot use Write or Bash"). The official documentation states it pre-approves listed tools without a prompt but every other tool remains callable. A candidate should answer "restriction" on the exam (that is the exam-correct framing) but understand the live pre-approval model and that the real boundary is disallowed-tools or permission deny rules.

1. Existence of disallowed-tools. Older documentation and some community posts say tool blocking must be done in settings only. As of v2.1.152, disallowed-tools is a documented frontmatter field that removes tools from the pool. The exam guide's "live field list" already includes it. Treat disallowed-tools as real and current.

1. A skills frontmatter list inside CLAUDE.md. One forensics item implies such a list enabling automatic skill use, with omission making a skill command-triggered only. This is not corroborated by current documentation; the real control surfaces are disable-model-invocation in the skill and skillOverrides in settings. Mark this not independently confirmed for any claim that CLAUDE.md carries a skill list.

1. Scope precedence for same-named skills. Earlier guidance called same-name collisions across scopes "ambiguous and unpredictable." Current documentation states personal overrides project (enterprise overrides personal). The safe, always-correct answer is the distinct-name pattern, which avoids the collision entirely regardless of which rule applies.

1. Documentation domains. Our lessons cite code.claude.com/docs/en/...; the verified URL list uses docs.claude.com/en/docs/.... Both resolve to the same current docs; the verified list is preferred for citations.

1. Added-directory skills loading. An --add-dir directory grants file access rather than configuration discovery, but skills and commands are an explicit exception: Claude Code loads .claude/skills/ and .claude/commands/ from each added directory automatically, alongside the project skills. This only applies when the project setting source is enabled (the default); in --safe-mode none of the three (skills, commands, subagents) load from added directories. By contrast, CLAUDE.md from an added directory is NOT loaded by default and requires CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1. A candidate should not assume that adding a directory exposes its skills only after an opt-in, the way it does for CLAUDE.md.

Beyond the task statement

The reference page omits several adjacent topics our lessons cover that a candidate may face on related questions. Each is listed with its slug and why it matters for Task 3.2.

• The CLAUDE.md hierarchy and golden rules (configuration). Task 3.2 tests the boundary between always-loaded CLAUDE.md and on-demand skills; the companion lesson explains the four-level CLAUDE.md chain (global, project, local, directory), the concatenation-not-override rule, the @path import syntax, and the six golden rules. Understanding that CLAUDE.md loads for every session is what makes the "skills load on demand" contrast stick.
• Path-scoped rules via .mdc (the .claude/rules/ system, claude-code-mdc-config). When a convention applies automatically but only to matching files, .claude/rules/ is the correct home, not a skill and not global CLAUDE.md. This is the middle layer between always-on and on-demand that the reference page hints at but does not name.
• Built-in slash command lifecycle (claude-code-slash-commands). Most built-in commands run fixed CLI logic; a smaller set are bundled skills (/code-review, /batch, /debug, /doctor) that give Claude instructions and let it orchestrate the work with its own tools. Knowing that custom commands are now defined via SKILL.md (not a separate descriptor) and that most session-management commands are interactive-only while user-invoked skills work in -p mode prevents scoping mistakes. The lesson maps commands across the session lifecycle: setup (/init, /memory, /mcp, /agents, /permissions), mid-task (/plan, /model, /effort, /context, /compact), parallel work (/agents, /tasks, /background, /batch), pre-ship (/diff, /code-review, /review, /security-review), between sessions (/clear, /resume, /branch), and recovery (/rewind, /doctor, /debug, /feedback). The /compact versus /clear distinction matters: /compact summarizes history to free context and keeps what matters, while /clear starts fresh on a new task and only reloads CLAUDE.md.

• Distribution beyond a single repo (claude-code-skill-management). For sharing wider than one repository, Claude Code uses a plugin and marketplace system managed with the /plugin command; a skill folder with a .claude-plugin/plugin.json manifest becomes a plugin that can bundle skills alongside agents, hooks, and MCP servers. There is no --install-skill CLI flag and no skill-specific package registry; distribution is via git for project-local skills or the plugin and marketplace system for wider sharing. Managed (organization-wide) deployment goes through managed settings.
• Skills as reusable instruction sets and the Skills-versus-Projects-versus-Custom-Instructions contrast (claude-101-skills). This beginner lesson frames Skills as saved, task-level workflows, distinct from always-on Custom Instructions and topic-level Projects. It reinforces the "skills are modular, shareable, task-specific" framing the exam expects, though it concerns the claude.ai product rather than Claude Code and is explicitly not part of the CCA-F exam weighting.
• Permission integration and distribution (claude-code-skill-management). Skills plug into the same permission system as everything else: deny the Skill tool to disable all skills, use Skill(name) or Skill(name *) rules to allow or deny specific skills, and distribute via git (project-local) or the plugin and /plugin system (wider sharing). The skillOverrides setting controls visibility from settings instead of editing a shared skill's frontmatter.
• Hooks as enforcement (configuration). For guarantees that must hold regardless of what a skill does, hooks (PreToolUse/PostToolUse) and permission deny rules are the durable layer; skill frontmatter disallowed-tools is a turn-scoped convenience by comparison.

Worked production examples

These five examples are connected: a team builds a /review checklist (project-shared), a personal /brainstorm analysis skill (isolated, read-only), a /deploy task skill (explicit only), a /create-migration command with arguments, and a single SKILL.md showing the full frontmatter value space. Each block proves a specific mechanism and notes its failure boundary. A sixth example extends the picture to monorepo and plugin scoping, where directory-qualified names and plugin namespaces resolve collisions that the simpler two-path model hides. Together they cover every file shape, every documented frontmatter field, argument passing, isolation, tool pre-approval, and the cross-level precedence rules the exam tests.

Worked production examples: Example 1: A skill directory with its entrypoint and supporting files

A project-wide code-review skill needs a checklist file it can reference. The directory shape is what enables that supporting file. The ${CLAUDE_SKILL_DIR} substitution lets the skill find its own assets at any install level.

.claude/skills/review/
  SKILL.md
  checklist.md

---
name: review
description: Run the team code review checklist against staged changes. Use when the user asks to review, requests a PR check, or types /review.
argument-hint: "<branch or 'staged' for uncommitted changes>"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(git diff *)
---

# review body

Read the checklist at `${CLAUDE_SKILL_DIR}/checklist.md` and work through each item:

1. Error handling: are new code paths covered?
2. Test coverage: do new functions have tests?
3. API naming: do exported names follow the project convention?
4. Secrets: are any hardcoded credentials present?

Apply the checklist to the diff supplied in `$ARGUMENTS`.

This proves the directory form carries a sibling checklist.md that a flat .claude/commands/review.md could not. Failure boundary: if you instead write .claude/skills/review.md (a loose flat file), no /review command is registered at all, because the loader expects a directory containing SKILL.md.

Worked production examples: Example 2: A flat command file

A simple team command that needs no supporting files can stay flat. The filename minus extension becomes the command name, and $ARGUMENTS carries runtime input.

# .claude/commands/standup.md
---
description: Summarize yesterday's and today's work from git history for a standup update
argument-hint: "<since-branch, e.g. main>"
---

Write a standup update from the git history since `$ARGUMENTS`:

- What I completed (merged or committed)
- What is in progress
- Blockers (failing tests, open reviews)

This proves that .claude/commands/standup.md creates /standup and that $ARGUMENTS receives the typed text after the command name. Failure boundary: the flat form cannot carry a supporting-files directory, cannot be auto-discovered by description matching in the same way the skills form can, and loses name-collision precedence to a same-named skill. Also, paths and name in this frontmatter are ignored.

Worked production examples: Example 3: Full frontmatter with every documented field

This single SKILL.md shows the complete documented value space in one place. In practice you would set only the fields a skill needs; the example is intentionally exhaustive for reference.

---
# SKILL.md frontmatter - full documented value space
name: security-audit            # optional; defaults to the directory name
description: >-                 # recommended; drives discovery and the menu tooltip
  Scan the codebase for vulnerability patterns and report findings.
  Use when the user asks for a security review, types /security-audit,
  or mentions OWASP, secrets, or injection.
when_to_use: >-                 # optional; appended to description for matching
  "security review, find secrets, check for SQL injection,
  audit dependencies for CVEs"
argument-hint: "<directory or module to scan, e.g. src/auth>"  # optional autocomplete hint
arguments:                      # optional named positional args for $name substitution
  - target
  - severity
disable-model-invocation: false # optional; true forces explicit /name only
user-invocable: true            # optional; false hides from / menu but Claude can auto-load
allowed-tools:                  # optional; pre-approves without prompt (does NOT restrict)
  - Read
  - Grep
  - Glob
  - Bash(git log *)
disallowed-tools:              # optional; removes tools from the pool while active
  - Write
  - Edit
context: fork                  # optional; run in an isolated subagent
agent: Explore                 # optional; subagent type when context: fork
background: false              # optional; only with context: fork; wait in the invoking turn
model: inherit                 # optional; override model for the skill turn
effort: high                   # optional; low|medium|high|xhigh|max
paths:                         # optional; glob patterns limiting auto-activation
  - "**/*.ts"
  - "**/*.tsx"
hooks:                         # optional; lifecycle hooks scoped to this skill
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: scripts/guard.sh
shell: bash                    # optional; shell for !`command` blocks
mcp:                           # optional; MCP servers scoped to the skill
  - security-scanner
license: MIT                   # Agent Skills standard field (catalog metadata)
compatibility: "claude-code>=2.1.0"
metadata:
  author: platform-team
---

# security-audit body

Scan `$target` for the patterns in `${CLAUDE_SKILL_DIR}/patterns.md` at `$severity` severity.

This proves every documented field and its shape. Failure boundary: name and paths are ignored inside a .claude/commands/ file; model and effort are skill-scoped and resume to the session after the skill; disallowed-tools clears on the next message, so it is not a durable boundary; setting both user-invocable: false and disable-model-invocation: true makes the skill unreachable.

Worked production examples: Example 4: Argument passing through named arguments and $ARGUMENTS

A migration generator shows three substitution styles: the $ARGUMENTS catch-all, named $name arguments from the arguments field, and a !command dynamic-injection block.

# .claude/commands/create-migration.md
---
description: Generate a database migration scaffold for the given change
argument-hint: "<migration name, e.g. add_user_roles>"
arguments:
  - name
---

Generate a migration scaffold for `$name`.

Latest committed tag: !`git describe --tags --abbrev=0`

Use the convention from our migration guide and write the file as
`migrations/$(date +%Y%m%d)_$name.sql`. The user typed: $ARGUMENTS

This proves that $name resolves from the arguments list, $ARGUMENTS carries the full typed text, and !git describe ... is replaced with live output before Claude sees the body. Failure boundary: if the body never references $ARGUMENTS, typed text is ignored rather than errored; dynamic-injection commands never prompt for permission, but a matching ask or deny permission rule still aborts the invocation regardless of allowed-tools.

Worked production examples: Example 5: A skill that pre-approves tools and runs isolated

A personal, verbose codebase-analysis skill that must be read-only and must not clutter the main conversation combines allowed-tools (pre-approval) with context: fork (isolation) and agent: Explore (read-only subagent).

---
name: brainstorm
description: >-
  Brainstorm design alternatives for a feature area and report the tradeoffs.
  Use when the user asks to explore options, weigh approaches, or types /brainstorm.
context: fork
agent: Explore
background: false
allowed-tools:
  - Read
  - Grep
  - Glob
argument-hint: "Provide a feature description or codebase area to explore"
---

# brainstorm body

Explore `$ARGUMENTS` and produce three candidate designs with tradeoffs.
Read widely; do not modify any file. Return a concise summary of the options.

This proves the canonical analysis-skill recipe: context: fork keeps the verbose file listings and excerpts out of the main conversation, agent: Explore supplies a read-only tool set, and allowed-tools: [Read, Grep, Glob] pre-approves those three so the exploration runs without permission prompts. The skill lives at ~/.claude/skills/brainstorm/SKILL.md so it is personal and never distributed via git. Failure boundary: allowed-tools does not make the skill read-only by itself; if you needed a hard guarantee that nothing is written, add disallowed-tools: [Write, Edit, Bash] (turn-scoped) or a permission deny rule (durable). Without context: fork, the exploration output lands in the main context and degrades later responses.

Worked production examples: Example 6: Monorepo and plugin scoping with directory-qualified names

A monorepo needs a deploy skill that is specific to one package and must not shadow the root deploy. The nested directory form gives a directory-qualified name automatically.

apps/web/.claude/skills/deploy/
  SKILL.md
.claude/skills/deploy/
  SKILL.md
my-plugin/skills/deploy/
  SKILL.md

# apps/web/.claude/skills/deploy/SKILL.md
---
name: deploy
description: Deploy the web app package to its preview environment. Use when changing files under apps/web.
context: fork
allowed-tools:
  - Bash(npm run deploy:web *)
---

# my-plugin/skills/deploy/SKILL.md  (plugin namespace)
---
name: my-plugin:deploy
description: Deploy via the shared platform plugin pipeline.
---

This proves three scoping facts at once. First, a nested skill under apps/web/.claude/skills/deploy/ becomes available when Claude works on files in that package and appears under the qualified name /apps/web:deploy; typing the unqualified /deploy still runs the project-root skill, and Claude Code also invokes the nested variant when its directory holds the files in play. Second, a plugin skill at my-plugin/skills/deploy/ is namespaced as /my-plugin:deploy and cannot collide with personal, project, or enterprise skills. Third, the precedence across levels is enterprise, then personal, then project, so a same-named personal deploy wins locally over the project one, while an enterprise deploy would override both. Failure boundary: a nested skill is not loaded at startup; it loads the first time Claude reads or edits a file inside that subdirectory and stays available for the rest of the session. A flat .claude/commands/deploy.md at the root loses name-collision precedence to the directory-form skill of the same name.

Build exercise material

These steps are verifiable: each has an observable outcome that proves the mechanism worked. They follow the reference page's build exercise but add the discovery and security checks the exam rewards.

Step 1. Create a project-scoped /review command in .claude/commands/review.md containing a team code review checklist, with frontmatter description and argument-hint. Observable outcome: a file exists at .claude/commands/review.md in the repository; running /review in Claude Code triggers the checklist; the command appears for any developer who clones the repository because the file is committed. Why: project-scoped commands are shared via git, so every developer gets them on clone.

Step 2. Create a personal /brainstorm skill at ~/.claude/skills/brainstorm/SKILL.md with context: fork in the frontmatter. Observable outcome: a SKILL.md file exists under the home directory; the skill is available only in your sessions; a colleague or fresh clone without your home directory config does not see /brainstorm. Why: user scope is personal and never version-controlled.

Step 3. Add allowed-tools to the brainstorm skill restricted to Read, Grep, and Glob. Observable outcome: the frontmatter now includes the list; under current behavior those three tools run without a permission prompt, while any other tool still follows normal permission settings. If the goal is a hard read-only guarantee, also add disallowed-tools: [Write, Edit, Bash], noting it clears on the next message. Why: allowed-tools pre-approves; disallowed-tools removes.

Step 4. Add argument-hint to the brainstorm skill: "Provide a feature description or codebase area to explore". Observable outcome: invoking /brainstorm without arguments shows the hint in the picker; supplying a target removes the prompt. Why: argument-hint surfaces the expected input at invocation time.

Step 5. Verify scoping boundaries. Observable outcome: /review works in any clone of the repository; /brainstorm works only in your session. A colleague or fresh clone without your home directory config does not see /brainstorm as an available command. Why: this confirms the project-versus-user axis the exam repeatedly tests.

Step 6. Invoke the brainstorm skill against a codebase area and confirm the verbose output does not appear in the main conversation. Observable outcome: the main conversation shows a concise summary; the file listings, code excerpts, and analysis notes are not visible in the main history. Subsequent responses remain high quality because the context window is not filled with exploration output. Why: context: fork runs the skill in an isolated subagent whose output returns only as a summary.

Step 7. Convert /review to the canonical skills form to gain discovery and precedence. Move the body to .claude/skills/review/SKILL.md, add a precise description, and confirm /review now auto-triggers when a request matches the description. Observable outcome: typing a request that matches the description auto-loads the skill; a same-named flat command (if it existed) would lose on collision. Why: the directory form adds automatic discovery and name-collision precedence.

Step 8. Check the description listing budget with /doctor. Observable outcome: /doctor reports the skill listing's context cost and flags if descriptions are being truncated. Trim description and when_to_use so the key use case leads, since each entry's combined text is capped at 1,536 characters. Why: a shortened or dropped description can strip the keywords Claude needs to match the skill.

Troubleshooting and anti-patterns

The official skills documentation lists concrete failure modes. Each maps to a mechanism above and to a distractor the exam reuses.

Skill not triggering. If Claude does not use a skill when expected: check that the description includes the keywords a user would naturally say; verify the skill appears when you ask "What skills are available?"; try rephrasing the request to match the description; and invoke it directly with /name if it is user-invocable. If the frontmatter YAML is malformed, Claude Code loads the body with empty metadata, so /name still works but there is no description to match against. Run with --debug to see the parse error, or run claude plugin validate on the skills directory (v2.1.233+) to find files whose frontmatter does not parse.

Skill triggers too often. If Claude uses a skill when you do not want it: make the description more specific, and add disable-model-invocation: true if you only ever want manual invocation. The fix for over-triggering is almost always in the description, not in turning off model invocation entirely (unless that is genuinely the intent).

Skill descriptions are cut short. Claude Code loads a listing of skill names and descriptions into context so the model knows what is available. The listing always contains every skill name, but when you have many skills the descriptions are shortened to fit the listing's character budget, which can strip the keywords the model needs. The budget scales at 1% of the model's context window and drops descriptions starting with the least-invoked skills. Run /doctor for an estimate, or raise the budget with skillListingBudgetFraction in settings or the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable. Free budget by setting low-priority entries to "name-only" in skillOverrides, or by trimming description and when_to_use (each entry's combined text is capped at 1,536 characters).

Skill not appearing after a move. A skill from .claude/commands/ or a nested .claude/skills/ in an added directory is not watched live, so after you add or edit such a file there, restart the session. Live change detection covers SKILL.md text under the main skills locations without a restart; creating a top-level skills directory that did not exist when the session started requires a restart.

Fabricated keys and surfaces. A stable class of wrong answers invents configuration keys or surfaces that do not exist: override: true (to make a personal skill supersede a project one), auto_run: false and hidden: true (to disable auto-invocation), a commands array in .claude/config.json, a commands entry in settings.json, and registering commands inside CLAUDE.md. Each names the right intent with a mechanism that does not exist. The real tools are positional scoping (paths), disable-model-invocation, and the documented frontmatter set.

Scope inversion. Placing a team command in user scope, or a personal command in the project, is attractive because the command "works for me," masking that it never distributes. The project-versus-user axis decides sharing; no registration step changes it.

Mislocated guidance. Putting a task workflow in CLAUDE.md, or a universal standard in a skill, exploits confusion between the always-loaded and on-demand layers. CLAUDE.md loads every session; a skill loads only when invoked. A standard buried in a never-invoked skill is skipped; a procedure forced into CLAUDE.md bloats every session.

Feature misattribution. Assigning context: fork the job of gating behavior, allowed-tools the job of routing output, or argument-hint the job of opening a child session. Each field is credited with a neighboring field's function; the exam reuses these as distractors.

Troubleshooting and anti-patterns: Nested and plugin-scoped skills

Skills also load from nested .claude/skills/ directories below the working directory. When Claude reads or edits a file in a subdirectory, skills from that subdirectory's .claude/skills/ become available, letting a monorepo package provide its own skills that apply when working on that package even if the session started at the repo root. If a nested skill shares a name with another skill, both stay available: the nested one appears under a directory-qualified name such as apps/web:deploy, and its description says which directory it applies to. Typing /deploy runs the project-root skill; typing /apps/web:deploy runs the nested variant explicitly. When you invoke the unqualified name, Claude Code appends the directory-qualified variants to its context with an instruction to also invoke any variant whose directory holds the files being worked on.

Plugin skills use a plugin-name:skill-name namespace, so they cannot conflict with personal, project, or enterprise skills. Adding a .claude-plugin/plugin.json to a skill folder loads it as a plugin named <name>@skills-dir, so it can bundle agents, hooks, and MCP servers alongside the skill. In a project's .claude/skills/, this requires accepting the workspace trust dialog first. Enterprise skills sit above personal and project skills; a deploy skill in both ~/.claude/skills/ and the project's .claude/skills/ resolves to the personal one locally, while an enterprise deploy would override both. The precedence order across levels is enterprise, then personal, then project.

A synced skill (enabled for a claude.ai account) whose name matches any other command is skipped so the other command runs; Claude Code reserves the names of its own built-in commands and bundled skills even when they are unavailable. Name comparison ignores case, spacing, and invisible characters, and treats compatibility forms such as fullwidth letters as their plain equivalents, so a synced Commit cannot load beside a local commit.