别再复制粘贴 Prompt 了：3 分钟定义你自己的 Claude Code Agent

每次让 Claude 审查代码，都得先打一段"你是一个代码审查员，只看不改，按严重程度分级，禁止说看起来不错"。每次写文章，都得重复一遍"开头场景引入，不写套话，段落不超过4行"。

说一遍两遍还行，说十遍就烦了。更烦的是，Workflow 脚本里每个 agent() 调用都得把这段规则复制一遍，改一个地方要改十处。

Custom Agent 解决的就是这个问题：把规则存成一个文件，以后只说"派审查员去看"，它自己就知道该怎么干。

这篇文章讲清楚三件事：Custom Agent 是什么、怎么定义。

一、Custom Agent 和 SubAgent 是什么关系

先把两个词搞清楚，不然后面会混：

ini 复制代码

Custom Agent = 岗位模板（存在文件里的定义）
SubAgent    = 派出去干活的实例（运行时创建的独立 Claude）

打个比方：Custom Agent 是"招聘 JD"，写好了这个岗位要什么能力、遵守什么规矩。SubAgent 是"上岗的员工"，你派活的时候按 JD 创建一个人，它带着这些规矩去干活，干完汇报结果。

你定义一个"审查员"Custom Agent，每次派它出去，就创建一个 SubAgent 实例。

和 Slash Command 的区别

这是最容易搞混的。用一个具体场景说：

Slash Command /写文章 ：你敲 /写文章 Hook，主 Claude 自己写。写的过程中你能看到它在干嘛，可以中途说"第三个要点换个例子"，它听得到。

Custom Agent ：你说"派内容写手去写 Hook"，一个子 Claude 在后台独立跑。它看不到主对话里聊了什么，写完把结果丢回来。你可以继续聊别的，方向不对就在 /tasks 里停掉重派。

vbnet 复制代码

Slash Command → 主 Claude 干活，你能随时插话
Custom Agent  → 子 Claude 独立干活，干完汇报，需要时可单独引导

还有个 CLAUDE.md，那是项目规则文件，主 Claude 和子 Agent 都会读它，和 Custom Agent 不冲突------CLAUDE.md 管"这个项目的规矩"，Custom Agent 管"这个岗位怎么干活"。

二、三步上手你的第一个 Agent

第 1 步：建目录、写文件

Custom Agent 就是一个 Markdown 文件，放在 .claude/agents/ 目录下。

bash 复制代码

# 全局：所有项目都能用
mkdir -p ~/.claude/agents

# 或者项目级：只在当前项目用
mkdir -p 你的项目/.claude/agents

创建 ~/.claude/agents/article-reviewer.md：

yaml 复制代码

---
name: article-reviewer
description: 审查文章的技术准确性、AI味和可读性。当需要检查文章质量、找问题、给修改建议时使用。
tools: Read, Grep
model: haiku
---

你是文章审查员。你的任务是阅读文章并从三个维度找出具体问题。

## 审查规则

1. 技术准确性：检查技术错误、概念混淆、代码错误，标注严重程度（致命/一般/建议）
2. AI味检测：找出"在当今""随着""众所周知"等套话，标注位置
3. 可读性：指出读起来费劲的段落，说明原因

## 输出要求

- 每个问题必须标注具体位置（哪一段、哪一句）
- 禁止说"看起来不错""整体很好"这类没有信息量的话
- 如果某个维度没发现问题，写"XX维度：通过"
- 你只有读权限，不要修改文件

就这么简单。一个 YAML frontmatter（--- 包起来的部分）加一段系统 Prompt。

偷懒方式：直接在对话里说"帮我定义一个叫 article-reviewer 的 Custom Agent，规则是..."，Claude 会自动帮你创建这个文件。

第 2 步：在对话里用它

css 复制代码

你：派 article-reviewer 看看这篇文章 agent/教程草稿.md

Claude 会创建一个 SubAgent，带着你写的规则去读文件、审查，然后把结果返回到主对话。你也可以直接说"用 article-reviewer 审查......"，或者输入 /agents 从列表里选。

第 3 步：在 Workflow 里用它

javascript 复制代码

// 不用 Custom Agent：每次写 200 字规则
const review = await agent(
  `审查这篇文章，从技术准确性、AI味、可读性三个维度...
   （后面省略 200 字）`,
  { phase: '审查' }
)

// 用了 Custom Agent：只传任务，规则在模板里
const review = await agent(
  `审查这篇文章：${draft}`,
  { agentType: "article-reviewer", phase: '审查' }
)

agentType 就是你在 frontmatter 里写的 name。加这一个参数，这个子 Claude 就自带所有规则。

三、Frontmatter 每个字段怎么写

yaml 复制代码

