Claude Code Knowledge Base

Component Types Overview

Type	Path	Invocation	Context Cost
Command	`.claude/commands/name.md`	`/name args`	Loaded on invocation
Agent	`.claude/agents/name.md`	`Task(subagent_type)`	Loaded into subagent context
Skill	`.claude/skills/name/SKILL.md`	Auto or `/name`	Loaded by description match
Hook	`.claude/settings.json`	Automatic on event	Zero (shell script)
Rules	`.claude/rules/*.md`	Auto-loaded always	Always in system prompt
Memory	`CLAUDE.md` (various levels)	Auto-loaded always	Always in system prompt

Commands

Path: .claude/commands/name.md Invocation: /name or /name arguments

---
description: Required. What the command does.
allowed-tools: Optional. Restrict tools (comma-separated).
model: Optional. opus/sonnet/haiku — or alias from settings.
argument-hint: Optional. Hint shown in autocomplete.
---

Command instructions here.

Use $ARGUMENTS for full argument string.
Use $ARGUMENTS[0], $ARGUMENTS[1] for positional args.
Use $1, $2 as shorthand for $ARGUMENTS[N].
Use ${CLAUDE_SESSION_ID} for session identifier.

Key rules:

Equivalent to .claude/skills/name/SKILL.md with user-invocable: true
Commands in subdirectories: .claude/commands/sub/name.md → /sub/name
Budget: SLASH_COMMAND_TOOL_CHAR_BUDGET (default 15000 chars)

Agents (Subagents)

Path: .claude/agents/name.md Invocation: Task tool with subagent_type="name"

---
name: agent-name            # required, matches filename without .md
description: Required. When to use. "PROACTIVELY" for auto-invoke.
tools: Optional. All by default. Comma-separated.
disallowedTools: Optional. Denylist complement to tools.
model: Optional. opus | sonnet | haiku | inherit
permissionMode: Optional. default | acceptEdits | plan | dontAsk | delegate | bypassPermissions
skills: Optional. Auto-load skills (comma-separated inline list).
hooks: Optional. Lifecycle hooks scoped to this agent.
memory: Optional. user | project | local — CLAUDE.md scope to load.
---

Agent system prompt here.

Permission modes:

default — ask user for each tool use
acceptEdits — auto-allow file edits, ask for others
plan — read-only exploration, no writes
dontAsk — run without asking, within sandbox
delegate — inherit parent permissions
bypassPermissions — skip all permission checks (dangerous)

Built-in subagent types: Explore, Plan, general-purpose, Bash, statusline-setup, claude-code-guide

Execution: foreground (blocks) or background (run_in_background: true). Resume via agent ID.

Scope priority: CLI --agents flag > project .claude/agents/ > user ~/.claude/agents/ > plugin agents

Skills

Path: .claude/skills/name/SKILL.md Invocation: /name (if user-invocable) or auto-loaded by agent/description match

---
name: skill-name            # lowercase, hyphens, max 64 chars
description: Required. What and when. Max 1024 chars.
allowed-tools: Optional. Restrict tools.
model: Optional. Model override when skill is active.
context: Optional. "fork" for isolated subagent execution.
agent: Optional. Which subagent type to run in (Explore, Plan, etc).
hooks: Optional. Lifecycle hooks scoped to this skill.
disable-model-invocation: true   # only user can invoke
user-invocable: false            # only Claude can invoke
---

Skill instructions here.

Use $ARGUMENTS, $ARGUMENTS[N], $N for user input.
Use !`command` for dynamic context injection (shell output inserted).

Folder structure:

skill-name/
├── SKILL.md        # required, max 500 lines
├── references/     # large content extracted here
├── scripts/        # executable code
└── assets/         # templates, resources

Invocation control matrix:

`disable-model-invocation`	`user-invocable`	Who can invoke
false (default)	true (default)	Both user and Claude
true	true	User only (via `/name`)
false	false	Claude only (auto-load)
true	false	Nobody (disabled)

Hooks

Path: .claude/settings.json (or agent/skill frontmatter hooks: field)

Hook Events (12)

Event	When	Matcher	Can Block
`PreToolUse`	Before tool execution	Tool name	Yes
`PostToolUse`	After tool execution	Tool name	No
`Notification`	On notification	—	No
`Stop`	Agent stops	—	No
`SubagentStop`	Subagent completes	Agent name	No
`PreCompact`	Before context compaction	—	No
`PostCompact`	After context compaction	—	No
`ToolError`	Tool execution error	Tool name	No
`PreUserInput`	Before user message processed	—	No
`PostUserInput`	After user message processed	—	No
`SessionStart`	Session begins	—	No
`SessionEnd`	Session ends	—	No

