Reference Guide

Claude Code

The terminal-native coding agent — its layers, what each one is for, and the loop that uses them well.

← Back to Reference Hub

Best for: Long-horizon agent work, refactors, debugging autonomously, scripted runs.

  • Install: npm i -g @anthropic-ai/claude-code, then run "claude" in any directory
  • Reads CLAUDE.md at project root automatically for working memory
  • Full filesystem read/write and shell execution — no copy/paste needed
  • Models: Opus 4.7 (planning), Sonnet 4.6 (default), Haiku 4.5 (fast/cheap) — switchable per session
  • Context: 200K standard · 1M beta on supported surfaces · 500K on Enterprise
  • --dangerously-skip-permissions disables per-action approvals for fully autonomous runs

Limitations: No traditional inline tab-completion — designed for chat/agent interaction, not keystroke completion. Anthropic models only. Heavier resource use than completion-first tools like Copilot.

Primary surface

Best for: Non-trivial changes where you want alignment before code is written.

  • Toggle with Shift+Tab — explicit, visible mode in the prompt indicator
  • Read-only: file reads, greps, web search, MCP queries — no writes
  • Output is a structured plan with files-to-touch and a step-by-step approach
  • Use ExitPlanMode to commit to the plan; the agent then drops into execute mode
  • Best paired with subagents for parallel exploration before planning

Limitations: Plan Mode quality is bounded by what the agent can read. If context is scattered across services Claude can't reach, the plan will hand-wave that section. Add MCP servers for those data sources.

Recommended default

Best for: Patterns that recur (rule of three) where you want consistent execution.

  • Location: .claude/skills/<name>/SKILL.md (project) or ~/.claude/skills/ (user)
  • Description field is the trigger contract — write it the way the user would phrase the request
  • Body is normal Markdown — checklists, examples, gotchas, references to files in the same skill folder
  • Can ship supporting files (templates, scripts) alongside SKILL.md
  • Use the skill-creator skill (built-in) to scaffold new ones with good triggers

Limitations: Skills only fire if the description matches. Vague or generic descriptions ('does code review') will misfire — under-fire on real cases, over-fire on lookalikes. Test the trigger by paraphrasing what you'd actually ask.

Highest reuse ROI

Best for: Parallel exploration, specialized roles, tasks that would pollute main context.

  • Defined in .claude/agents/<name>.md with a description, tool allowlist, and system prompt
  • Invoked via the Task/Agent tool with a self-contained prompt
  • Each subagent gets its own context window — long agents stay focused
  • Parallel subagents work well for "explore four directories simultaneously" patterns
  • Common roles: code-reviewer, explorer (read-only search), planner, verifier

Limitations: Subagents have no memory of the parent conversation — prompts must be self-contained. Don't expect the subagent to 'know what you've tried' unless you tell it. Cost is real: each subagent run is its own model call.

Parallel-safe

Best for: Quality gates that must run regardless of what the agent decides to do.

  • Configured in .claude/settings.json under hooks{} — matcher + command + event
  • PreToolUse can block a tool call (non-zero exit cancels the action)
  • PostToolUse fires after — perfect for autoformatters, test runs, validators
  • SessionStart/SessionEnd good for logging, briefing notes, or memory sync
  • Hooks are deterministic — not AI. Use them when "AI decides" is the wrong control plane.

Limitations: Hooks run every time their matcher matches — over-broad matchers will slow every action to a crawl. Start narrow (specific tool + specific path), expand only when needed. Failures in PostToolUse don't roll back the action; use PreToolUse for blocking.

Quality gates

Best for: Frequent prompts (review-pr, ship-it, write-tests) that benefit from one-keystroke recall.

  • Location: .claude/commands/<name>.md (project) or ~/.claude/commands/ (user)
  • Body is the full prompt — Markdown formatting is fine
  • Arguments via {{ARG}} placeholders that the user fills at invocation time
  • Show in the prompt with /<name> — autocomplete by name
  • Often the cheapest first step before promoting to a skill (no trigger to design)

Limitations: Slash commands are explicit — you have to remember to type them. If you want the agent to apply the pattern automatically when it sees the right shape of work, write a skill instead.

Lowest setup cost

Best for: Letting the agent reach systems it doesn't natively know about.

  • Configure project-scoped servers in .mcp.json (committed to repo)
  • User-scoped servers in ~/.claude.json
  • Transport: stdio (local subprocess), HTTP, or SSE
  • Official Anthropic registry of trusted MCP servers — searchable from inside Claude Code
  • Tools appear with prefixed names: mcp__<server>__<tool>

Limitations: Every MCP server you add expands the agent's reach — and the prompt-injection surface. Treat MCP servers like dependencies: review code, prefer first-party or well-known sources, and use Hooks to gate writes that go through MCP.

Ecosystem hook

Best for: Sharing reusable Claude Code customizations across a team or the public marketplace.

  • One package, many primitives — no more "install these eight files in this order"
  • Versioned and pinnable — teams stay on a known-good build
  • Marketplaces aggregate plugins, public or private
  • Inspect with /plugin list; manage with /plugin enable/disable
  • Build your own with the plugin scaffolding tools (a single-sentence brief is often enough)

Limitations: A plugin's skills and hooks run with the same trust as anything else in .claude/. Audit before installing third-party plugins, especially ones with hooks or MCP servers that write or call external services.

Distribution unit

Skills, slash commands, and subagents are not the same thing

A **slash command** is an explicit prompt expansion — you type `/name` and the file contents become the prompt. A **skill** is a workflow with a trigger — the agent loads it automatically when the description matches what you (or the agent) said. A **subagent** is a whole separate agent invocation with its own context window — used to delegate work the main session shouldn't carry. The naming sounds adjacent; the use cases barely overlap. Pick by the question "should this fire automatically?" — if yes, skill; if no but you want the shortcut, slash command; if the work is heavy enough to deserve its own context, subagent.