create-or-audit-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create or audit a subagent

创建或审核子代理

Subagents are isolated, read-only (by default) contexts for bounded analysis tasks. They do NOT replace skills — skills take actions; agents produce reports.

子代理是用于限定范围分析任务的独立、默认只读的上下文。它们不能替代skills——skills执行操作，而agents生成报告。

Before You Start

开始之前

```
skills/meta/create-or-audit-agent/templates/agent.md
```
— annotated blank skeleton with frontmatter rules and the read-only-enforcement rationale.
```
skills/meta/create-or-audit-agent/lib/validate.sh
```
— mechanical checks including the read-only enforcement rule.
Decision rule: agents = read-only analysis producing structured reports; skills = action-taking workflows. If the task writes files or changes state, build a skill (use
```
create-or-audit-skill
```
).

```
skills/meta/create-or-audit-agent/templates/agent.md
```
—— 带有注释的空白框架，包含前置元数据规则和只读强制机制的原理说明。
```
skills/meta/create-or-audit-agent/lib/validate.sh
```
—— 包含只读强制规则在内的机械检查脚本。
决策规则：agents = 生成结构化报告的只读分析；skills = 执行操作的工作流。如果任务涉及写入文件或更改状态，请构建skill（使用
```
create-or-audit-skill
```
）。

Mode 1 — build a new agent

模式1 —— 构建新代理

Step 1: decide agent vs skill

步骤1：确定用agent还是skill

If the task is any of the following, a subagent is the right tool:

The analysis would flood main context with tool output (large codebase scans, full log dumps).
The output is a structured report the caller can consume (review, audit, impact analysis).
The context is bounded and read-only (no writes, no shell commands with side effects).

If the task takes actions (edits files, creates PRs, runs tests that change state), write a skill instead.

如果任务符合以下任一情况，子代理是合适的工具：

分析过程会让主上下文充斥大量工具输出（如大型代码库扫描、完整日志导出）。
输出是调用方可使用的结构化报告（如评审、审计、影响分析）。
上下文是限定范围且只读的（无写入操作、无带有副作用的shell命令）。

如果任务需要执行操作（编辑文件、创建PR、运行会更改状态的测试），请编写skill替代。

Step 2: choose the read-only posture

步骤2：选择只读模式

If the description mentions

review

analyze

audit

scan

check

, or

research

without

fix

implement

create

write

modify

, or

update

```
tools: Read, Grep, Glob
```
(minimum) — add
```
Bash
```
only if the agent must run tests or
```
git
```
read-only commands.
Do NOT include
```
Write
```
or
```
Edit
```
. The validator errors on read-only-sounding agents with write tools.

如果描述中提到

review

、

analyze

、

audit

、

scan

、

check

或

research

，但未提及

fix

、

implement

、

create

、

write

、

modify

或

update

：

```
tools: Read, Grep, Glob
```
（最小配置）—— 仅当agent必须运行测试或
```
git
```
只读命令时，才添加
```
Bash
```
。
请勿包含
```
Write
```
或
```
Edit
```
。验证器会对看似只读的agent却包含写入工具的情况报错。

Step 3: write the frontmatter

步骤3：编写前置元数据

yaml

---
name: agent-name-kebab-case
description: >
  One dense sentence: what this agent analyzes.
  Use when user says 'trigger 1', 'trigger 2', 'trigger 3'.
  Do NOT use for (sibling case that redirects).
tools: Read, Grep, Glob
model: sonnet
permissionMode: plan
maxTurns: 25
---

```
name
```
matches the filename.
Description: ≥3 trigger phrases, ≥1 "Do NOT use for", no angle brackets, < 1024 chars.
```
maxTurns
```
— a read-only analysis rarely needs > 30.

yaml

---
name: agent-name-kebab-case
description: >
  一句简洁的句子：说明该agent分析的内容。
  当用户说‘触发词1’、‘触发词2’、‘触发词3’时使用。
  请勿用于（需重定向的同类场景）。
tools: Read, Grep, Glob
model: sonnet
permissionMode: plan
maxTurns: 25
---

```
name
```
需与文件名匹配。
描述：至少包含3个触发短语、至少1个“请勿用于”说明，无尖括号，字符数少于1024。
```
maxTurns
```
—— 只读分析很少需要超过30轮对话。

Step 4: write the body

步骤4：编写主体内容

The body is the agent's system prompt — it starts cold, no conversation context. Structure it as:

You are a {role} — one-line role declaration.
What You Should Read First — 1–3 orientation files (
```
src/...
```
,
```
docs/...
```
). The agent runs
```
Read
```
on these before starting.
How You Work — numbered phases or steps. Each phase has a concrete goal and a hand-off.
What You Report Back — a markdown skeleton. Agents with unstable output format cannot be called reliably.
What You Do NOT Do — explicit non-goals. Keeps scope creep out. Each prohibition pairs with a redirect (principle 05).

主体是agent的系统提示词——它从零开始，无对话上下文。结构如下：

