Build the plugin

Module 12. The only required key is name. Everything else is metadata or a path override.

{
"name": "diff-review",
"displayName": "Diff Review",
"version": "1.0.0",
"description": "Reviews uncommitted changes before you commit them.",
"author": {
  "name": "Learn Claude Code",
  "url": "https://github.com/learn-claude-code/diff-review"
},
"license": "MIT",
"keywords": ["review", "git", "diff", "pre-commit"],
"experimental": {
  "themes": "./themes/"
}
}

1. L1 This file is the only thing that belongs inside .claude-plugin/. Every directory below it sits at the plugin root instead. Move one in here and it stops loading, with no error in the Errors tab and nothing in validation.
2. L2 The only required field, and the namespace for every component in the tree. It is what makes module 5's skill answer to /diff-review:review-changes; the directory the plugin is checked out into has no say in the name.
3. L4 Setting version pins the plugin to that string, so users receive an update only when you bump it. Omit it and the version comes from the marketplace entry instead. Where both exist, plugin.json wins.
4. L5 Misspell this key and nothing errors. An unknown field is legal JSON and legal to the loader, so it does nothing quietly until claude plugin validate --strict promotes the warning to a failure.
5. L10 Metadata from here down. displayName, license and keywords change what a person reads in the plugin manager and change nothing about which directories load.
6. L13 Module 6's theme, pointed at from under experimental because the schema for themes and monitors may still change. A top-level themes key works today, warns under claude plugin validate, and a future release will require this placement.

Module 4. A flat markdown file, still a valid plugin component.

---
description: Print the diffstat for uncommitted work, grouped by directory.
argument-hint: [path]
---

!`git diff --stat -- ${0:-.}`

Read the diffstat above. Report which directories the change touches
and which single file moved the most lines.

1. L1 Module 4 wrote this file into .claude/commands/. Nothing inside it changed on the way in. What changed is the invocation, which is now /diff-review:diff-stat and cannot be shadowed by a project skill of the same short name.
2. L6 The ! runs the command and injects its output before the model reads the rest of the file. It is recognised only at the start of a line or immediately after whitespace, so an indented copy of this line would stay literal text.

Executed, never loaded into context. Still reached through ${CLAUDE_SKILL_DIR}, which resolves inside the plugin now.

#!/usr/bin/env bash
set -euo pipefail
path="${1:-.}"

echo "== diffstat =="
git diff --stat -- "$path" || true

echo
echo "== files =="
git diff --name-only -- "$path" | head -100

1. L2 Strict mode, which makes the next line matter. Under set -e a single non-zero exit ends the script, and a hook or skill script that dies early looks identical to one that had nothing to report.
2. L6 The || true is there because git exits non-zero outside a repository and with nothing staged. Without it, a user running the skill in a plain directory gets silence instead of an empty diffstat.
3. L10 The cap is here rather than in the skill body because this output is read by the model. The script itself is executed and never loaded into context, so its own length costs nothing; what it prints does.

Module 5. Inside a plugin, frontmatter name sets the last segment of the command.

---
name: review-changes
description: Review uncommitted changes and flag anything risky before a commit.
when_to_use: When the user asks what changed, wants a commit message,
or asks whether the diff is safe to commit.
argument-hint: [path]
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/summarize.sh *)
---

Run `${CLAUDE_SKILL_DIR}/scripts/summarize.sh $0` and read its output.

Summarize the change in two or three bullets, then list anything
risky. The risk categories are in reference.md next to this file.

1. L2 Module 5's skill, and the one field whose meaning changed on arrival. Inside a plugin, name sets the segment after the colon; outside one, the directory decides the command name and this is a display label.
2. L7 The pre-approval and the body have to agree on the path. ${CLAUDE_SKILL_DIR} substitutes in both the body and Bash rules in allowed-tools, and that pairing is what lets a bundled script run without a prompt.
3. L10 The script now lives inside the plugin's installation directory, which moves on every update. Writing the path through the variable is what keeps this line correct after the user upgrades.
4. L13 reference.md sits next to this file and is not loaded until the skill sends Claude to it. Only the name and description are in context at startup; everything else is fetched on demand.

Module 6. The filename minus .json is the slug, exactly as it was in your home directory.

{
"name": "Review Dusk",
"base": "dark",
"overrides": {
  "diffAdded": "#2f5d3a",
  "diffRemoved": "#6b2f35",
  "warning": "#d8a657",
  "error": "#e06c75"
}
}

1. L2 A display label. The slug comes from the filename minus .json, so this theme is stored as custom:diff-review:review-dusk once the plugin ships it, where module 6's copy in your home directory was custom:review-dusk.
2. L3 base names the built-in theme this inherits from, one of dark, light, and their daltonized and ansi variants. It is why overrides only has to list the four colours you actually changed.

Module 7. Same file you wrote into .claude/output-styles/, moved wholesale.

---
name: Review notes
description: Verdict first, then evidence, in the register of a code review
keep-coding-instructions: true
---

Open every response about a diff with a one-line verdict: safe to
commit, safe with edits, or hold. Then give the evidence as findings.

