Skills
Teach Claude a routine once.
A SKILL.md with steps, scripts, and reference files. Runs when you call it, or when Claude decides it's relevant.
Reach for it when You've typed the same instructions three times.
/deploy stagingClaude Code Cheat Sheet
The commands you'll use every day, plus the five ways to extend Claude Code and when to reach for each. Every claim links to the official docs.
Checked against the official Claude Code docs on October 18, 2026.
The Big Picture
Five ways to extend Claude Code, and the exact moment in a session where each one kicks in.
Where each one plugs in
- Session starts
- You prompt
- Claude works
- Tool call
- Claude stops
Subagents
Hand off the messy side quest.
A helper with its own context window, tools, and model. It does the digging and hands back a summary.
Reach for it when A task would bury your conversation in logs or search results.
@test-runner run the suite, tell me what brokeHooks
Rules that run every single time.
Your script fires on a lifecycle event: before a tool call, after an edit, when Claude stops. Exit code 2 blocks.
Reach for it when It has to happen whether or not Claude remembers.
PreToolUse → block git push --forceMCP Servers
Plug Claude into everything else.
Servers that add new tools: GitHub, Sentry, Notion, your database, a real browser.
Reach for it when Claude needs to reach a system outside your repo.
claude mcp add --transport http sentry https://mcp.sentry.dev/mcpPlugins
Ship the whole setup as one install.
Skills, agents, hooks, and MCP servers bundled together, versioned, and installable from a marketplace.
Reach for it when You want your team's setup in every repo, or someone else's in yours.
/plugin install commit-commands@claude-plugins-officialLooking for custom slash commands? They've been merged into skills. Old .claude/commands/ files still work. docs ↗
Decision Guide
Pick what you're trying to do. The wizard tells you which mechanism to reach for.
Reach for
Skills
Create .claude/skills/<name>/SKILL.md and commit it. Everyone on the repo gets /name.
Reach for
Subagents
Define one in .claude/agents/. It works in its own context window and hands back only a summary.
Reach for
Hooks
Add a PreToolUse hook in .claude/settings.json. Exit code 2 blocks the call and tells Claude why.
Reach for
MCP Servers
Run claude mcp add, or commit a .mcp.json at the project root so the whole team gets it.
Reach for
Hooks, not CLAUDE.md
The docs put it plainly: an instruction in CLAUDE.md or a skill is a request, a PreToolUse hook that blocks the action is enforcement.
Reach for
Skills + CLAUDE.md
Put always-on conventions in CLAUDE.md, and longer playbooks in skills that only load when relevant.
Reach for
Plugins
Install one from a marketplace. Anthropic's official marketplace is added the first time you start Claude Code.
Reach for
Plugins
Package your skills, agents, hooks, and MCP config as a plugin and publish it through your own marketplace.
Daily Commands
Most of your time in Claude Code isn't spent writing skills or hooks. It's spent steering a session. These are the commands and keys that do the most work, grouped by what you're trying to do.
Manage context
/contextSee what's filling the window, as a colored grid/compact [focus]Summarize so far to free up room/clearStart fresh. The old chat stays in /resume/btw <question>Side question that doesn't join the chat
Undo and go back
/rewindRoll back the chat, the code, or both/resumePick up a previous session
Set up
/initGenerate a starter CLAUDE.md/memoryEdit CLAUDE.md, toggle auto memory/permissionsAllow, ask, and deny rules/modelSwitch model. Arrows change effort
Check your work
/reviewReview the diff, a branch, or a PR/doctorDiagnose and fix your setup/usageCost and plan limits
See what loaded
/skillsSkills, with token cost per skill/hooksHooks that are actually configured/mcpServer status and OAuth/pluginInstalled plugins and marketplaces
Keys worth memorizing
- ShiftTab Cycle permission modes (default, acceptEdits, plan…)
- Esc Stop Claude mid-turn. Work so far is kept
- EscEsc Empty prompt: open the rewind menu
- @ Mention a file, with autocomplete
- ! Run a shell command yourself, output joins the chat
- CtrlB Send a running command or agent to the background
- CtrlO Transcript viewer with every tool call
- CtrlG Write the prompt in your editor
- CtrlV Paste an image (Cmd+V in iTerm2)
- ⌥P Switch model without losing your prompt (Alt+P on Windows/Linux)
Gotchas: 3 things that bite people
- /compact keeps going with a summary, /clear throws the context away. Between unrelated tasks, /clear is usually the better call, because leftover context from the last task is noise for the next one. docs ↗
- /rewind only restores files Claude edited with its own edit tools. Changes made by Bash commands (rm, mv, a codegen script) aren't checkpointed. Git is still your real undo. docs ↗
- /agents no longer opens a manager (it did through v2.1.197). Ask Claude to create a subagent, or edit .claude/agents/ directly. docs ↗
Sources Commands reference ↗ Interactive mode and shortcuts ↗ Checkpointing ↗
CLAUDE.md
Plain markdown that Claude reads at the start of every session. Conventions, build commands, and 'never do this' notes live here. It isn't an extension mechanism, but every other mechanism on this page works better when this file is good.
Where it lives
~/.claude/CLAUDE.md👤 Just you You, in every projectyour-repo/CLAUDE.md👥 Team The team, through gitCLAUDE.local.md👤 Just you You, in this repo. Add it to .gitignore.claude/rules/api.md👥 Team The team, only when matching files are open
All locations, including managed policy ↗
How long should it be?
Under 200 lines: what the docs recommend
Longer: more context per turn, and Claude follows it less reliably
Writing effective instructions ↗
Example
---
paths:
- "src/api/**/*.ts"
---
# API conventions
- Every endpoint validates input with zod before touching the database
- Return errors as { error: { code, message } }, never a bare string
- Every query on a tenant table filters by tenant_id
Gotchas: 6 things that bite people
- Over 200 lines? Move anything that only matters for part of the codebase into path-scoped rules, so it loads only when Claude touches those files. docs ↗
- @path imports help you organize a long file but don't save any context. Imported files load at launch too. docs ↗
- If two instructions contradict each other, Claude may pick one arbitrarily. /doctor prompt-audit looks for conflicts across your CLAUDE.md files, rules, and skills. docs ↗
- CLAUDE.md is a request, not a guarantee. If a rule has to hold every time, back it with a hook. docs ↗
- Already have an AGENTS.md for other coding tools? Claude Code can read it, so you don't need two copies. docs ↗
- Auto memory saves notes on its own (your preferences, corrections, project context). Check what it wrote with /memory now and then. docs ↗
Skills
A skill is a folder with a SKILL.md file. You run it with /skill-name, and Claude can also load it on its own when the description matches what you're doing.
Config.claude/skills/<name>/SKILL.md (project) · ~/.claude/skills/<name>/SKILL.md (personal)
Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. Old command files keep working, but write new ones as skills so you get supporting files and invocation control. docs ↗
Common Frontmatter
name- Command name in the / menu. Defaults to the directory name.
description- What it does and when to use it. Claude matches on this, so put the key use case first.
allowed-tools- Tools Claude can use without asking permission during the turn that invokes the skill, e.g. Bash(npm run *) Read
disable-model-invocation- true = only you can trigger it with /name. Use for anything with side effects.
user-invocable- false = hidden from the / menu, only Claude loads it (background knowledge)
argument-hint- Autocomplete hint, e.g. [staging|production]
context- fork = run the skill in a subagent with its own context
Who can trigger it?
Both of you
(default)- You ✓
- Claude ✓
Description sits in context every turn
Use for Most skills
Only you
disable-model-invocation: true- You ✓
- Claude ✗
Description stays out of context
Use for /deploy, /commit, anything with side effects
Only Claude
user-invocable: false- You ✗
- Claude ✓
Description sits in context every turn
Use for Background knowledge, like how a legacy system works
Example
---
name: deploy
description: Deploy the current branch to staging or production
argument-hint: [staging|production]
disable-model-invocation: true
allowed-tools: Bash(npm run *) Bash(npm test) Read
---
Current branch: !`git branch --show-current`
Deploy the app to $ARGUMENTS (default: staging):
1. Run tests: `npm test`
2. Build: `npm run build`
3. Deploy: `npm run deploy -- --env $ARGUMENTS`
4. Verify the deployment health check passes
5. Report the deployed URL back to me
Gotchas: 6 things that bite people
- allowed-tools pre-approves tools, it doesn't restrict them. The grant clears when you send your next message. To take tools away while a skill is active, use disallowed-tools. docs ↗
- $ARGUMENTS is everything after the command. Use $0, $1, $2 for positional arguments, or name them with the arguments field. Quote multi-word values. docs ↗
- The !`command` syntax runs before Claude sees the skill, and the output replaces the placeholder. Handy for injecting git status or a PR diff. docs ↗
- Descriptions are truncated at 1,536 characters in the skill listing. Too vague and you get false triggers, too long and the important part gets cut. docs ↗
- Once invoked, a skill's content stays in context for the rest of the session. Every line costs tokens on every later turn, so keep SKILL.md tight and move reference material into supporting files. docs ↗
- Malformed YAML frontmatter fails silently. /name still works, but Claude can't match your description. Run claude --debug to see the parse error. docs ↗
Sources Skills docs ↗ Frontmatter reference ↗ anthropics/skills examples ↗
Subagents
Specialized assistants that do a side task in their own context window and return only a summary. Define one when you keep spawning the same kind of worker with the same instructions.
Config.claude/agents/*.md (project) · ~/.claude/agents/*.md (personal)
Frontmatter
name- Required. Unique identifier, e.g. test-runner
description- Required. When Claude should delegate to this agent
tools- Comma-separated allowlist, e.g. Read, Grep, Bash. Omit to inherit every tool.
disallowedTools- Tools to remove from the inherited or listed set
model- sonnet, opus, haiku, fable, a full model ID, or inherit
permissionMode- default, acceptEdits, auto, dontAsk, plan, or bypassPermissions
Why delegate: what ends up in your context
Do it yourself
Your conversation
- Your work
- Test logs
- Files it read
92% full of stuff you'll never look at again
Delegate to a subagent
Your conversation
- Your work
- Summary
35% full. Just the answer came back
test-runner (its own window)
- Test logs
- Files it read
Thrown away when it finishes
Illustrative. The point is the shape, not the exact numbers. docs ↗
Subagents can delegate too
- 🧑 You
- 🤖 reviewer layer 1
- 🤖 verifier layer 2
- 🤖 fact-checker layer 3
Three layers below you by default. At the limit the Agent tool is withheld, so the last one does the work itself. Change it with CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH. docs ↗
Example
---
name: test-runner
description: Run the test suite and report failures with suggested fixes. Use after code changes.
tools: Bash, Read, Grep, Glob
model: sonnet
---
You are a test-running specialist. When invoked:
1. Identify the test framework in use (check package.json, pytest.ini, etc.)
2. Run the full test suite
3. For any failures, read the failing test and the source code
4. Report: which tests failed, why, and a suggested fix
5. Never modify source code. Only report findings.
Gotchas: 5 things that bite people
- Subagents start fresh. They don't see your conversation history, so the delegation prompt has to carry the context. They do load CLAUDE.md and a git status snapshot (the built-in Explore and Plan agents skip both). docs ↗
- The Task tool was renamed to Agent in v2.1.63. Old Task(...) references in settings still work as aliases. docs ↗
- Every agent's description sits in context on every turn. Claude Code warns at startup once your custom agents' descriptions pass 15,000 tokens. Keep descriptions short and put detail in the body. docs ↗
- Use the model field to run read-only or mechanical agents on haiku for cost savings. docs ↗
- Keep agent prompts focused. A 'do everything' agent defeats the purpose.
Sources Subagents docs ↗ Example subagents ↗
Hooks
Handlers that fire automatically on lifecycle events. Use them for guardrails, formatting, logging, and notifications. A hook can be a shell command, an HTTP call, an MCP tool, or a prompt for a model to evaluate.
Config.claude/settings.json → hooks (also ~/.claude/settings.json, .claude/settings.local.json, plugins)
Exit codes: the part everyone gets wrong
exit 0
Go
Success. The action runs. JSON on stdout can still steer it.
exit 2
Blocked
The action is stopped, and your stderr goes to Claude as the reason.
exit 1, 3, …
Error, but it runs anyway
Logged as a hook error and the action still happens. A hook that exits 1 to block does nothing.
Lifecycle Events
Claude Code has over 30 hook events. These are the ones you'll reach for first.
| Event | When it fires | Blocking |
|---|---|---|
SessionStart | Session starts or resumes. Stdout is added to Claude's context, so it's good for injecting state. | 👁 Watch only |
UserPromptSubmit | Fires when you submit a prompt, before Claude sees it. | 🛑 Can block |
PreToolUse | Fires before a tool runs. Exit 2 blocks the call. | 🛑 Can block |
PermissionRequest | Fires when a permission prompt would appear. Return a decision to allow or deny it. | 🔀 Decides allow/deny |
PostToolUse | Fires after a tool succeeds. Gets tool_input and tool_response on stdin. | 👁 Watch only |
Notification | Fires when Claude needs your attention (waiting on input or a permission prompt). | 👁 Watch only |
SubagentStop | Fires when a subagent finishes. | 🛑 Can block |
Stop | Fires when Claude finishes responding. Blocking it makes Claude keep working. | 🛑 Can block |
PreCompact | Fires before context compaction. | 🛑 Can block |
SessionEnd | Fires when the session ends. Good for cleanup and logging. | 👁 Watch only |
Examples
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.command' | grep -qE 'git (push.*(-f|--force)|reset --hard|clean -f)' && { echo 'Blocked: destructive git command' >&2; exit 2; } || exit 0"
}
]
}
]
}
}
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
}
]
}
]
}
}
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}
Gotchas: 5 things that bite people
- The config is nested: each event holds a list of matchers, and each matcher holds its own hooks array of handlers with a type. A flat { matcher, command } entry won't load. docs ↗
- Hooks get JSON on stdin with session_id, cwd, and hook_event_name. Tool events add tool_name, tool_input, and (after the call) tool_response. docs ↗
- Without a matcher (or with "*"), a hook fires on every occurrence of its event. Scope tool hooks with something like Edit|Write. docs ↗
- Hooks run with your user permissions. Keep them fast, since a slow PreToolUse hook slows down every tool call. docs ↗
- Run /hooks to see what actually loaded. If it shows nothing, check which settings file you edited. docs ↗
MCP Servers
Model Context Protocol servers expose external tools to Claude. Add one with claude mcp add and its tools are available in your session. Remote servers use HTTP, local ones run as a process over stdio.
Config.mcp.json (project, committed) · ~/.claude.json (local and user scopes)
Popular servers, one copy away
GitHub
Review PRs, create issues, search repos
claude mcp add --transport http github https://api.githubcopilot.com/mcp/
Sentry
Pull errors and stack traces into the chat
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
Notion
Read and update docs, specs, and databases
claude mcp add --transport http notion https://mcp.notion.com/mcp
Postgres (DBHub)
Query and inspect schemas. Use a read-only user
claude mcp add db -- npx -y @bytebase/dbhub --dsn "postgresql://..."
Playwright
Drive a real browser: click, fill, screenshot
claude mcp add playwright -- npx @playwright/mcp@latest
Same server name in two places? The top one wins
- 1
Local wins
~/.claude.jsonYou, this project - 2
Project
.mcp.jsonThe team, through git - 3
User
~/.claude.jsonYou, every project - 4
Plugin
a plugin's .mcp.jsonWherever the plugin is on - 5
claude.ai connectors
your claude.ai accountYou, everywhere
The winning entry is used whole. Fields don't merge across scopes. docs ↗
Example
{
"mcpServers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "Bearer ${GITHUB_PAT}"
}
},
"db": {
"command": "npx",
"args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"]
}
}
}
Gotchas: 5 things that bite people
- The old reference packages like @modelcontextprotocol/server-github and server-postgres are archived. GitHub now runs an official remote server, and the Claude Code docs point Postgres users to DBHub. docs ↗
- Never hardcode secrets in .mcp.json. It supports ${VAR} and ${VAR:-default} expansion. docs ↗
- Claude Code asks you to approve .mcp.json servers in interactive sessions, but claude -p and cloud sessions load them without asking. Review what's in a repo's .mcp.json before you run it headless. docs ↗
- Tool search is on by default, so only tool names load at startup and full definitions load when needed. Adding servers costs much less context than it used to. docs ↗
- Run /mcp to check status and handle OAuth, or claude mcp list from your shell. docs ↗
Sources MCP docs ↗ MCP quickstart ↗ Playwright MCP ↗ DBHub ↗
Plugins
A plugin is a directory of skills, agents, hooks, and MCP servers that Claude Code installs and loads as one unit. It's the distribution layer on top of the four mechanisms above.
Config.claude-plugin/plugin.json (manifest) · managed with /plugin
What a plugin contains
A manifest at .claude-plugin/plugin.json, plus any of skills/, agents/, hooks/hooks.json, and .mcp.json. Plugin skills are namespaced, so a review skill in my-plugin runs as /my-plugin:review and two plugins can't collide.
Marketplaces
A marketplace is a repo with a .claude-plugin/marketplace.json listing plugins and where to fetch them. Claude Code adds Anthropic's official one (claude-plugins-official) the first time you start an interactive session.
Build vs. install
Install one to get a setup someone else maintains. Build one to give your team's setup to every repo with versioned updates. While you're developing, skip the marketplace and load it straight from the folder with --plugin-dir.
What's in the box
my-plugin
.claude-plugin/plugin.jsonSkills
skills/review/SKILL.md→ runs as /my-plugin:review
Agents
agents/reviewer.md→ a subagent Claude can delegate to
Hooks
hooks/hooks.json→ run on lifecycle events
MCP
.mcp.json→ tools from a server
Who made it?
Official
claude-plugins-officialAnthropic's own. Added the first time you start Claude Code.
Community
claude-communityAnthropic-hosted community names, only from github.com/anthropics/.
Third-party
your-company/pluginsEverything else, including your own company's marketplace.
Commands
| Command | What It Does |
|---|---|
/plugin | Open the plugin manager (Discover, Installed, Marketplaces tabs) |
/plugin marketplace add <source> | Add a marketplace from a GitHub repo, URL, or local path |
/plugin install <name>@<marketplace> | Install a plugin, e.g. commit-commands@claude-plugins-official |
/reload-plugins | Apply plugin edits without restarting the session |
claude --plugin-dir ./my-plugin | Load a plugin from disk for one session (for development) |
claude plugin disable <name> | Turn a plugin off without uninstalling it |
Gotchas: 4 things that bite people
- A plugin runs as you. Its hooks and MCP servers execute with your user privileges, so review what a plugin adds before installing it, whatever marketplace it came from. docs ↗
- An enabled plugin costs context in every session, not just the ones where you use it. The names and descriptions of its skills and agents load on every turn. Plugins in the official marketplace show a Context cost estimate before you install. docs ↗
- Only marketplaces sourced from github.com/anthropics/ can use Anthropic's official names. Anything else, including your company's marketplace, is third-party. docs ↗
- Community plugins reflect the author's workflow and opinions. A plugin that enforces strict TDD might fight your team's process. A focused setup usually beats a stack of plugins.
Sources Plugins overview ↗ Create a plugin ↗ Plugin commands ↗ Browse plugins ↗
Why Your Org Should Build Custom Plugins
The case for investing in Claude Code customization.
Consistency at Scale
When 20 developers prompt Claude differently, you get 20 different patterns. Skills and agents encode your team's best practices into reusable templates, so every engineer gets the senior architect's approach by default.
Guardrails That Actually Work
An instruction in CLAUDE.md is a request. A PreToolUse hook is enforcement. Block force-pushes, protect .env, auto-format every edit, all without relying on anyone remembering the process. docs ↗
Faster Onboarding
New developers run /setup and get a working environment. They run /deploy and it works. The knowledge that used to live in a senior engineer's head becomes something you can execute.
Tribal Knowledge Codification
Every organization has unwritten rules: 'always use the v2 API for payments,' 'never query the users table without a tenant filter.' CLAUDE.md and skills write them down, and hooks enforce the ones that can't be broken. Both survive employee turnover.
Compound Returns
A /review skill that takes an hour to write and saves 10 minutes per PR pays for itself after six PRs. Across 50 PRs a week and 48 working weeks, that's 400 hours a year. Plug in your own numbers below.
Your numbers, not a benchmark. Time a few PRs with and without the skill before you trust the minutes.
50
PRs
10
min
1
hrs
Pays for itself after
6 PRs
Hours back per year
400
Hours per year = PRs per week × minutes saved × 48 working weeks ÷ 60. Payback = build time ÷ minutes saved per PR.
Ready to Go Deeper?
This cheat sheet covers the mechanics. Know someone who isn't an engineer and wants to start? The guide walks them through a first build, one prompt at a time.
Read the Full Guide