claude-code-knowledge

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(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 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