ktg-plugin-marketplace/plugins/config-audit/knowledge/claude-code-capabilities.md

Claude Code Configuration Capabilities

Source: Official Claude Code documentation (code.claude.com/docs), 75 pages, verified 2026-04-03. Delta layer: research/03-claude-code-changes-config-surfaces.md (verified 2026-04-19) — sandbox/managed-only/prompt-cache surfaces added between v2.1.14 and v2.1.114.

2026-04 deltas (research/03)

Surface	Added in	Notes
sandbox.* (filesystem.allowRead/denyRead, network.deniedDomains/allowedDomains, enabled, failIfUnavailable, allowUnsandboxedCommands, enableWeakerNetworkIsolation)	~v2.1.77–v2.1.83	Sandbox configuration surface; managed-only variants exist for enterprise lockdown.
allowManagedHooksOnly, allowManagedMcpServersOnly, allowManagedPermissionRulesOnly, sandbox.filesystem.allowManagedReadPathsOnly, sandbox.network.allowManagedDomainsOnly	~v2.1.83–v2.1.84	Enterprise policy enforcement — block any non-managed hook/MCP/permission.
disableSkillShellExecution	v2.1.91	Disables !command shell expansion in skill bodies. Prompt-injection mitigation.
forceRemoteSettingsRefresh	v2.1.92	Fail-closed on managed-settings fetch failure.
showClearContextOnPlanAccept	v2.1.77	Plan-mode opt-in to clear context after plan accept.
showThinkingSummaries	v2.1.113 (default flipped to false)	Now opt-in.
tui, autoScrollEnabled	v2.1.111	Fullscreen terminal UI mode.
attribution.commit, attribution.pr	2026-04	Granular replacement for legacy includeCoAuthoredBy.
Env: ENABLE_PROMPT_CACHING_1H, FORCE_PROMPT_CACHING_5M	v2.1.108	Explicit prompt-cache TTL control.
Env: CLAUDE_CODE_DISABLE_1M_CONTEXT, CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING	2026-04	Behavior opt-outs for new defaults.

Official Configuration Guidance (Anthropic)

These principles are backed by official docs and verified community reports. Use them to ground recommendations.

Core Architecture

• CLAUDE.md is advisory, not enforced. It's injected as user-message context — Claude reads it and tries to follow it, but there is no guarantee of strict compliance. Compliance depends on specificity and file length.
• settings.json is the enforcement layer. Permissions, sandbox rules, and tool grants are enforced by the client regardless of what Claude decides to do.
• Hooks are deterministic. Unlike CLAUDE.md instructions which are advisory, hooks guarantee the action happens every time with zero exceptions.

Proven Impact

• CLAUDE.md over 200 lines degrades adherence. GitHub issue #22503 documents 300-line CLAUDE.md being "ignored 80+ times." Official docs now explicitly call this out: "important rules get lost in the noise."
• Path-scoped rules reduce context noise. Rules without paths: frontmatter load every session regardless of relevance. Scoped rules trigger only when Claude reads matching files.
• Conflicting instructions cause arbitrary behavior. When CLAUDE.md contains contradictions, Claude picks one arbitrarily. No priority mechanism resolves conflicts within a single CLAUDE.md.
• System prompt takes precedence over CLAUDE.md. Built-in system prompts (plan mode, agent launching) can override user-defined CLAUDE.md instructions.

When Each Feature Is Relevant

Feature	Relevant when...	Not needed when...
permissions.deny	Sensitive files exist (.env, secrets/)	Fully trusted solo dev environment
hooks	Repeatable automation or safety checks needed	Occasional manual workflows
path-scoped rules	Multiple languages, contexts, or large codebase	Single-language, small project
MCP servers (.mcp.json in git)	Team shares tool access	Solo project, personal tools only
custom agents	Specialized parallel workflows	Linear single-task coding
custom skills	Repeated multi-step workflows	One-off tasks
CLAUDE.local.md	Personal preferences differ from team	Solo developer
model overrides	Different tasks need different cost/capability	Default model works for all tasks
output styles	Team has specific formatting needs	Default style is sufficient
managed settings	Organization-wide policy enforcement	No org, solo developer

---

1. CLAUDE.md — Project Memory

What it is: Markdown file injected into every session as user-message context.

Scope	Location
Project (shared)	./CLAUDE.md or ./.claude/CLAUDE.md
Project (personal)	./CLAUDE.local.md (gitignored)
User (all projects)	~/.claude/CLAUDE.md
Org-managed (macOS)	/Library/Application Support/ClaudeCode/CLAUDE.md
Org-managed (Linux)	/etc/claude-code/CLAUDE.md

Key features: @import syntax inlines other files (max 5 hops); HTML comments <!-- --> stripped before injection (free maintainer notes); lazy loading of subdirectory files; claudeMdExcludes setting skips files by glob.

Fully utilizing: CLAUDE.md under 200 lines with clear headers; @import for large specs; CLAUDE.local.md for personal sandbox URLs; auto-memory enabled.

Common gaps: No CLAUDE.local.md; no @imports (one huge file); no user-level ~/.claude/CLAUDE.md; file over 200 lines reducing adherence.