1. L4 Module 7's file, and the field that decides how much of Claude Code survives it. An output style is appended to the system prompt and drops the built-in software engineering instructions unless this is true. It defaults to false.
2. L7 Output styles take effect on /clear or a new session rather than immediately, and they do not apply to subagents. The risk-reviewer agent below reports in its own voice regardless of what this file says.

Module 8. Invoked as @agent-diff-review:risk-reviewer.

---
name: risk-reviewer
description: Reads a diff in isolated context and reports only the risks.
tools: Read, Grep, Glob, Bash
model: sonnet
color: orange
---

You review a diff and report risk. You do not write code.

For each risk, give the file, the line, the category, and one
sentence on what breaks if the change ships as written.

1. L2 Module 8 wrote this agent. Its name is the one component name in the tree that a teammate can take from you: a project or user .claude/agents/risk-reviewer.md on their machine overrides the plugin copy.
2. L4 The pool this agent can reach. A handful of tools are stripped from every subagent whatever you list here, AskUserQuestion and EndConversation among them, so do not write a workflow that depends on one.
3. L7 Three fields you could write above this line stop working once the agent ships in a plugin. permissionMode, mcpServers and hooks are all ignored for plugin agents, so the policy this agent runs under is the installing user's, not yours.

Module 9. Identical format to the hooks object in settings.json, plus an optional description.

{
"description": "Deny reads of secret-shaped files while reviewing a diff.",
"hooks": {
  "PreToolUse": [
    {
      "matcher": "Read|Bash",
      "hooks": [
        {
          "type": "command",
          "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/block_secrets.py\"",
          "timeout": 10
        }
      ]
    }
  ]
}
}

1. L1 Module 9 wrote this object into .claude/settings.json. The docs say to copy it across unchanged, because the format is the same. What changed is where it lives: hooks/hooks.json at the plugin root, never inside .claude-plugin/.
2. L4 Hook entries merge across levels rather than replacing each other, and a plugin copy of a handler stays separate from an identical one in settings. Ship a hook a user already runs and it runs twice.
3. L6 Matchers are evaluated against the runtime tool name. If this plugin's own MCP server were the target, the matcher would need mcp__plugin_diff-review_repo-files__<tool>: written against the bare server key it never fires.
4. L10 The path goes through ${CLAUDE_PLUGIN_ROOT} because the plugin's installation directory changes on every update. A hardcoded path works on your machine and breaks the first time a user upgrades.
5. L10 The escaped quotes around the variable are part of the command. Shell form hands the whole string to a shell, so an installation directory containing a space splits into two arguments without them.
6. L11 Seconds, and far below the 600-second default for a command handler. A hook that decides whether a read is allowed is on the critical path of every Read and Bash call, so give it a budget that fails fast.

The tested hook from the hooks lab, copied in unchanged.

#!/usr/bin/env python3
"""PreToolUse (Read|Bash): deny access to secret files."""
import json, re, sys

SECRET = re.compile(
  r"(^|/)(\.env(\.[\w-]+)?|id_rsa|id_ed25519|.*\.pem|credentials\.json)$")

data = json.load(sys.stdin)
# ... emits a permissionDecision of "deny" on a match, then exits 0.
# The JSON carries the decision. Silence is not approval.

1. L8 The hook reads its input as JSON on stdin. That is the whole interface: Claude Code writes the event, the script writes a decision back, and nothing else passes between them.
2. L9 A permissionDecision of "deny" blocks the call and tells Claude why. Exit 2 blocks it as well, and the two are not interchangeable: exit 2 stops the call before permission rules are evaluated.
3. L10 Exit 0 with no output means the hook had no decision to report and the call continues through the normal permission flow. The docs say it plainly, and it is the line the hooks lab is built to prove.

Module 10. At the plugin root, not inside .claude-plugin/.

{
"mcpServers": {
  "repo-files": {
    "type": "stdio",
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-filesystem",
      "${CLAUDE_PROJECT_DIR}"
    ]
  }
}
}

1. L1 Module 10 wrote this file and it moved without an edit. It sits at the plugin root beside hooks/ and skills/. Inside .claude-plugin/ it would load nothing, and the failure looks like a server that was never configured.
2. L3 This key is half of the runtime name. Tools arrive as mcp__plugin_diff-review_repo-files__<tool>, and an mcp_tool hook aimed at the server needs a third spelling, plugin:diff-review:repo-files.
3. L9 CLAUDE_PROJECT_DIR is the project root, so the filesystem server is scoped to the repository being reviewed. CLAUDE_PLUGIN_ROOT here would point the server at the plugin's own installed files, which is where your code lives and not where the user's work is.

Not loaded by Claude Code. Written for the person deciding whether to install this.

# diff-review

Reviews uncommitted changes before you commit them, and refuses to
read secret files while doing it.

  claude --plugin-dir ./example-plugin

1. L6 There is no install step for local development. The flag loads the plugin for one session, and a --plugin-dir plugin outranks an installed marketplace plugin of the same name, which is how you test a change against the version your team already runs.