normalize-agent-for-claude

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<EXTREMELY-IMPORTANT> Every rewrite decision must be tied to Claude Code's agent runtime.

Non-negotiable rules:

Read
```
references/claude-agent-runtime.md
```
before planning or rewriting.
Default to
```
--mode plan
```
unless the user explicitly asks for rewrite now.
Keep the body lean because the full markdown body becomes the agent system prompt.
Use frontmatter for runtime controls before adding more prose.
Never preload large skills into agent frontmatter unless they have already been slimmed and justified.

Never add skill-only frontmatter to an agent.

allowed-tools

argument-hint

arguments

when_to_use

disable-model-invocation

user-invocable

context

agent

shell

, and

paths

belong to skills, not agents.

</EXTREMELY-IMPORTANT>

<EXTREMELY-IMPORTANT> 每一项重写决策都必须与Claude Code的Agent运行时挂钩。

不可协商的规则：

在制定计划或进行重写前，先阅读
```
references/claude-agent-runtime.md
```
。
默认使用
```
--mode plan
```
模式，除非用户明确要求立即重写。
保持主体内容精简，因为完整的Markdown主体将成为Agent的系统提示语。
在添加更多描述性文字前，优先使用前置元数据（frontmatter）进行运行时控制。
除非已完成精简并具备充分理由，否则绝不要将大型Skill预加载到Agent的前置元数据中。
绝不要为Agent添加仅适用于Skill的前置元数据。
```
allowed-tools
```
、
```
argument-hint
```
、
```
arguments
```
、
```
when_to_use
```
、
```
disable-model-invocation
```
、
```
user-invocable
```
、
```
context
```
、
```
agent
```
、
```
shell
```
和
```
paths
```
属于Skill，而非Agent。

</EXTREMELY-IMPORTANT>

Normalize Agent For Claude

为Claude标准化Agent

Inputs

输入

```
$target
```
: Agent directory or direct path to
```
AGENT.md
```
```
$mode
```
: Optional.
```
plan
```
or
```
rewrite
```
. Default:
```
plan
```

```
$target
```
: Agent目录或
```
AGENT.md
```
的直接路径
```
$mode
```
: 可选参数。
```
plan
```
（计划）或
```
rewrite
```
（重写）。默认值：
```
plan
```

Goal

目标

Produce a Claude Code optimized agent that carries role identity and constraints cleanly, uses frontmatter intentionally, and avoids wasting prompt budget on procedural bulk that belongs in skills or shared rules.

生成适配Claude Code的优化Agent，使其清晰承载角色身份与约束，有意地使用前置元数据，避免在提示语中浪费预算存放属于Skill或共享规则的流程性冗余内容。

Step 1: Resolve the target

步骤1：确定目标对象

Accept either an agent directory or a direct
```
AGENT.md
```
path.
Normalize to the agent root and confirm
```
AGENT.md
```
exists.
Determine mode:
- ```
--mode rewrite
```
  means plan first, then rewrite in the same run
- missing mode means
```
plan
```
Inventory the current agent:
- line count of
```
AGENT.md
```
- existing frontmatter fields
- section map of the body
- obvious duplicated global policy or giant knowledge catalogs

Success criteria: You know the exact target agent, target mode, and the current prompt-shape risks.

接受Agent目录或
```
AGENT.md
```
的直接路径作为输入。
标准化为Agent根目录并确认
```
AGENT.md
```
存在。
确定模式：
- ```
--mode rewrite
```
  意味着先制定计划，再在同一次运行中完成重写
- 未指定模式时默认使用
```
plan
```
盘点当前Agent的情况：
- ```
AGENT.md
```
  的行数
- 已有的前置元数据字段
- 主体内容的章节结构
- 明显重复的全局策略或庞大的知识目录

成功标准：明确知晓目标Agent、目标模式以及当前提示语结构存在的风险。

Step 2: Load the Claude Code agent runtime anchors

步骤2：加载Claude Code Agent运行时锚点

Read

references/claude-agent-runtime.md

fully before making any recommendation.

Extract these constraints from the reference:

agent
```
description
```
becomes
```
whenToUse
```
the whole markdown body becomes the system prompt
Claude supports richer agent frontmatter than most custom agents use
agent
```
skills:
```
preloads full skill content
tool allow and deny lists are enforced at runtime
repo-wide project rules already have a separate instruction hierarchy
agent rewrites must use agent-native frontmatter only, not skill-native headers

If this repository contains

claude-code-source/

, use the exact source files named in the reference to verify unusual frontmatter or isolation decisions.

Success criteria: Every planned change is backed by specific Claude runtime behavior.

在提出任何建议前，完整阅读

references/claude-agent-runtime.md

。

从参考文档中提取以下约束条件：

Agent的
```
description
```
将变为
```
whenToUse
```
整个Markdown主体将成为系统提示语
Claude支持的Agent前置元数据比大多数自定义Agent使用的更丰富
Agent的
```
skills:
```
字段会预加载完整的Skill内容
工具允许列表和禁止列表在运行时会被强制执行
仓库级别的项目规则已有独立的指令层级
Agent重写必须仅使用Agent原生的前置元数据，而非Skill原生的头部信息

