Extend Claude Code with Custom Subagents and Slash Commands

What you'll build

Two project-level extensions for Claude Code: a diff-reviewer subagent that audits your branch with read-only-ish tools, and a /pr-summary slash command that injects the real branch diff and drafts a PR description. Both live in .claude/, so they get committed and every teammate picks them up automatically.

Prerequisites

Verified against Claude Code v2.1.267 (September 2026) and git 2.x on macOS. Everything here also works on Linux, WSL, and Windows; only the install command differs.

Install Claude Code if you haven't:

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

Confirm with claude --version, which prints the version followed by (Claude Code). You also need a Claude subscription (Pro, Max, Team, or Enterprise) or a Console account; run claude once and follow the login prompt. The tutorial assumes a repo whose default branch is main.

1. Scaffold the directories

From your repo root:

mkdir -p .claude/agents .claude/skills/pr-summary

Subagents are Markdown files in .claude/agents/. Slash commands are skills: one directory per command under .claude/skills/, each containing a SKILL.md. (The older .claude/commands/deploy.md format still works, but skill directories are the current form and let you bundle helper scripts later.) Files in ~/.claude/agents/ and ~/.claude/skills/ do the same job across all your projects; project-level files win when names collide with lower-priority sources.

2. Create the diff-reviewer subagent

A subagent is a system prompt plus YAML frontmatter. It runs in its own context window, which is the point: a 3,000-line diff review happens over there, and only the findings come back to your main conversation.

Create .claude/agents/diff-reviewer.md:

---
name: diff-reviewer
description: Reviews branch diffs for bugs, risky patterns, and missing tests. Use proactively after code changes or before opening a PR.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a code reviewer for this repository. When invoked:

1. Run `git diff main...HEAD` to see what changed on this branch.
2. Read any changed file where the diff alone lacks context.
3. Report findings in three sections: bugs, risky patterns (error
   handling, auth, hardcoded values), and missing tests.

Cite file and line for every finding, quote the offending code, and
suggest a concrete fix. Never edit files.

Three frontmatter fields do the work. name must be lowercase letters and hyphens. description is what the main agent reads when deciding whether to delegate, so write it as trigger conditions, not marketing; "Use proactively after code changes" is the phrasing Anthropic's own examples use to encourage delegation. tools is an allowlist: leaving out Write and Edit means the reviewer can't touch your code even if its prompt goes sideways. model: sonnet keeps reviews fast and cheap; valid values are sonnet, opus, haiku, fable, a full model ID, or inherit.

One version note: /agents used to open an interactive wizard, but as of v2.1.198 it doesn't. Write the file yourself or ask Claude to write it.

3. Create the /pr-summary slash command

Create .claude/skills/pr-summary/SKILL.md:

---
name: pr-summary
description: Draft a PR title and description from the current branch diff
disable-model-invocation: true
allowed-tools: Bash(git log *), Bash(git diff *)
---

## Branch context

- Commits: !`git log --oneline main..HEAD`
- Files changed: !`git diff --stat main...HEAD`

## Full diff

!`git diff main...HEAD`

## Instructions

Write a PR title (imperative, under 70 characters) and a description
with three sections: Summary, Changes, and Testing. Base every claim
on the diff above. If the diff shows no test changes, say exactly what
to run manually. Output Markdown only, ready to paste into GitHub.

The !`command` syntax is what makes this reliable: each command runs before the model sees anything, and its output replaces the placeholder. The model writes the summary from your actual diff instead of guessing from conversation history. disable-model-invocation: true makes the command yours alone; Claude can't decide to trigger it mid-task. allowed-tools pre-approves those two git patterns for the turn, so follow-up commands the model runs (say, git log on one file's history) don't produce permission prompts.

4. Route the command through the subagent (optional)

For big branches you can run the summary in the subagent's context instead of your main conversation. Add three lines to the SKILL.md frontmatter:

context: fork
agent: diff-reviewer
background: false

context: fork runs the skill in an isolated subagent with no conversation history, agent picks which one, and background: false makes it wait and return the result in the current turn instead of running detached. The 3,000-line diff now never enters your main context window.

Verify it works

Make a scratch branch with a real change:

git checkout -b demo/pr-summary
cat > add.js <<'EOF'
export function add(a, b) {
  return a + b;
}
EOF
git add add.js
git commit -m "add add() helper"
claude

Skills and agents load at session start, so start claude after the files exist. Type /pr- and the command should autocomplete; run /pr-summary. Expected output, modulo wording:

## Summary
Adds an `add()` helper exporting a two-argument addition function.

## Changes
- New file `add.js` with `add(a, b)`

## Testing
No tests in the diff. Run `node -e "import('./add.js').then(m =>
console.log(m.add(2, 3)))"` and confirm it prints 5.

Now the subagent. Type @agent-diff-reviewer review this branch. You'll see a task entry for diff-reviewer while it works, then a report with the three sections from its prompt (for this branch: no bugs, no input validation on add(), no test coverage). The @agent- mention forces delegation; plain requests like "review my changes before I open a PR" should route there too, thanks to the description.

Troubleshooting

/pr-summary missing from the / menu: the session predates the file. Exit (/exit) and rerun claude. Also check the exact path; it must be .claude/skills/pr-summary/SKILL.md, not .claude/skills/pr-summary.md.

fatal: ambiguous argument 'main...HEAD': unknown revision or path not in the working tree. Any !`command` that exits non-zero aborts the whole invocation, and this one means main doesn't exist locally. Fix with git fetch origin main:main, or swap main for master in SKILL.md if that's your default branch.

Claude answers review requests itself instead of delegating: the description isn't specific enough for the router. Add explicit trigger phrasing ("Use proactively after code changes"), or force it with @agent-diff-reviewer. Frontmatter that fails to parse (a stray tab, a name with uppercase or colons) also silently disqualifies the agent, so lint the YAML first.

Permission prompt on every git command during /pr-summary: the allowed-tools grant only covers patterns you listed. git show, for example, matches neither git log * nor git diff *; add Bash(git show *) if the model needs it.

Next steps

Make commands parameterized: $ARGUMENTS expands to everything typed after the command, and an arguments: [base_branch] frontmatter field gives you named $base_branch substitution, so /pr-summary develop could set the diff base. Give the reviewer memory: project and it accumulates repo conventions across sessions. hooks frontmatter lets an agent validate commands before running them (the docs show a read-only SQL gate). The full field references live in the subagents and slash commands docs, and both files you wrote today are plain Markdown in your repo: treat them like code, review changes to them, and iterate.