Claude Code Knowledge

Claude Code Knowledge Base

Component Types Overview

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 | plan | acceptEdits | auto | dontAsk | bypassPermissions | delegate
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:

Hooks

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

Hook Events

Verified against Claude Code 2.1.233 with claude plugin validate — an unknown event name is rejected as hooks.<Name>: Invalid key in record, so this list is checked, not remembered.

Blocking is done with exit code 2 (exit 1 is a non-blocking error). PreToolUse may also return JSON with permissionDecision: "deny". See references/hooks-reference.md for per-event payloads and blocking semantics.

Never generate these — they do not exist. A hook registered under an invented name silently never fires, and claude plugin validate rejects the plugin with Invalid key in record:

Hook Types (3)

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

Exit Codes

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)

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. Only the manifests live inside .claude-plugin/; every component directory sits at the plugin root, next to it — not inside it:

my-plugin/                  # plugin root
├── .claude-plugin/
│   ├── plugin.json         # manifest (required)
│   └── marketplace.json    # only when this repo is also a marketplace
├── commands/               # namespaced as /plugin:command
├── agents/                 # available as subagent_type "plugin:agent"
├── skills/<name>/SKILL.md  # namespaced as /plugin:skill
├── hooks/hooks.json        # plugin-scoped hooks
├── .mcp.json               # MCP servers (or an "mcpServers" key in plugin.json)
└── .lsp.json               # LSP server config

Putting commands/ or skills/ inside .claude-plugin/ makes them invisible — the loader looks for them at the plugin root.

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:

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

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:

Context Cost Awareness

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