你是一名{角色} —— 一行角色声明。
你应首先阅读的内容 —— 1–3个定位文件（
```
src/...
```
、
```
docs/...
```
）。agent开始前会对这些文件执行
```
Read
```
操作。
你的工作方式 —— 分阶段或步骤的编号列表。每个阶段都有明确目标和交接点。
你需返回的报告 —— Markdown框架。输出格式不稳定的agent无法被可靠调用。
你不应做的事 —— 明确的非目标。防止范围蔓延。每个禁止项需对应一个重定向（原则05）。

Step 5: run the validator

步骤5：运行验证器

bash

bash skills/meta/create-or-audit-agent/lib/validate.sh .claude/agents/{agent-name}.md

Fix errors, especially: read-only-with-write-tools (hard error), angle brackets in description, name-matches-filename.

bash

bash skills/meta/create-or-audit-agent/lib/validate.sh .claude/agents/{agent-name}.md

修复错误，尤其是：只读agent却包含写入工具（严重错误）、描述中存在尖括号、名称与文件名不匹配。

Step 6: smoke test

步骤6：冒烟测试

Invoke the agent manually with a representative query. The report should land in the exact format from "What You Report Back." If it doesn't, the system prompt needs tightening.

使用代表性查询手动调用agent。报告应完全符合“你需返回的报告”中指定的格式。若不符合，需收紧系统提示词。

Mode 2 — audit an existing agent

模式2 —— 审核现有代理

Step 1: structural

步骤1：结构检查

bash

bash skills/meta/create-or-audit-agent/lib/validate.sh path/to/agent.md

bash

bash skills/meta/create-or-audit-agent/lib/validate.sh path/to/agent.md

Step 2: five gates

步骤2：五项检查门限

Gate 1 — least privilege. Does the agent have only the tools it demonstrably uses? If

Bash

is listed but the body never runs a command, remove it.

Gate 2 — read-only intent. If the description sounds review/analyze/audit, the tools list must NOT contain

Write

Edit

. Validator errors on this.

Gate 3 — orientation. The body names ≥1 file the agent should read first. An agent that opens with "Find all the X" without naming where starts with a codebase-wide grep — wasteful.

Gate 4 — output format. Is there a report skeleton the caller can rely on? If not, add one.

Gate 5 — portability. Remove project-specific names from the library version. Concrete project paths stay in the project's

.claude/agents/

— not here.

门限1 —— 最小权限。 agent是否仅拥有其实际使用的工具？如果列出了

Bash

但主体从未执行命令，请移除它。

门限2 —— 只读意图。 如果描述涉及评审/分析/审计，工具列表中不得包含

Write

或

Edit

。验证器会对此报错。

门限3 —— 定位引导。 主体中需指定至少一个agent应首先阅读的文件。如果agent直接以“查找所有X”开头却未指定位置，会触发全代码库范围的grep——这是低效的。

门限4 —— 输出格式。 是否存在调用方可依赖的报告框架？如果没有，请添加。

门限5 —— 可移植性。 从库版本中移除项目特定名称。具体项目路径应保留在项目的

.claude/agents/

中——而非此处。

Step 3: report

步骤3：生成报告

markdown

undefined

markdown

undefined

Agent Audit: {agent-name}

Agent审核：{agent-name}

Verdict: APPROVE | REVISE | REJECT

结论：通过 | 修改 | 拒绝

Gate results

门限检查结果

Gate	Result	Notes
1. Least privilege	...	...
2. Read-only enforced	...	...
3. Orientation	...	...
4. Output format	...	...
5. Portability	...	...

门限	结果	备注
1. 最小权限	...	...
2. 只读强制	...	...
3. 定位引导	...	...
4. 输出格式	...	...
5. 可移植性	...	...

Proposed revisions

建议修改

...

undefined

...

undefined

Verify

验证

bash

bash skills/meta/create-or-audit-agent/lib/validate.sh .claude/agents/{name}.md

bash

bash skills/meta/create-or-audit-agent/lib/validate.sh .claude/agents/{name}.md

Expected: VERDICT: PASS

预期结果：VERDICT: PASS

Smoke: invoke the agent. Output should match the declared format.

冒烟测试：调用agent。输出应与声明的格式匹配。

undefined

undefined

Common Mistakes

常见错误

Mistake	Correction
Write agent that should be a skill	Agents are for analysis; skills take actions. Move to `skills/workflow/` and use a concrete verb in the name.
Reviewer agent with Write/Edit tools	Remove them. Read-only reviewers must stay read-only — validator enforces.
Agent body is 10 lines of "do your best"	Agents start cold. Spell out the exact procedure and the exact report shape, or every invocation produces different output.
Description without "Do NOT use for"	Add the counter-scenario pointing at a sibling agent. Without it, the router over-matches.

错误	修正方案
本应是skill却写成了agent	Agents用于分析；skills用于执行操作。将其移至 `skills/workflow/` ，并在名称中使用具体动词。
审核类agent包含Write/Edit工具	移除这些工具。只读审核类agent必须保持只读——验证器会强制执行此规则。
Agent主体仅用10行“尽力而为”的描述	Agents从零开始。需明确写出精确流程和报告格式，否则每次调用都会产生不同输出。
描述中缺少“请勿用于”说明	添加指向同类agent的反场景说明。没有此项，路由会过度匹配。