---

2. CLAUDE.local.md — Personal Project Config

What it is: Companion to CLAUDE.md; appended after it; gitignored by default.

Config location: ./CLAUDE.local.md (project root)

Key fields/options: Free-form markdown, same syntax as CLAUDE.md. Ideal for personal API keys, sandbox URLs, local dev notes.

Fully utilizing: Personal overrides that shouldn't be committed; local tool paths; developer-specific preferences.

Common gaps: File never created; personal preferences mixed into shared CLAUDE.md.

---

3. ~/.claude/CLAUDE.md — User-Level Memory

What it is: Loaded for every project; lower precedence than project CLAUDE.md.

Config location: ~/.claude/CLAUDE.md

Key fields/options: Same markdown as project CLAUDE.md; @import supported.

Fully utilizing: Personal coding style, preferred tools, communication preferences applied everywhere.

Common gaps: File never created; duplicating same instructions in every project CLAUDE.md.

---

4. User Rules — ~/.claude/rules/

What it is: Personal rules files that load based on path patterns.

Config location: ~/.claude/rules/*.md

Key fields/options: YAML frontmatter paths: field with glob patterns — file loads only when Claude works on matching paths. Symlinks supported. Recursive discovery.

---
paths: ["src/**/*.ts"]
---
# TypeScript-specific rules here

Fully utilizing: Separate rule files per language, per domain, per tool; prevents irrelevant rules loading.

Common gaps: No ~/.claude/rules/ at all; everything in one CLAUDE.md that always loads.

---

5. Project Rules — .claude/rules/

What it is: Project-scoped rules with path-specific activation.

Config location: ./.claude/rules/*.md

Key fields/options: Same paths: frontmatter as user rules. Committed to git for team sharing.

Fully utilizing: TypeScript rules only load for .ts files; migration rules only load for db/** paths; test rules only load for **/*.test.*.

Common gaps: No .claude/rules/ directory; path-specific rules not used; all rules always load.

---

6. Org-Managed CLAUDE.md

What it is: Org-controlled instructions that cannot be overridden by users.

Config locations: /Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux), C:\Program Files\ClaudeCode\CLAUDE.md (Windows)

Fully utilizing: Org-wide security policies, required compliance notes, standard workflow rules.

Common gaps: Not used in org deployments; individual teams manage their own configs without coordination.

---

7. Project settings.json

What it is: Project-level settings committed to git; shared with team.

Config location: ./.claude/settings.json

Key fields: permissions.allow/deny/ask, env, hooks, model, effortLevel, attribution, enabledPlugins, enableAllProjectMcpServers

Fully utilizing: Team-agreed allow/deny rules; project env vars; attribution config; plugin list for team.

Common gaps: File doesn't exist; no permissions configured; no env block; missing $schema line.

---

8. User settings.json

What it is: Personal settings applied to all projects.

Config location: ~/.claude/settings.json

Key fields: model, effortLevel, outputStyle, language, statusLine, autoMemoryEnabled, autoMemoryDirectory, hooks, defaultShell, voiceEnabled, editorMode (in ~/.claude.json)

Fully utilizing: Personal model preference; default effort level; status line config; user-level hooks.

Common gaps: File never touched; relying on project settings only; no personal preferences set.

---

9. Local settings.json

What it is: Per-project personal overrides; gitignored.

Config location: ./.claude/settings.local.json

Key fields: Same as project settings.json; autoMode classifier (user/local settings only, not project).

Fully utilizing: Local dev API endpoints; personal permission overrides; local-only env vars.

Common gaps: Never created; personal overrides committed to shared settings.json.

---

10. Managed Settings

What it is: Org-controlled settings at highest precedence; cannot be overridden.