---
name: article-reviewer   # 必须。小写加连字符，调用时用
description: ...          # 必须。最关键的字段
tools: Read, Grep         # 可选。不给就全部工具都能用
model: haiku              # 可选。不写则继承默认模型
---

逐个说：

name ：Agent 的唯一标识，用小写字母加连字符（比如 article-reviewer），agentType 传这个值。建议和文件名保持一致，虽然不是强制的，但好找。

description ：这是最容易写坏的字段。它不是自我介绍，是触发条件。主 Claude 靠它判断"这个任务该不该派给这个 Agent"。

arduino 复制代码

坏例子："一个专业的文章审查工具"
        → 太模糊，Claude 不知道什么时候该用

好例子："审查文章的技术准确性、AI味和可读性。当需要检查文章质量、找问题、给修改建议时使用。"
        → 说清了"干什么"和"什么时候用"

tools ：给什么工具。这个字段的意义不只是限制能力，更是安全。审查员只需要读文件，就不给 Write。它实际上改不了你的文件，比在 Prompt 里写"不许改"可靠得多。

model：用什么模型。个人经验：

找问题、分类、格式化这类活，haiku 够用，便宜
写文章、分析原因、综合判断，用 sonnet
别什么都用 opus，贵且没必要

四、关键特性：上下文隔离

这是 SubAgent 最重要的一个特性，很多人刚开始用会踩坑：子 Agent 看不到主对话之前聊了什么。

它拿不到主对话的历史、贴过的代码和已读的文件。主对话里讨论过的需求、改过的方案，它一概不知。

建议你动手验证一下，花不了一分钟：

arduino 复制代码

第 1 步：在主对话里聊一个背景
"我要写一篇给 Android 开发者看的入门文章，读者有 Java 基础但没接触过协程"

第 2 步：不重复背景，直接派子 Agent
"派 article-reviewer 帮我列一个文章大纲"

你会发现子 Agent 完全不知道目标读者是谁，列出来的大纲是泛泛而谈的。因为它是一个全新的、独立的上下文，主对话里聊过的背景它拿不到。

这个特性有好有坏：

好处是干净。子 Agent 去跑测试、扫日志，这些高噪声的输出不会污染主对话。主对话始终保持清爽，你和 Claude 的讨论不会被几千行测试日志淹没。

注意点是：别假设它知道背景。派活的时候把必要信息说清楚。

bash 复制代码

坏例子："按刚才说的改一下"
        → 子 Agent：刚才说啥了？

好例子："把这篇文章的开头改成场景引入式，要求：第一句是一个具体场景，
        不超过两句话，不要用'在当今'开头。文章内容：${draft}"
        → 它需要的信息全在任务描述里

五、全局和项目级放哪

bash 复制代码

~/.claude/agents/          → 全局，所有项目可用
项目/.claude/agents/       → 项目级，只在这个项目用

怎么选：

通用角色（审查员、写手、研究员）放全局，哪个项目都能用
项目专属角色（比如"Android 模块审查员"，只看你这个项目的结构）放项目级
重名时项目级优先

六、什么时候该定义，什么时候别折腾

我的判断标准很简单：

复制代码

同一段规则在 3 个以上不同任务里重复出现 → 定义
只用一次 → 直接写在 Prompt 里，别折腾

还有几种情况也没必要：

需要频繁来回确认的任务（子 Agent 独立于主对话，来回沟通成本高，不适合）
就改一两行的小事（派 Agent 的开销比直接改还大）
规则还没稳定，正在频繁调整（先在 Prompt 里迭代，稳定了再存）

定义 Agent 不是越多越好。我目前常用的也就四五个，都是反复用、规则稳定的。

七、定义完对照检查

写完一个 Agent，过一遍这个清单：

bash 复制代码

□ name 用小写字母加连字符了吗？（别用中文或空格）
□ description 写清"干什么 + 什么时候用"了吗？
□ tools 只给了必要的吗？（只读的活别给 Write）
□ 派活时把背景信息说全了吗？（子 Agent 看不到主对话）
□ 文件改了重启会话了吗？（直接改文件需重启，/agents界面创建的立即生效）
□ 这个规则真的会重复用 3 次以上吗？

小结

ini 复制代码

Custom Agent = 存在 .claude/agents/xxx.md 里的岗位模板
SubAgent    = 派活时按模板创建的独立 Claude

三步：建目录写文件 → 对话里派它 → Workflow 里用 agentType 指定

四个字段：
  name        Agent 标识（小写加连字符）
  description 触发条件（最关键）
  tools       给什么工具（安全靠它）
  model       用什么模型（省钱靠它）

核心特性：上下文隔离
  子 Agent 看不到主对话 → 干净，但派活时要给足背景

下一篇讲 Agent Prompt 怎么写，通过三个真实案例（视频导演、帧数据生成器、审查员）讲清楚怎么写规则、怎么限制输出格式、怎么让 Agent 不越权。