若此仓库包含

claude-code-source/

目录，请使用参考文档中指定的精确源文件来验证特殊的前置元数据或隔离决策。

成功标准：每一项计划中的变更都有Claude运行时行为的具体依据。

Step 3: Audit the current agent against Claude's runtime

步骤3：对照Claude运行时审计当前Agent

Evaluate the target agent using this checklist:

Identity vs procedure
- What content is true role identity? (role definition, expertise bullets, decision heuristics, domain knowledge, traits)
- What content is actually workflow and should live in skills? (step-by-step procedures, shell commands, templates, checklists)
- Role-specific expertise lists and decision heuristics are
```
IDENTITY
```
  — they stay in the body. Only move procedure into skills or references.
Prompt mass
- Which large sections exist only because the current agent is compensating for missing skills or shared rules?
Frontmatter opportunities
- Would
```
disallowedTools
```
  ,
```
skills
```
  ,
```
initialPrompt
```
  ,
```
hooks
```
  ,
```
permissionMode
```
  ,
```
maxTurns
```
  ,
```
background
```
  ,
```
memory
```
  , or
```
isolation
```
  improve runtime behavior?
- Are there any skill-only headers that must be removed or explicitly avoided?
Tool surface
- Is the tool list broader than the role actually needs?
Skill preload risk
- Would adding a skill to frontmatter create prompt bloat because the skill is still too large?
Instruction duplication
- Are repo-wide rules duplicated here even though Claude already loads project memory separately?

Classify each issue:

```
PROMPT
```
: body is too large or carries the wrong content
```
RUNTIME
```
: missing or misused Claude frontmatter
```
TOOLS
```
: tool exposure is too broad or too vague
```
DUPLICATION
```
: project policy is duplicated in agent body
```
EXTRACTION
```
: content should move into skills or references

Success criteria: You have a concrete, source-backed explanation of what should stay, move, or shrink.

使用以下 checklist 评估目标Agent：

身份与流程
- 哪些内容是真正的角色身份？（角色定义、专业技能要点、决策启发式规则、领域知识、特质）
- 哪些内容实际上是工作流程，应存放在Skill中？（分步流程、Shell命令、模板、检查清单）
- 角色专属的专业技能列表和决策启发式规则属于
```
IDENTITY
```
  （身份）——保留在主体中。仅将流程性内容迁移至Skill或参考文档。
提示语体量
- 哪些大型章节的存在仅仅是因为当前Agent需要弥补缺失的Skill或共享规则？
前置元数据优化机会
- 使用
```
disallowedTools
```
  、
```
skills
```
  、
```
initialPrompt
```
  、
```
hooks
```
  、
```
permissionMode
```
  、
```
maxTurns
```
  、
```
background
```
  、
```
memory
```
  或
```
isolation
```
  是否能改善运行时行为？
- 是否存在任何必须移除或明确避免的仅适用于Skill的头部信息？
工具范围
- 工具列表是否超出了角色实际需要的范围？
Skill预加载风险
- 将Skill添加到前置元数据中是否会因Skill仍过大而导致提示语膨胀？
指令重复
- 仓库级规则是否在此处重复出现，即便Claude已单独加载项目记忆？

对每个问题进行分类：

```
PROMPT
```
：主体内容过大或包含不合适的内容
```
RUNTIME
```
：缺少或误用了Claude前置元数据
```
TOOLS
```
：工具暴露范围过宽或过于模糊
```
DUPLICATION
```
：项目策略在Agent主体中重复出现
```
EXTRACTION
```
：内容应迁移至Skill或参考文档

成功标准：对哪些内容应保留、迁移或精简有具体的、基于源文件的解释。

Step 4: Write the per-agent DAG plan

步骤4：编写单Agent DAG计划

Create both of these artifacts:

.ulpi/plans/agents/<agent-name>-normalize-for-claude.md

.ulpi/plans/agents/<agent-name>-normalize-for-claude.json

The plan must include:

Current state
- line count
- current frontmatter
- oversized sections
- duplicated global policy
Claude runtime findings
- each finding mapped to source references from
```
references/claude-agent-runtime.md
```
Target state
- final frontmatter shape
- body sections to keep, delete, or move
- skills or references the agent should depend on instead
DAG tasks
- frontmatter rewrite
- prompt-body reduction
- procedure extraction into skills or references
- tool-surface tightening
- validation
Guardrails
- what identity must stay
- what must move out
- what must not be preloaded
Validation
- concrete checks to confirm the final agent is structurally sound

Each DAG task should include:

```
id
```
```
title
```
```
rationale
```
```
filesToModify
```
```
filesToCreate
```
```
dependencies
```
```
validation
```

Success criteria: The markdown and JSON plans describe the same safe sequence of work.

创建以下两个产物：

.ulpi/plans/agents/<agent-name>-normalize-for-claude.md

.ulpi/plans/agents/<agent-name>-normalize-for-claude.json

计划必须包含：

