agent-conventions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Conventions

Agent 规范

Apply these conventions when creating or modifying AI agent definitions.

创建或修改AI Agent定义时需遵循以下规范。

Dispatch

触发逻辑

$ARGUMENTS	Action
Active (auto-invoked when working on agent files)	Apply all conventions below
Empty	Display convention summary
`check`	Run validation checks only

$ARGUMENTS	动作
激活（处理Agent文件时自动触发）	应用下述所有规范
空	展示规范摘要
`check`	仅运行验证检查

References

参考文件

File	Purpose
`references/readme-template.md`	Template for agent README.md index entries

文件	用途
`references/readme-template.md`	Agent README.md索引条目的模板

Conventions

规范内容

Required Frontmatter

必填 Frontmatter

Every agent file must include these fields in YAML frontmatter:

```
name
```
-- kebab-case, must match filename without
```
.md
```
```
description
```
-- non-empty, describes the agent's purpose

每个Agent文件的YAML frontmatter中必须包含以下字段：

```
name
```
-- kebab-case格式，必须与去掉
```
.md
```
后缀的文件名完全一致
```
description
```
-- 非空，描述Agent的用途

Optional Frontmatter

可选 Frontmatter

```
tools
```
-- comma-separated tool allowlist (default: all)
```
disallowedTools
```
-- comma-separated tool denylist
```
model
```
--
```
sonnet
```
|
```
opus
```
|
```
haiku
```
|
```
inherit
```
(default:
```
inherit
```
)

permissionMode

default

acceptEdits

delegate

dontAsk

bypassPermissions

plan

```
maxTurns
```
-- integer cap on agentic turns
```
skills
```
-- list of skills preloaded into agent context
```
mcpServers
```
-- list of MCP servers available to this agent
```
memory
```
--
```
user
```
|
```
project
```
|
```
local
```
```
hooks
```
-- lifecycle hooks scoped to this agent

Memory field conventions:

Choose the narrowest memory scope:
```
local
```
for temporary insights,
```
project
```
for shared patterns,
```
user
```
for cross-project preferences
Keep memory entrypoint files under 200 lines — content beyond this is truncated at load time
Organize memory by topic (e.g.,
```
debugging.md
```
,
```
api-patterns.md
```
), not chronologically
Use MEMORY.md as the index file; create separate topic files for detailed notes

```
tools
```
-- 逗号分隔的工具允许列表（默认：允许所有工具）
```
disallowedTools
```
-- 逗号分隔的工具禁止列表
```
model
```
--
```
sonnet
```
|
```
opus
```
|
```
haiku
```
|
```
inherit
```
（默认：
```
inherit
```
）

permissionMode

default

acceptEdits

delegate

dontAsk

bypassPermissions

plan

```
maxTurns
```
-- Agent运行轮次的整数上限
```
skills
```
-- 预加载到Agent上下文的技能列表
```
mcpServers
```
-- 该Agent可使用的MCP服务器列表
```
memory
```
--
```
user
```
|
```
project
```
|
```
local
```
```
hooks
```
-- 该Agent的生命周期钩子

Memory字段规范：

选择范围最窄的内存作用域：
```
local
```
用于临时洞察，
```
project
```
用于共享模式，
```
user
```
用于跨项目偏好
内存入口文件需保持在200行以内 -- 超出部分会在加载时被截断
按主题组织内存内容（例如
```
debugging.md
```
、
```
api-patterns.md
```
），而非按时间排序
使用MEMORY.md作为索引文件；为详细笔记创建单独的主题文件

Naming

命名规范

All agent names use kebab-case:
```
^[a-z0-9][a-z0-9-]*$
```
Filename (without
```
.md
```
) must match the
```
name
```
frontmatter field exactly
No consecutive hyphens, no leading/trailing hyphens

所有Agent名称使用kebab-case格式：
```
^[a-z0-9][a-z0-9-]*$
```
文件名（去掉
```
.md
```
后缀）必须与frontmatter中的
```
name
```
字段完全匹配
不得使用连续连字符，不得有前导/尾随连字符

README Index Requirement

README索引要求

When defining a new agent at any level:

```
~/.claude/agents/
```
```
.claude/agents/
```
(project-level)
Project-local agent directories

Update the corresponding

README.md

index in the same directory:

Add a row to the index table with agent name, description, and key fields
Add a description section with usage details
Keep the table sorted alphabetically by name

在任意层级定义新Agent时：

```
~/.claude/agents/
```
```
.claude/agents/
```
（项目层级）
项目本地Agent目录

需要更新同目录下对应的

README.md

索引：

在索引表格中添加一行，包含Agent名称、描述和关键字段
添加包含使用细节的描述章节
保持表格按名称字母顺序排序

Body Content

正文内容

Write the system prompt in imperative voice ("Check the logs" not "Checks the logs")
Keep agent definitions focused on a single responsibility
Reference skills by name rather than inlining their content

系统提示词使用祈使语气（例如“检查日志”而非“会检查日志”）
Agent定义需聚焦单一职责
按名称引用技能，而非直接内嵌技能内容

Critical Rules

关键规则

Always update the README.md index when adding or modifying an agent
Name every agent in kebab-case matching its filename exactly
Include both
```
name
```
and
```
description
```
in frontmatter -- they are required
Never duplicate agent functionality -- check existing agents first
Keep agent system prompts under 500 lines for maintainability
Run
```
wagents validate
```
after any agent frontmatter change
Use imperative voice throughout the agent body text

Canonical terms (use these exactly):

```
agent
```
-- an AI agent definition file in
```
agents/
```
directory
```
frontmatter
```
-- YAML metadata between
```
---
```
delimiters
```
system prompt
```
-- the markdown body after frontmatter
```
index table
```
-- the markdown table in README.md listing all agents
```
kebab-case
```
-- lowercase words separated by hyphens

添加或修改Agent时始终更新README.md索引
所有Agent使用kebab-case命名，且与文件名完全匹配
frontmatter中必须包含
```
name
```
和
```
description
```
字段 -- 二者为必填项
切勿重复Agent功能 -- 先检查现有Agent是否已支持
为保证可维护性，Agent系统提示词需控制在500行以内
修改Agent frontmatter后需运行
```
wagents validate
```
Agent正文中全程使用祈使语气

标准术语（请严格按以下表述使用）：

```
agent
```
-- 存放在
```
agents/
```
目录下的AI Agent定义文件
```
frontmatter
```
-- 位于
```
---
```
分隔符之间的YAML元数据
```
system prompt
```
-- frontmatter之后的Markdown正文
```
index table
```
-- README.md中列出所有Agent的Markdown表格
```
kebab-case
```
-- 小写单词之间用连字符分隔的命名格式