open/ktg-plugin-marketplace

Fork 0

Kjell Tore Guttormsen f93d6abdae feat: initial open marketplace with llm-security, config-audit, ultraplan-local

2026-04-06 18:47:49 +02:00

15 KiB

Raw Blame History

Claude Code Configuration Capabilities

Source: Official Claude Code documentation (code.claude.com/docs), 75 pages, verified 2026-04-03.

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.

15 KiB Raw Blame History