当前状态
- 行数
- 当前的前置元数据
- 过大的章节
- 重复的全局策略
Claude运行时发现
- 每个发现都映射到
```
references/claude-agent-runtime.md
```
  中的源引用
目标状态
- 最终的前置元数据结构
- 主体中需保留、删除或迁移的章节
- Agent应依赖的Skill或参考文档
DAG任务
- 前置元数据重写
- 提示语主体精简
- 流程内容提取至Skill或参考文档
- 工具范围收紧
- 验证
防护规则
- 哪些身份信息必须保留
- 哪些内容必须移出
- 哪些内容不得预加载
验证
- 确认最终Agent结构合理的具体检查项

每个DAG任务应包含：

```
id
```
```
title
```
```
rationale
```
（理由）
```
filesToModify
```
（需修改的文件）
```
filesToCreate
```
（需创建的文件）
```
dependencies
```
（依赖项）
```
validation
```
（验证方式）

成功标准：Markdown和JSON计划描述的是同一套安全的工作序列。

Step 5: Rewrite only if requested

步骤5：仅在请求时进行重写

If mode is

plan

, stop after writing the DAG artifacts.

If mode is

rewrite

Rewrite the frontmatter first.
Reduce the body to:
- role and expertise (specific domain knowledge and capability claims)
- scope
- decision heuristics (how to choose between approaches)
- failure boundaries
- output contract
- brief skill handoff guidance
Move repeated procedures and large examples out of the agent. Keep role expertise bullets and decision heuristics — these are identity, not procedure.
Add Claude-native frontmatter only when it changes runtime behavior materially.
Keep the result role-specific, not generic.

Preferred rewrite outcomes:

agent
```
description
```
becomes a strong
```
whenToUse
```
body becomes much smaller and more identity-focused
```
disallowedTools
```
and tighter
```
tools
```
are used where appropriate
```
skills:
```
is used sparingly and only for already-slim skills
duplicated project rules are removed from the body
no skill-only headers are introduced into the rewritten agent

Success criteria: The rewritten agent is thinner, more precise, and better aligned to Claude's runtime model.

若模式为

plan

，则在生成DAG产物后停止操作。

若模式为

rewrite

：

先重写前置元数据。
将主体内容精简为：
- 角色与专业技能（特定领域知识与能力声明）
- 范围
- 决策启发式规则（如何在不同方案间选择）
- 失败边界
- 输出约定
- 简短的Skill交接指引
将重复的流程和大型示例从Agent中移出。保留角色专业技能要点和决策启发式规则——这些属于身份信息，而非流程内容。
仅当能实质性改变运行时行为时，才添加Claude原生的前置元数据。
确保结果具有角色针对性，而非通用化。

首选重写成果：

Agent的
```
description
```
变为清晰明确的
```
whenToUse
```
主体内容大幅精简且更聚焦于身份信息
在合适的场景使用
```
disallowedTools
```
和更严格的
```
tools
```
设置
谨慎使用
```
skills:
```
，仅用于已精简的Skill
从主体中移除重复的项目规则
不会在重写后的Agent中引入仅适用于Skill的头部信息

成功标准：重写后的Agent更精简、更精准，且与Claude的运行时模型更契合。

Step 6: Validate the result

步骤6：验证结果

After planning or rewriting:

Re-read the final
```
AGENT.md
```
.
Confirm the frontmatter reflects real runtime decisions.
Confirm the body is mostly identity, scope, heuristics, and boundaries.
Confirm no skill-only headers were introduced.
Confirm large procedure blocks are gone or explicitly moved.
Confirm the summary names the Claude source anchors that drove the major changes.

Success criteria: The output can be used immediately without re-interpreting why the structure changed.

在制定计划或完成重写后：

重新阅读最终的
```
AGENT.md
```
。
确认前置元数据反映了真实的运行时决策。
确认主体内容主要包含身份信息、范围、启发式规则和边界。
确认未引入仅适用于Skill的头部信息。
确认大型流程块已移除或明确迁移。
确认总结中指明了驱动主要变更的Claude源文件锚点。

成功标准：输出无需重新解释结构变更的原因即可直接使用。

Output Contract

输出约定

Always report:

```
Agent:
```
target path and normalized root
```
Mode:
```
```
plan
```
or
```
rewrite
```
```
Top runtime issues:
```
the highest-value Claude mismatches
```
Artifacts:
```
exact plan or rewritten file paths
```
Guardrails applied:
```
3 to 5 bullets tied to Claude runtime behavior

If rewrite mode was used, also report:

which sections were removed or moved
which frontmatter fields were added, removed, or intentionally omitted

始终报告：

```
Agent:
```
目标路径和标准化根目录
```
Mode:
```
```
plan
```
或
```
rewrite
```
```
Top runtime issues:
```
最具价值的Claude适配不匹配点
```
Artifacts:
```
精确的计划或重写文件路径
```
Guardrails applied:
```
3至5条与Claude运行时行为相关的防护规则要点

若使用了重写模式，还需报告：

哪些章节被移除或迁移
哪些前置元数据字段被添加、移除或有意省略