Custom Subagent Structure — Claude Code Guide

A custom subagent is a versioned workflow

A custom subagent stores repeatable work rules in a Markdown file. The team can review it in Git, discuss changes, and check whether permissions expanded silently.

The file describes a role and contract; it does not make the result correct automatically. Its scope, tools, and instructions must fit the actual task.

Minimal file structure

---
name: reviewer
description: Read-only reviewer for prepared diffs.
tools: [read, grep, diff]
---

## Role
Inspect a prepared diff in a defined area.

## Prohibitions
Do not edit code or expand scope without an owner decision.

## Result
Return findings with severity, file:line, evidence, and confidence.

Description routes usage

The description should say what the subagent does, when to invoke it, and what it does not do. A generic description encourages bad delegation; explicit prohibitions keep a read-only role narrow.

1. Choose the audience and scope.
2. Define role, use conditions, permitted actions, and stop conditions.
3. Limit tools to the minimum set.
4. Run on a safe prepared diff.
5. Confirm that it returns evidence and makes no changes.
6. Store and review the file as an engineering artifact.

A role file is not permission for everything

• Markdown instructions do not replace permissions or approvals.
• Shell or write access increases the capability surface.
• A custom subagent should not move from review to implementation on its own.
• Verify version-sensitive details against current CLI documentation.