The complete guide to structuring Claude Code's extension stack — from global cross-project knowledge to project-specific automation, with the full tools annexure.
Watch the walkthrough
Claude Code reads memory files before every session. More specific files override broader ones. Understanding this hierarchy is the foundation of everything.
~/.claude/projects/<hash>/memory/ — facts it learns during sessions like "user prefers verbose logging" or "this project uses pnpm". Use /memory to view and edit. Auto memory is gitignored.
Skills are directories with a SKILL.md file that teach Claude how to handle specific tasks. Unlike CLAUDE.md facts, skills are procedural — they teach Claude what to do, step by step.
A directory with a SKILL.md file containing YAML frontmatter (how it runs) and markdown content (what Claude does). Claude loads the file on-demand when your intent matches the skill's description — zero context window cost when idle.
Skills can be invoked by Claude automatically (when it detects relevance), by you via slash command (e.g., /code-review), or by another agent. The frontmatter invocation field controls this.
Skills can include reference .md files, Python scripts, shell scripts, templates. Claude only loads what it needs for the specific task — a skill with 20 reference files only loads the relevant 2 for your request. Efficient token usage.
Claude Code skills follow the Agent Skills open standard — compatible with Cursor, Gemini CLI, Windsurf, Aider, GitHub Copilot, Zed, Warp, RooCode, and more. Build once, run everywhere in your AI toolchain.
| Field | Type | Description | Example |
|---|---|---|---|
| name | string | Creates the /name slash command | code-review |
| description | string | Claude uses this for auto-matching your intent | Review code for quality… |
| allowed-tools | string | Comma-separated tools this skill can use without asking | Read, Write, Bash(git*) |
| invocation | enum | auto | slash | agent | auto |
| version | string | Semantic version for the skill | 1.2.0 |
| model | string | Override model for this skill (default: inherits) | claude-haiku-4-5 |
| context | string | Use fork to run in isolated agent context | fork |
| agent | string | Which subagent type runs this skill | Explore |
| license | string | License reference (points to LICENSE.txt in skill dir) | MIT |
Available across all your projects. Good for personal coding preferences, your favorite review checklists, documentation templates you always use. Stored in your home directory.
Available only in this repository. Good for project-specific workflows: deploy scripts, seed data commands, project-specific test patterns. Committed to git — team shares them.
/simplify (3-agent parallel code review), /batch (large-scale parallel changes with git worktrees), /claude-api (auto-activates when Anthropic SDK is imported).
Agents are separate Claude instances with their own context window, tool permissions, and model. Use agents when you need parallel execution, isolated memory, or a true specialist that should not be polluted with your main conversation context.
Uses Claude Haiku (fast, cheap). Fires automatically on "where is X?" or "find all files that…". Read-only tools. Perfect for codebase navigation.
Inherits your current model. Used in plan mode for research before implementation. Analyzes requirements, produces implementation plans. Read-only.
Full tool access. Used for complex delegated tasks. Can spawn further sub-agents. Your main workhorse for autonomous multi-step work.
| Field | Purpose |
|---|---|
| name | Agent identifier & command |
| description | When Claude auto-invokes it |
| tools | Allowed tools (principle of least privilege) |
| model | Override model per agent |
| memory | project | none | user |
| mcpServers | MCP servers this agent can use |
Available in all projects. General-purpose specialists you always want — researcher, security reviewer, documentation writer.
Project-specific specialists with deep knowledge of your repo. Committed to git so your team shares them.
Everything in one view — global vs. project-level, what's committed vs. gitignored, what's shared vs. personal.
The mental model is simple: Memory = what Claude knows, Skills = what Claude does, Agents = who Claude delegates to.
| You want to… | Use | Location |
|---|---|---|
| Persist facts across all sessions | CLAUDE.md | Global |
| Share rules across all your projects | ~/.claude/CLAUDE.md or rules/ | Global |
| Teach Claude a repeatable workflow | Skill | Either |
| Skill available everywhere | ~/.claude/skills/ | Global |
| Skill scoped to one repo | .claude/skills/ | Project |
| Run parallel or isolated tasks | Agent | Either |
| Share an agent across projects | ~/.claude/agents/ | Global |
| Agent only in one project | .claude/agents/ | Project |
| Personal overrides, not in git | CLAUDE.local.md | Local |
| Path-specific rules (monorepo) | .claude/rules/*.md + paths | Project |
Every tool available in Claude Code as of 2025 — built-in tools, permission scoping, and the complete allowed-tools syntax.
| Tool | Category | Description | Key Parameters |
|---|---|---|---|
| Read | File I/O | Read any file — text, images (visual), PDFs (page selection), Jupyter notebooks. Returns content with line numbers. Supports pagination for large files. | file_path, start_line?, end_line? |
| Write | File I/O | Create or overwrite a file entirely. Use for new files or complete rewrites. Sends all file content — use Edit for small targeted changes to avoid token waste. | file_path, content |
| Edit | File I/O | Targeted find-and-replace within a file. Must Read the file first. Fails if the target string isn't found (safety guarantee). Far more token-efficient than Write for small changes. | file_path, old_str, new_str, replace_all? |
| Bash | Execution | Execute shell commands in a persistent bash session. State persists across calls (env vars, working directory). Supports background processes. Git, npm, docker, pytest, any CLI tool. | command, description, timeout?, restart? |
| Glob | Search | Fast file pattern matching. Returns list of matching paths sorted by modification time. Use for finding files before reading. More efficient than Bash find for file discovery. | pattern, path? |
| Grep | Search | Regex search across file contents. Returns matching lines with context. Supports recursive search and file type filtering. Faster than Bash grep for codebase search. | pattern, path?, recursive?, include? |
| WebFetch | Web | Fetch and read web pages. Returns text content. Useful for reading documentation, GitHub files, API references. Used by research agents and the /claude-api skill. | url, prompt? |
| WebSearch | Web | Search the web and return results with snippets. Used by researcher agents. Combine with WebFetch to get full article content after finding relevant URLs. | query |
| NotebookEdit | File I/O | Edit Jupyter notebook cells directly — add, update, or delete cells. Understands notebook structure: code cells, markdown cells, outputs. Works with .ipynb files natively. | notebook_path, cell_index, new_source, cell_type? |
| TodoWrite | Planning | Manage the active task list. Create, update, and mark tasks as complete. Claude uses this internally to track multi-step work. Visible via /todos command. Persists through the session. | todos: [{id, content, status, priority}] |
| BashOutput | Execution | Retrieve output from a running or completed background bash shell. Use when you launched a long-running process with Bash and need to check its output without blocking. | shell_id |
| KillShell | Execution | Terminate a running background bash shell. Use to clean up long-running processes (dev servers, watchers) that are no longer needed. | shell_id |
| SlashCommand | Meta | Execute slash commands within the conversation programmatically. Allows agents to trigger other skills and commands. Used for meta-orchestration patterns. | command, args? |
| ExitPlanMode | Meta | Exit plan mode and transition to execution mode. Used by the Plan agent after producing an implementation plan. Signals Claude is ready to start making changes. | (none) |
| Tool | Category | Description |
|---|---|---|
| Task | Agent | Launch a specialized sub-agent for complex, multi-step tasks. The agent gets its own context window and tool access. Specify subagent_type: general-purpose, Explore, Plan, or any custom agent name from your .claude/agents/. |
| Skill (meta-tool) | Skills | The meta-tool managing all skills. Appears in Claude's tools array alongside Read, Write, Bash. Its description contains the formatted list of all available skills. Claude uses it to invoke the right skill by command name. |
| mcp__* | MCP | Tools dynamically loaded from connected MCP servers. Each server exposes its own set of tools prefixed with the server name. Examples: mcp__github__create_pr, mcp__postgres__query, mcp__stripe__create_payment. |
| Syntax | Meaning |
|---|---|
| ToolName | Permit all uses of this tool |
| ToolName(*) | Permit any argument (explicit wildcard) |
| ToolName(filter) | Permit only matching calls |
| Write(src/**) | Write only inside src/ (glob) |
| Bash(git *) | Any git subcommand |
| Bash(git commit:*) | git commit with any message |
| Read(.env*) | Deny reading .env files (in deny list) |
.claude/settings.local.json for personal local overrides (auto-gitignored).
MCP (Model Context Protocol) servers extend Claude Code with tools from external services. Each server exposes tools that appear in Claude's tool list prefixed by the server name.
| MCP Server | Type | Key Tools Exposed | Install Command |
|---|---|---|---|
| GitHub | Official | create_pr, list_issues, create_issue, search_code, get_file_contents, push_files | npx @modelcontextprotocol/server-github |
| PostgreSQL | Official | query, list_tables, describe_table, execute_ddl | npx @modelcontextprotocol/server-postgres |
| Filesystem | Official | read_file, write_file, list_directory, search_files, move_file, create_directory | npx @modelcontextprotocol/server-filesystem |
| Brave Search | Official | brave_web_search, brave_local_search | npx @modelcontextprotocol/server-brave-search |
| Slack | Official | post_message, list_channels, get_channel_history, add_reaction | npx @modelcontextprotocol/server-slack |
| Puppeteer | Official | navigate, screenshot, click, fill_form, evaluate_js, pdf_export | npx @modelcontextprotocol/server-puppeteer |
| Memory (KV) | Official | store_memory, retrieve_memory, search_memories, list_memories | npx @modelcontextprotocol/server-memory |
| Google Drive | Community | list_files, read_file, create_file, update_file, share_file | npx @modelcontextprotocol/server-gdrive |
| Stripe | Community | create_customer, create_payment, list_subscriptions, create_refund | mcp.stripe.com/sse |
| Asana | Community | create_task, list_tasks, update_task, create_project, assign_task | mcp.asana.com/sse |
| Perplexity | Community | search (deep web research with citations) | via Perplexity API |
| Firecrawl | Community | scrape, crawl_site, search, extract (structured data from web) | via Firecrawl API |
| Jira | Community | create_issue, list_issues, update_issue, add_comment, transition_issue | via Atlassian MCP |
| Linear | Community | create_issue, list_issues, update_issue, list_projects, list_cycles | via Linear MCP |
| Sentry | Community | list_issues, get_issue_details, generate_agents_md, create_fix | via Sentry MCP |
claude mcp add --transport stdio github npx -y @modelcontextprotocol/server-github — stores config in .claude/mcp.json. Use --transport http for URL-based servers.