Hook Types (3)

{"type": "command", "command": "./script.sh"}
{"type": "prompt", "prompt": "Check if output is safe"}
{"type": "agent", "agent": "validator-agent"}

Exit Codes

Code	Behavior
0	Allow (continue)
2	Block (deny tool use, PreToolUse only)
Other	Log warning, continue

Hook Configuration

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {"type": "command", "command": "php -l $CLAUDE_FILE_PATH", "async": false}
        ]
      }
    ]
  }
}

Matcher patterns: exact name, | OR, regex. MCP tools: mcp__server__tool.

For comprehensive hooks reference see references/hooks-reference.md.

Memory & CLAUDE.md

Hierarchy (top to bottom, higher = higher priority)

Level	Location	Scope
Managed	System dirs (enterprise)	Organization-wide
User	`~/.claude/CLAUDE.md`	All user projects
User rules	`~/.claude/rules/*.md`	All user projects
Project	`CLAUDE.md` (project root)	This project
Project rules	`.claude/rules/*.md`	This project
Local	`CLAUDE.local.md` (project root, auto-gitignored)	This machine only
Nested	`src/CLAUDE.md`, `tests/CLAUDE.md`	Subdirectory context

Rules Files

.claude/rules/*.md — modular rules, always loaded into system prompt.

Path-specific rules via paths frontmatter:

---
paths:
  - src/Domain/**
  - src/Application/**
---
These rules apply only when working with files matching the glob patterns above.

Import Syntax

@path/to/file.md      # relative to current file
@/absolute/path.md    # absolute path
@~/user/path.md       # home directory

Import recursion limit: 5 hops max.

Commands

/memory — view and edit memory files
/init — generate initial CLAUDE.md from project analysis

For full reference see references/memory-and-rules.md.

Plugins

Path: .claude-plugin/plugin.json (plugin root)

{
  "name": "my-plugin",
  "description": "What this plugin provides",
  "version": "1.0.0",
  "author": "Name",
  "repository": "https://github.com/user/repo"
}

Plugin structure:

.claude-plugin/
├── plugin.json         # manifest (required)
├── commands/           # namespaced as /plugin:command
├── agents/             # available as subagent_type
├── skills/             # namespaced as /plugin:skill
├── hooks/hooks.json    # plugin-scoped hooks
├── .mcp.json           # MCP server config
└── .lsp.json           # LSP server config

Namespaced invocation: /plugin-name:skill-name

Installation sources: GitHub, Git URL, NPM, File path, Directory.

For full reference see references/plugins-reference.md.

Permissions

Rule Syntax

{
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": ["Bash(rm *)"],
    "ask": ["Write", "Edit"]
  }
}

Specifier patterns:

Pattern	Example	Matches
`Tool`	`Read`	All Read calls
`Tool(literal)`	`Bash(npm test)`	Exact command
`Tool(glob)`	`Read(src/**)`	Gitignore-style glob
`Tool(domain:)`	`WebFetch(domain:api.example.com)`	Domain filter
`mcp__server__tool`	`mcp__github__create_issue`	MCP tool
`Task(agent)`	`Task(acc-ddd-auditor)`	Specific subagent

Evaluation order: deny → ask → allow (deny wins over allow)

For full reference see references/settings-and-permissions.md.

MCP (Model Context Protocol)

Config: .mcp.json (project root) or in settings.json

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-name"],
      "env": {"API_KEY": "..."}
    }
  }
}

Tool naming: mcp__servername__toolname

Scope hierarchy: project .mcp.json > user settings > plugin .mcp.json

Permission: enableAllProjectMcpServers, allowedMcpServers, deniedMcpServers in settings.

Settings

Hierarchy: managed > CLI args > local > project > user

Level	Location
User	`~/.claude/settings.json`
Project	`.claude/settings.json`
Local	`.claude/settings.local.json` (gitignored)
Managed	Enterprise system dirs

Key settings areas: permissions, hooks, sandbox, MCP, model config, context management, attribution.

For full schema reference see references/settings-and-permissions.md.

Decision Framework

When to use which component type:

Goal	Best Component	Reason
Reusable saved prompt	Command	User invokes, low context cost
Complex analysis in isolation	Agent	Separate context window
Knowledge base / templates	Skill	Auto-loaded, shared across agents
Auto-trigger on events	Hook	Zero context cost, shell execution
Project-wide instructions	CLAUDE.md	Always in context
Path-specific rules	Rules (`.claude/rules/`)	Conditional loading
Distributable extension	Plugin	Namespaced, installable
External tool integration	MCP	Standardized protocol

Context Cost Awareness

Component	Context Budget Impact
CLAUDE.md + rules	Always loaded (~500 lines recommended max)
Skills (auto-loaded)	Loaded when description matches (~15K chars budget)
Skills (by agent)	Loaded into agent's context window
Agents	Separate context window (no parent cost)
Hooks (command type)	Zero context cost (shell execution)
Hooks (prompt/agent type)	Uses context for LLM evaluation
MCP tools	Tool descriptions always in context
Plugins	Components loaded per their type rules

Patterns

Parallel Agents

Run in parallel:
1. Task: researcher — study architecture
2. Task: security-scanner — check security
3. Task: performance-analyzer — check performance

Wait for all and combine results.

Progressive Disclosure

SKILL.md — brief instructions (max 500 lines)
references/ — details loaded when needed
scripts/ — execute without reading into context

Chained Agents

1. researcher → studies the task
2. planner → creates plan based on research
3. implementer → implements the plan
4. reviewer → reviews implementation

Agent Teams (Coordinator Pattern)

coordinator (opus) → delegates via Task tool
├── auditor-1 (sonnet, parallel)
├── auditor-2 (sonnet, parallel)
└── generator (sonnet, sequential after audit)

Coordinator uses TaskCreate/TaskUpdate for progress tracking.

Plugin Distribution

Package as .claude-plugin/ → publish to GitHub/NPM
Users install: enabledPlugins in settings
Skills namespaced: /plugin-name:skill-name

Validation Checklists

Commands

description is filled and specific
Path: .claude/commands/*.md
$ARGUMENTS used if argument-hint defined
model specified consciously (opus for complex, haiku for fast)
Instructions are clear and step-by-step

Agents

name and description are filled
name matches filename (without .md)
tools are minimally necessary
disallowedTools used if most tools needed except few
model chosen consciously
permissionMode appropriate for task
skills: is comma-separated inline list (not YAML array)
Coordinators have TaskCreate, TaskUpdate in tools
Coordinators have acc-task-progress-knowledge in skills

Skills

name is lowercase with hyphens, matches folder name
description < 1024 characters, explains "when to use"
SKILL.md < 500 lines
Large content extracted to references/
context: fork if needs isolated execution
Path: .claude/skills/name/SKILL.md

Hooks

JSON is valid
Event name is one of 12 valid events
matcher is correct tool/agent name or pattern
command script exists and is executable
Exit codes handled properly (0=allow, 2=block)
async: true only for non-blocking operations

Memory/Rules

CLAUDE.md < 500 lines (recommended)
.claude/rules/*.md for modular rules
CLAUDE.local.md in .gitignore
@imports resolve (max 5 hops)
paths frontmatter uses valid glob patterns

Settings

Valid JSON in settings.json
Permission rules follow deny → ask → allow order
settings.local.json is gitignored
Sandbox configured if auto-allowing Bash
MCP servers explicitly allowed/denied

Reference Files

Detailed documentation for specific areas:

Hooks Reference — all 12 events, 3 types, matchers, I/O, exit codes
Skills Advanced — context:fork, agent, hooks, model, invocation control
Subagents Advanced — memory, hooks, disallowedTools, background, resume
Memory and Rules — CLAUDE.md hierarchy, rules/, @imports, paths
Plugins Reference — plugin structure, manifest, marketplace, migration
Settings and Permissions — full schema, sandbox, permissions, env vars

acc-claude-code-knowledge

Claude Code Knowledge Base

Component Types Overview

Commands

Agents (Subagents)

Skills

Hooks

Hook Events (12)

Hook Types (3)

Exit Codes

Hook Configuration

Memory & CLAUDE.md

Hierarchy (top to bottom, higher = higher priority)

Rules Files

Import Syntax

Commands

Plugins

Permissions

Rule Syntax

MCP (Model Context Protocol)

Settings

Decision Framework

Context Cost Awareness

Patterns

Parallel Agents

Progressive Disclosure

Chained Agents

Agent Teams (Coordinator Pattern)

Plugin Distribution

Validation Checklists

Commands

Agents

Skills

Hooks

Memory/Rules

Settings

Reference Files