Reference

When you need the row, not the lesson

You already know what you are looking for. This page gives you the table, not the reasoning. The modules cover each surface when you want the why.

Precedence, surface by surface

Two definitions share a name. One wins, and which one depends on the surface. The rules do not agree with each other across surfaces.

Surface Winner when names collide
Skills enterprise > personal > project. Plugin skills are namespaced. A skill beats a .claude/commands/ file of the same name, and all of them beat a claude.ai-synced skill.
Subagents managed > --agents > project > user > plugin.
Settings managed > CLI > project-local > shared project > user. Lists merge rather than replace.
CLAUDE.md and rules Nothing overrides anything. Everything concatenates, root to cwd, with CLAUDE.local.md last within each directory, and user rules ahead of project rules.
Output styles Across nested project directories, the one closest to your cwd wins.
The pair that trips people

Skills and subagents invert against each other. For skills, your personal definition beats the project's. For subagents, the project's definition beats yours. That is the mistake most people make first: generalize from one surface to the other, and both load without complaint while your override silently fails.

The hook decision surface

A hook can say yes or no two ways: its exit code, and JSON on stdout. The exit codes are where people get surprised.

Signal What Claude Code does
Exit 0, no output Treated as no decision to report. The tool call continues through the normal permission flow. Silence never approves anything.
Exit 1 A non-blocking error. Without valid JSON on stdout, the action proceeds, even though 1 is the conventional Unix failure code.
Exit 2 For most events, the only exit code that blocks through the code alone. Enforce policy with exit 2.
WorktreeCreate The exception: any non-zero exit code aborts worktree creation.
PermissionRequest Exit 2 is not honored here and the permission flow proceeds unchanged. Deny through the decision object in JSON instead.
Caveat that changes the reading

Claude Code reads JSON from stdout at every exit code, not only at 0. Exit 1 is not inert when the hook also prints valid JSON: that decision still takes effect. Read the exit code and stdout together. Never read the exit code alone.

This table is the general rule. The exceptions are per event, and there are 33 of them. Every hook event has its own page: what each exit code does on that event, and which JSON fields it honours.

Hook timeouts

Defaults depend on handler type. Two events tighten them. One event drops the per-hook budget entirely and shares a single clock across every handler.

Handler or event Timeout Notes
command, http, mcp_tool 600s The default for the three most common handler types.
prompt 30s Default for prompt handlers.
agent 60s Default for agent handlers, which the docs flag as experimental.
UserPromptSubmit 30s Lowers the command, http and mcp_tool default.
MessageDisplay 10s Lowers the same three to the tightest per-event ceiling.
SessionEnd 1.5s, shared Not per hook. All SessionEnd hooks share the one budget.

Plugin directory layout

Only plugin.json lives inside .claude-plugin/. Everything else sits at the plugin root: the directory you pass to --plugin-dir, or the one that contains the manifest. That root is never ~/.claude/.

Path Holds
.claude-plugin/plugin.json The manifest. Optional, and name is its only required field.
skills/<name>/SKILL.md Skills. The folder name becomes the skill name.
commands/*.md Skills as flat markdown files. New plugins should use skills/.
agents/*.md Subagent definitions.
hooks/hooks.json Hook configuration. Same object shape as the one in your settings file.
.mcp.json MCP servers.
.lsp.json LSP (Language Server Protocol) servers, keyed by language.
output-styles/ Output styles.
themes/*.json Color themes. Experimental, and read-only once installed.
monitors/monitors.json Background monitors. Experimental, and interactive sessions only.
workflows/ Workflow scripts.
bin/ Executables added to the Bash tool's PATH while the plugin is enabled. You cannot include this directory in a plugin distributed through claude.ai organization settings.
settings.json at root Default settings applied when the plugin is enabled. Only agent and subagentStatusLine are supported, and unknown keys are ignored.

A one-skill plugin can put SKILL.md at the plugin root and skip skills/. The invocation name then comes from frontmatter name, not the folder name.

How fresh is this

Every fact on this page was verified against the live Claude Code docs on 2026-08-27. Much of what you see here needs a recent v2.1.x binary. Run claude --version before you trust a row, and check the live docs before you trust this page.

The version numbers here were not checked against a running binary. They are quoted from the documentation as it stood on that date.