Config locations: managed-settings.json in system dirs; managed-settings.d/*.json (alphabetical merge)

Key fields (managed-only): allowedMcpServers, deniedMcpServers, allowManagedMcpServersOnly, allowManagedHooksOnly, allowManagedPermissionRulesOnly, allowedChannelPlugins, blockedMarketplaces, strictKnownMarketplaces, pluginTrustMessage

Fully utilizing: Lock MCP servers to org-approved list; enforce hook policies; org announcements via companyAnnouncements.

---

11. .mcp.json — Project MCP Config

What it is: Project-level MCP server configuration; committed to git.

Config location: ./.mcp.json

Key fields:

{
  "mcpServers": {
    "name": {
      "type": "stdio|http",
      "command": "...", "args": [...],
      "url": "...",
      "env": {}, "timeout": 30000, "trust": "workspace|trusted|untrusted"
    }
  }
}

Fully utilizing: Team-shared MCP servers (GitHub, Jira, DBs); MCP resources via @server:path; MCP prompts as slash commands; enableAllProjectMcpServers: true for zero-friction team onboarding.

Common gaps: No .mcp.json; MCP only configured in ~/.claude.json (not shared); trust levels not set; MCP resources not used.

---

12. ~/.claude.json — Global Config

What it is: Global non-settings preferences (separate file from settings.json).

Config location: ~/.claude.json

Key fields: mcpServers (user-scope MCP), autoConnectIde, autoInstallIdeExtension, editorMode ("normal"/"vim"), showTurnDuration, terminalProgressBarEnabled, teammateMode ("auto"/"in-process"/"tmux")

Fully utilizing: User-level MCP servers; vim mode enabled; IDE auto-connect.

Common gaps: MCP servers configured per-project instead of here when they should be global; editorMode never set.

---

13. managed-mcp.json — Org MCP Config

What it is: Org-managed MCP servers deployed to all users.

Config locations: System directories (same as managed-settings.json).

Key fields: Same mcpServers format as .mcp.json.

Fully utilizing: Org-wide MCP servers (internal APIs, knowledge bases) available everywhere.

Common gaps: Not deployed in org setups; teams configure MCP independently.

---

14. keybindings.json

What it is: Custom keyboard shortcuts for Claude Code UI.

Config location: ~/.claude/keybindings.json (open with /keybindings)

Key fields:

{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "bindings": [{"context": "Chat", "bindings": {"shift+enter": "chat:newline"}}]
}

Key actions: chat:submit, chat:newline, chat:externalEditor, chat:cycleMode, chat:thinkingToggle, chat:fastMode, voice:pushToTalk

Contexts: Global, Chat, Autocomplete, Settings, Confirmation, Tabs, Help, Transcript, HistorySearch, Task, ThemePicker, Attachments, Footer, MessageSelector, DiffDialog, ModelPicker, Select, Plugin

Fully utilizing: chat:newline bound to Shift+Enter; external editor for complex prompts; chord bindings for workflows.

Common gaps: File never created; chat:newline not bound (most common friction); vim mode not enabled for vim users.

---

15. Skills

What it is: Custom slash commands with full tool access.

Config locations: ~/.claude/skills/<name>/SKILL.md (user); .claude/skills/<name>/SKILL.md (project); .claude/commands/<name>.md (legacy)

Key frontmatter: name, description, argument-hint, allowed-tools, model, effort, context (fork), agent, hooks, paths, disable-model-invocation, user-invocable, shell

String substitutions: $ARGUMENTS, $ARGUMENTS[N], $N, ${CLAUDE_SESSION_ID}, ${CLAUDE_SKILL_DIR}

Dynamic context: !`command` executes shell command and inlines output.

Bundled skills: /batch, /claude-api, /debug, /loop, /simplify

Fully utilizing: Custom deploy/review workflows; disable-model-invocation: true on side-effect skills; context: fork for isolated research; !git diff HEAD`` for dynamic context; argument-hint for UX.

Common gaps: No custom skills; skills missing description (never auto-invoked); no !command`` dynamic context; bundled skills not used.

---

16. Agents (Subagents)

What it is: Named AI workers with scoped tools, models, and permissions.

Config locations: .claude/agents/<name>.md (project); ~/.claude/agents/<name>.md (user); plugin agents/; managed agents/

Key frontmatter: name, description, model, tools, disallowedTools, permissionMode, mcpServers, hooks, maxTurns, skills, initialPrompt, memory ("user"/"none"), effort, background, isolation ("worktree"), color

Built-in agents: Explore (read-only, Haiku), Plan (read-only), general-purpose (all tools), Claude Code Guide (Haiku)

Fully utilizing: Domain agents (security-reviewer, test-writer); restricted tool sets; Haiku for scanning, Opus for analysis; isolation: worktree for parallel work; memory: "user" for persistent learning; maxTurns guard.

Common gaps: No custom agents; no tool restrictions; no model optimization; no persistent memory; no worktree isolation; missing description (never auto-delegated).

---

17. Plugins

What it is: Namespaced bundles of skills + agents + hooks + MCP + tools.

Config location: .claude-plugin/plugin.json (manifest); enabled via enabledPlugins in settings.json

Key plugin.json fields: name, description, version, author, homepage, repository, license

Structure: skills/, agents/, hooks/hooks.json, .mcp.json, .lsp.json, bin/, settings.json

Enabling:

{"enabledPlugins": {"plugin-name@marketplace": true}}

Fully utilizing: Team plugins in shared marketplace; org tool bundles (MCP + skills + agents); LSP plugins for all languages; bin/ for custom CLI tools.

Common gaps: No plugins; .claude/ configs that should be plugins (not shareable); no LSP plugins; no team marketplace configured.

---

18. Output Styles

What it is: Named system prompt variants that change Claude's default behavior.

Config locations: ~/.claude/output-styles/*.md (user); .claude/output-styles/*.md (project); outputStyle key in settings.json

Built-in styles: Default (SE assistant), Explanatory (educational Insights blocks), Learning (collaborative, TODO(human) markers)

Custom format:

---
name: My Style
description: What this does
keep-coding-instructions: false
---
Instructions here...

Key distinction: Output styles replace the system prompt; CLAUDE.md adds a user message. Use output styles when you need stronger enforcement.

Fully utilizing: Custom style for documentation/analysis work; Explanatory for onboarding; project styles for specialized domains.

Common gaps: Never changed from Default; not knowing styles modify the system prompt (vs CLAUDE.md); no custom styles for specialized workflows.