repair-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Repair

Agent修复

Audit and improve an existing Claude Code agent against a gold standard. Unlike create-agent (which generates from scratch), this skill diagnoses violations and identifies gaps — what is broken, what is missing, and what would raise quality. The output is a structured improvement plan covering all dimensions of agent design.

对照黄金标准审计并优化现有的Claude Code Agent。与create-agent（从零生成Agent）不同，本Skill会诊断违规问题并识别差距——包括哪些部分存在故障、哪些内容缺失，以及哪些方面可以提升质量。输出结果是一份涵盖Agent设计所有维度的结构化改进方案。

Phase 1: Load the Agent

阶段1：加载Agent

The agent file at

$ARGUMENTS

is loaded inline:

@$ARGUMENTS

Note the directory from

$ARGUMENTS

to verify it lives in

agents/

(not

skills/

). Identify any

skills:

preloads listed in the frontmatter above.

If the file is a

SKILL.md

or lives in a

skills/

directory, decline and tell the user to use

repair-skill

instead. If the path is missing or ambiguous, use AskUserQuestion to resolve before proceeding.

Load the following reference files before Phase 2:

```
${CLAUDE_PLUGIN_ROOT}/skills/repair-agent/references/agent-anatomy.md
```
— gold standard for system prompt structure, voice conventions, size invariants, naming,
```
skills:
```
preload pattern, and the gap analysis checklist. Required for Dimensions 3, 5, 6, and 7.
```
${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/agent-frontmatter.md
```
— complete frontmatter field catalog, valid values, tool selection framework, color semantics, and execution modifiers. Required for Dimensions 1 and 2.

Proceed to Phase 2 when: agent file is confirmed in scope and reference files are loaded.

将

$ARGUMENTS

路径下的Agent文件内联加载：

@$ARGUMENTS

注意从

$ARGUMENTS

获取的目录，确认该文件位于

agents/

目录（而非

skills/

目录）。识别上述前置内容中列出的所有

skills:

预加载项。

如果文件是

SKILL.md

或位于

skills/

目录下，请拒绝处理并告知用户使用

repair-skill

。如果路径缺失或不明确，请使用AskUserQuestion工具解决后再继续。

进入阶段2前，请加载以下参考文件：

```
${CLAUDE_PLUGIN_ROOT}/skills/repair-agent/references/agent-anatomy.md
```
——系统提示结构、语气规范、大小限制、命名规则、
```
skills:
```
预加载模式以及差距分析清单的黄金标准。适用于维度3、5、6、7。
```
${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/agent-frontmatter.md
```
——完整的前置字段目录、有效值、工具选择框架、颜色语义和执行修饰符。适用于维度1和2。

确认Agent文件在处理范围内且参考文件已加载后，进入阶段2。

Phase 2: Audit

阶段2：审计

Run each dimension independently. For each finding record: the dimension code, what is wrong or missing, which principle it violates or which gold standard it falls short of, and the specific change required. Proceed to Phase 3 when all 7 dimensions are evaluated.

Finding types:

Violation — something present that contradicts a rule
Gap — something absent that would improve the agent against the gold standard
Improvement — something that works but could be meaningfully tightened

Severity:

critical — breaks triggering or causes the agent to malfunction on every invocation
major — degrades trigger accuracy, system prompt reliability, or autonomy safety
minor — polish; the agent works but isn't as good as it could be

独立评估每个维度。对于每个发现，记录：维度代码、问题或缺失内容、违反的原则或未达到的黄金标准，以及具体的修改要求。完成所有7个维度的评估后进入阶段3。

发现类型：

违规——存在违反规则的内容
差距——缺少能让Agent达到黄金标准的内容
优化点——当前内容可用，但可以进一步完善

严重程度：

critical（严重）——导致Agent触发失败或每次调用都出现故障
major（主要）——降低触发准确性、系统提示可靠性或自主执行安全性
minor（次要）——仅需优化；Agent可正常工作，但未达到最佳状态

Dimension 1 — Description Quality

维度1——描述质量

The description is read by the routing model to decide when to spawn this agent. It is the primary trigger mechanism and is always in context. Audit for violations and gaps.

Violations:

Framing: Does it start with "Use this agent when..."? Critical if wrong.
Bloated description: Description should be a concise
```
>
```
folded scalar, 50-70 tokens. No
```
<example>
```
blocks — they waste context without improving routing. Major if examples present or description exceeds ~80 tokens.
Scalar type: Should use
```
>
```
(folded). Minor if using
|
without XML blocks.
Proactive hint missing: For agents that fire after events, does the description include "Recommended PROACTIVELY after..."? Minor if proactive intent without the hint.

Gaps:

Negative trigger: If adjacent agents exist with overlapping scope, does the description state when NOT to trigger? Minor if adjacent agent exists without disambiguation.

描述内容由路由模型读取，用于决定何时启动该Agent。这是主要的触发机制，且始终处于上下文环境中。需同时审计违规问题和差距。

违规情况：

框架问题： 是否以“Use this agent when...”开头？错误时属于严重级别。
描述冗余： 描述应为简洁的
```
>
```
折叠标量，长度为50-70个token。不应包含
```
<example>
```
块——这些块会浪费上下文且对路由无帮助。如果包含示例或描述超过约80个token，属于主要级别。
标量类型： 应使用
```
>
```
（折叠格式）。如果使用
|
且无XML块，属于次要级别。
缺少主动提示： 对于事件触发型Agent，描述是否包含“Recommended PROACTIVELY after...”？如果有主动触发意图但缺少该提示，属于次要级别。

差距情况：

负向触发条件： 如果存在范围重叠的相邻Agent，描述是否说明何时不应触发？如果存在相邻Agent但未明确区分，属于次要级别。

Dimension 2 — Frontmatter Modifiers

维度2——前置修饰符

Refer to

agent-frontmatter.md

for the complete field catalog, tool selection framework, and color semantics. Omitting a field is not an error when the default applies — audit for mismatches (violations) and missing configuration that would improve the agent (gaps).

Violations:

Does
```
tools
```
include unscoped
```
Bash
```
for an agent that doesn't need full shell access? Agents run autonomously with no human in the loop — unrestricted Bash is the highest blast-radius grant. Major.
Is
```
model: opus
```
set for a task sonnet handles? Cost scales directly per spawn. Major.
Is
```
isolation: worktree
```
set without the agent performing git-state modifications? Unnecessary isolation adds overhead. Minor.
Does
```
disallowedTools
```
block a tool the system prompt requires? Critical.

Gaps:

Is
```
color
```
absent? Visual identity in the UI helps users track which agent is active in multi-agent workflows. Minor.
Is
```
tools
```
absent for a read-only analysis agent? Least-privilege requires an explicit allowlist for autonomous agents — omitting it grants full access when restricted access would suffice. Major for analysis-only agents.
Is
```
maxTurns
```
absent for a task with a predictable completion horizon? Unbounded agents can loop on ambiguous input. Minor for bounded tasks.
Is
```
skills
```
absent for an agent with domain-specific knowledge needs? Embedding domain reference directly in the system prompt inflates every spawn;
```
skills:
```
defers it. Major if system prompt exceeds 300 lines of embedded reference data.
Is
```
isolation: worktree
```
absent for an agent that modifies files in the working tree? Without isolation, modifications are immediate and irreversible during the run. Major.
Is
```
memory
```
absent for an agent that would benefit from cross-session learning? Agents that review code, audit patterns, or accumulate project knowledge should use persistent memory (
```
project
```
recommended default). If
```
memory
```
is set, does the system prompt include memory maintenance instructions? Without them, the agent won't proactively update its knowledge base. Major if the agent's domain involves pattern accumulation.
Is
```
effort
```
absent for a cost-sensitive or complexity-varying agent? Fast classification tasks benefit from
```
effort: low
```
; deep reasoning tasks from
```
effort: high
```
. Minor.
Is
```
initialPrompt
```
absent for a session-mode agent designed for
```
--agent
```
use? Without it, the agent waits for user input instead of self-starting. Minor if applicable.

参考

agent-frontmatter.md

获取完整的字段目录、工具选择框架和颜色语义。当默认值适用时，省略字段不属于错误——需审计不匹配项（违规）和缺失的优化配置（差距）。

违规情况：

```
tools
```
是否包含未限定范围的
```
Bash
```
，而该Agent并不需要完整的Shell访问权限？Agent会自主运行且无人工干预——无限制的Bash权限风险最高。主要级别。
是否为Sonnet模型可处理的任务设置了
```
model: opus
```
？成本与每次启动直接相关。主要级别。
是否在Agent未执行Git状态修改的情况下设置了
```
isolation: worktree
```
？不必要的隔离会增加开销。次要级别。
```
disallowedTools
```
是否阻止了系统提示所需的工具？严重级别。

差距情况：

是否缺少
```
color
```
字段？UI中的视觉标识有助于用户在多Agent工作流中跟踪活跃Agent。次要级别。
只读分析型Agent是否缺少
```
tools
```
字段？自主Agent的最小权限原则要求明确的允许列表——省略该字段会授予完全访问权限，而实际上仅需受限访问即可。分析型Agent属于主要级别。
具有可预测完成周期的任务是否缺少
```
maxTurns
```
字段？无限制的Agent可能在处理模糊输入时陷入循环。有界任务属于次要级别。
有领域特定知识需求的Agent是否缺少
```
skills
```
字段？将领域参考直接嵌入系统提示会增加每次启动的上下文负担；
```
skills:
```
字段可延迟加载这些内容。如果系统提示包含超过300行嵌入式参考数据，属于主要级别。
修改工作区文件的Agent是否缺少
```
isolation: worktree
```
字段？无隔离情况下，运行期间的修改会立即生效且不可撤销。主要级别。
可从跨会话学习中受益的Agent是否缺少
```
memory
```
字段？审查代码、审计模式或积累项目知识的Agent应使用持久化内存（推荐默认值为
```
project
```
）。如果设置了
```
memory
```
，系统提示是否包含内存维护说明？缺少说明的话，Agent无法主动更新其知识库。如果Agent的领域涉及模式积累，属于主要级别。
对成本敏感或复杂度可变的Agent是否缺少
```
effort
```
字段？快速分类任务适合
```
effort: low
```
；深度推理任务适合
```
effort: high
```
。次要级别。
为
```
--agent
```
使用场景设计的会话模式Agent是否缺少
```
initialPrompt
```
字段？缺少该字段的话，Agent会等待用户输入而非自行启动。适用时属于次要级别。

Dimension 3 — System Prompt Voice

维度3——系统提示语气

The markdown body of an agent file is its system prompt. Voice, persona, and structural conventions determine whether the agent behaves as a specialist or a generic assistant. Refer to

agent-anatomy.md

for voice conventions and the gold standard structure.

Violations:

First-person language: Does the body contain "I will", "I'll", "I am", or any first-person construction? Critical — the system prompt is an address to the agent; first-person reads as the agent narrating its own plan rather than following an instruction. Both second-person ("You will analyze...") and bare imperatives in process steps ("Analyze...") are correct conventions — only first-person breaks the contract.
Third-person self-description: Does the body refer to the agent in third person ("This agent will analyze...", "The agent should...")? Major — the body must address the agent directly, not describe it from the outside.
No persona statement: Does the first sentence establish role and domain? Without one, the agent has no expert identity to shape downstream decisions. Major.
No numbered process steps: Unstructured prose instructions produce variable behavior across invocations. Major if unstructured.
No output format: Is there an Output Format section? Callers — human or orchestrating skill — need predictable structure to consume results. Major if absent.

Gaps:

No edge cases: Predefined handling prevents mid-task failures that cost retries. Common cases: no input provided, ambiguous input, target missing, empty result. Minor.
Judgment steps without criteria: Steps like "analyze the situation" or "assess quality" without explicit criteria for what to consider and what constitutes a good outcome. Major per uncovered judgment step.

Agent文件的Markdown主体是其系统提示。语气、角色和结构规范决定了Agent是作为专家还是通用助手运行。参考

agent-anatomy.md

获取语气规范和黄金标准结构。

违规情况：

第一人称表述： 主体是否包含“I will”“I'll”“I am”或任何第一人称结构？严重级别——系统提示是对Agent的指令；第一人称表述会让Agent叙述自身计划而非遵循指令。第二人称（“You will analyze...”）和流程步骤中的直接祈使句（“Analyze...”）是正确规范——只有第一人称会破坏指令契约。
第三人称自我描述： 主体是否以第三人称指代Agent（“This agent will analyze...”“The agent should...”）？主要级别——主体必须直接对Agent发出指令，而非从外部描述Agent。
缺少角色声明： 第一句是否明确了角色和领域？缺少的话，Agent没有专家身份来指导后续决策。主要级别。
无编号流程步骤： 非结构化的 prose 指令会导致每次调用的行为不一致。如果是非结构化内容，属于主要级别。
无输出格式： 是否有Output Format部分？调用者（人类或编排Skill）需要可预测的结构来处理结果。如果缺失，属于主要级别。

差距情况：

无边缘情况处理： 预定义的处理逻辑可避免导致重试的任务中途失败。常见情况：无输入、模糊输入、目标缺失、结果为空。次要级别。
无判断标准的步骤： 类似“分析情况”或“评估质量”的步骤未明确说明需考虑的因素和良好结果的判定标准。每个未明确的判断步骤属于主要级别。

Dimension 4 — Agentic vs Deterministic Split

维度4——智能型与确定性拆分

Load
${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/script-patterns.md
before auditing this dimension. The same five signal patterns apply to agents as to skills.

Agents mix LLM-guided reasoning (agentic) and deterministic operations. The split should be deliberate — see the Degrees of Freedom table in

agent-anatomy.md

Violations:

Inlined deterministic code: Code blocks that would be re-generated identically across invocations belong in
```
scripts/
```
, not in the system prompt. Major.
Vague script references: "Run the validation script if needed" — no path, no trigger condition, no output interpretation. Minor.

Gaps — apply the five signal patterns to each process step:

Signal 1 (Repeated Generation): Same structure, different parameters → script. Major.
Signal 2 (Unclear Tool Choice): Fragile multi-tool sequence → script the procedure. Major.
Signal 3 (Rigid Contract): Can write
```
--help
```
for this step → CLI candidate. Minor.
Signal 4 (Dual-Use): Useful outside the agent → design as proper CLI. Minor.
Signal 5 (Consistency Critical): Must produce identical output → script, not LLM. Major.

审计此维度前，请加载
${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/script-patterns.md
。适用于Skill的五种信号模式同样适用于Agent。

Agent混合了LLM引导的推理（智能型）和确定性操作。拆分需经过审慎考虑——请参考

agent-anatomy.md

中的自由度表。

违规情况：

内联确定性代码： 每次调用都会生成相同内容的代码块应放在
```
scripts/
```
目录下，而非系统提示中。主要级别。
模糊的脚本引用： 类似“必要时运行验证脚本”的表述——无路径、无触发条件、无输出解释。次要级别。

差距情况——对每个流程步骤应用五种信号模式：

信号1（重复生成）： 结构相同、参数不同 → 应使用脚本。主要级别。
信号2（工具选择模糊）： 脆弱的多工具序列 → 应对流程编写脚本。主要级别。
信号3（严格契约）： 可为该步骤编写
```
--help
```
文档 → 适合CLI工具。次要级别。
信号4（双重用途）： 在Agent外也有用 → 应设计为正式CLI工具。次要级别。
信号5（一致性关键）： 必须生成相同输出 → 使用脚本，而非LLM。主要级别。

Dimension 5 — System Prompt Efficiency

维度5——系统提示效率

Every line in the agent body is loaded into context every time the agent is spawned. Domain reference data and lookup tables belong in

skills:

preloads, not embedded inline. Refer to size invariants in

agent-anatomy.md

to calibrate severity.

Violations:

Hedging language: "You might want to consider", "generally speaking", "you could try". Replace with direct imperatives. Minor per instance.
Routing guidance in body: Any section explaining when to trigger the agent belongs in the
```
description
```
field. The body loads only after triggering — routing guidance there never informs the triggering decision and burns context on every spawn. Major.
Embedded domain reference > 100 lines: Lookup tables, option catalogs, field definitions only needed for specific steps inflate every invocation. Use
```
skills:
```
preload instead. Major.
System prompt over ~400 lines: Signals embedded content that belongs in
```
skills:
```
preloads. Major.

Gaps:

Could
skills:
reduce system prompt size? Identify sections only needed for specific sub-tasks. Major if system prompt > 300 lines with extractable content.

Agent主体中的每一行内容在每次启动时都会加载到上下文中。领域参考数据和查找表应放在

skills:

预加载项中，而非内联嵌入。参考

agent-anatomy.md

中的大小限制来确定严重程度。

违规情况：

模糊表述： “You might want to consider”“generally speaking”“you could try”等表述。应替换为直接的祈使句。每个实例属于次要级别。
主体中的路由指引： 任何解释何时触发Agent的内容都应放在
```
description
```
字段中。主体仅在触发后加载——放在主体中的路由指引永远无法影响触发决策，且会在每次启动时浪费上下文。主要级别。
嵌入式领域参考超过100行： 仅特定步骤需要的查找表、选项目录、字段定义会增加每次调用的负担。应使用
```
skills:
```
预加载项替代。主要级别。
系统提示超过约400行： 表明存在应放在
```
skills:
```
预加载项中的嵌入式内容。主要级别。

差距情况：

是否可通过
skills:
减少系统提示大小？识别仅特定子任务需要的内容。如果系统提示超过300行且存在可提取内容，属于主要级别。

Dimension 6 — Process Completeness

维度6——流程完整性

A complete agent process is sequential, has explicit steps, and defines what "done" looks like at each step. Audit for broken workflow and for missing structure that would help.

Violations:

No numbered steps: Prose description of process without step numbers — the agent cannot track progress or know which step it's in. Major.
Steps without exit conditions: Multi-step processes need explicit completion criteria per step. Without them, the agent may loop or skip prematurely. Major if missing.
Half-thought steps: Phases that describe intent without specifying action or evaluation criteria. Major per uncovered step.
No input handling: What does the agent do if input is missing, ambiguous, or malformed? Minor if unaddressed.

Gaps:

No output format section: Callers cannot reliably consume implicit output structure. Major if agent returns structured data.
No validation checklist: A self-check at the end of the process catches errors that prose instructions miss. Minor.

完整的Agent流程应是顺序执行的，具有明确的步骤，并定义每个步骤的“完成”状态。审计是否存在工作流中断以及有助于提升的缺失结构。

违规情况：

无编号步骤： 用 prose 描述流程但无步骤编号——Agent无法跟踪进度或知晓当前所处步骤。主要级别。
步骤无退出条件： 多步骤流程需要每个步骤的明确完成标准。缺少的话，Agent可能陷入循环或提前跳过步骤。如果缺失，属于主要级别。
不完整的步骤： 仅描述意图但未指定操作或评估标准的阶段。每个不完整步骤属于主要级别。
无输入处理： Agent在输入缺失、模糊或格式错误时应如何处理？如果未说明，属于次要级别。

差距情况：

无输出格式部分： 调用者无法可靠处理隐含的输出结构。如果Agent返回结构化数据，属于主要级别。
无验证清单： 流程末尾的自我检查可捕捉 prose 指令遗漏的错误。次要级别。

Dimension 7 — Anatomy Completeness

维度7——结构完整性

Agents are typically single files, but their ecosystem includes

skills:

preloads and optional companion scripts. This dimension asks whether declared structure matches needs.

Refer to the Gap Analysis Checklist in

agent-anatomy.md

for each absent element.

Violations:

skills:
listed in frontmatter but not referenced in process: Dead preloads inflate context on every spawn without being used. Minor.
Naming violates conventions: Generic terms (helper, assistant, agent), underscores, over 50 characters, leading/trailing hyphens. Minor.

Gaps:

No
skills:
preload for domain-heavy agents: System prompt embeds a large reference catalog that could be externalized. Major if body > 300 lines.
No companion scripts for consistency-critical steps: Process describes steps that must produce identical output for identical inputs. Major.
color
absent: No visual identity in multi-agent UI contexts. Minor.
No
memory
for pattern-accumulating agents: Agent reviews code, audits quality, or accumulates project knowledge but has no persistent memory configured. Major if the agent's value increases with accumulated context.

Agent通常是单个文件，但其生态系统包括

skills:

预加载项和可选的配套脚本。此维度检查声明的结构是否符合需求。

参考

agent-anatomy.md

中的差距分析清单，检查每个缺失元素。

违规情况：

前置内容中列出
skills:
但流程中未引用：无用的预加载项会增加每次启动的上下文负担但未被使用。次要级别。
命名违反规范： 使用通用术语（helper、assistant、agent）、下划线、超过50个字符、首尾有连字符。次要级别。

差距情况：

领域密集型Agent无
skills:
预加载项：系统提示嵌入了大量可外部化的参考目录。如果主体超过300行，属于主要级别。
一致性关键步骤无配套脚本： 流程描述的步骤必须为相同输入生成相同输出。主要级别。
缺少
color
字段：在多Agent UI环境中无视觉标识。次要级别。
模式积累型Agent无
memory
字段： Agent审查代码、审计质量或积累项目知识，但未配置持久化内存。如果Agent的价值随积累的上下文提升，属于主要级别。

Phase 3: Improvement Report

阶段3：改进报告

Present findings as a structured report. Split violations from gaps. See

${CLAUDE_PLUGIN_ROOT}/skills/repair-agent/examples/sample-repair.md

for a complete example of the report format and a before/after repair session.

AGENT IMPROVEMENT REPORT: <agent-name>
System prompt: [N] lines | Description: [N] tokens | Tools: [listed / unrestricted]

VIOLATIONS
──────────
CRITICAL
  [D1] Description does not start with "Use this agent when..." — routing model cannot
       match. Fix: rewrite opening as "Use this agent when [trigger conditions]."

MAJOR
  [D3] Body uses first-person throughout ("I will analyze...") — system prompt must be
       second-person because it is an address to the agent, not a narration of intent.
       Fix: rewrite as "Analyze the input and identify..." throughout.
  [D2] `tools` omitted for a read-only analysis agent — omission grants full tool access;
       least-privilege for autonomous agents requires an explicit allowlist.
       Fix: add tools block sequence (Read, Grep, Glob)

MINOR
  [D2] `color` not set — no visual identity in multi-agent UI.
       Fix: add color: blue (analysis/review semantic).

GAPS (what would improve this agent)
─────────────────────────────────────
MAJOR
  [D7] System prompt is 380 lines of embedded domain reference. Extract to a skill file
       and preload via `skills:` frontmatter to reduce per-spawn context cost.

MINOR
  [D6] No edge cases section — what happens when the agent receives no input?
       Improvement: add "Edge Cases: No input provided — ask the user to share the target."

Group violations by severity, then gaps by severity. For each: dimension code, what is wrong or missing, the principle it falls short of, the exact fix.

Ask: "Apply all critical and major items? Or select specific ones?"

Proceed to Phase 4 when the user has indicated which items to apply.

将发现整理为结构化报告，区分违规问题和差距。完整的报告格式示例及修复前后的会话示例请参考

${CLAUDE_PLUGIN_ROOT}/skills/repair-agent/examples/sample-repair.md

。

AGENT IMPROVEMENT REPORT: <agent-name>
System prompt: [N] lines | Description: [N] tokens | Tools: [listed / unrestricted]

VIOLATIONS
──────────
CRITICAL
  [D1] Description does not start with "Use this agent when..." — routing model cannot
       match. Fix: rewrite opening as "Use this agent when [trigger conditions]."

MAJOR
  [D3] Body uses first-person throughout ("I will analyze...") — system prompt must be
       second-person because it is an address to the agent, not a narration of intent.
       Fix: rewrite as "Analyze the input and identify..." throughout.
  [D2] `tools` omitted for a read-only analysis agent — omission grants full tool access;
       least-privilege for autonomous agents requires an explicit allowlist.
       Fix: add tools block sequence (Read, Grep, Glob)

MINOR
  [D2] `color` not set — no visual identity in multi-agent UI.
       Fix: add color: blue (analysis/review semantic).

GAPS (what would improve this agent)
─────────────────────────────────────
MAJOR
  [D7] System prompt is 380 lines of embedded domain reference. Extract to a skill file
       and preload via `skills:` frontmatter to reduce per-spawn context cost.

MINOR
  [D6] No edge cases section — what happens when the agent receives no input?
       Improvement: add "Edge Cases: No input provided — ask the user to share the target."

按严重程度分组违规问题，再按严重程度分组差距。对于每个条目：维度代码、问题或缺失内容、未达到的原则、具体修复方案。

询问用户：“是否应用所有严重和主要项？还是选择特定项？”

用户指示要应用的条目后，进入阶段4。

Phase 4: Apply Improvements

阶段4：应用改进

Apply confirmed items in order: critical violations → major violations → major gaps → minor violations → minor gaps.

For each item:

State what is being changed and why (principle reference, not just "you asked")
Make the edit
Confirm the change is consistent with surrounding content

按以下顺序应用确认的条目：严重违规→主要违规→主要差距→次要违规→次要差距。

对于每个条目：

说明修改内容及原因（参考原则，而非仅“按您要求”）
执行编辑
确认修改与周围内容一致

Explain Your Choices

解释您的选择

After applying:

What was changed and why — reference the principle: "Rewrote body as second-person because the system prompt is an address to the agent; first-person breaks the instruction- following contract"
What was added and why — "Added
```
tools
```
block sequence (Read, Grep, Glob) because this is a read-only agent and least-privilege for autonomous execution requires an explicit allowlist"
What was left unchanged and why — "Left
```
maxTurns
```
unset — task horizon is open-ended"
What remains for the user — items requiring domain knowledge to fill

Phase 4 is complete when all confirmed items are applied, explanation delivered, and the validation checklist passes.

应用完成后：

修改内容及原因——参考原则：“将主体改写为第二人称，因为系统提示是对Agent的指令；第一人称会破坏遵循指令的契约”
新增内容及原因——“添加
```
tools
```
块序列（Read、Grep、Glob），因为这是只读Agent，自主执行的最小权限原则要求明确的允许列表”
未修改内容及原因——“未设置
```
maxTurns
```
——任务周期是开放式的”
需用户完成的内容——需要领域知识填充的条目

当所有确认条目都已应用、完成解释且验证清单通过后，阶段4完成。

Validation

验证

After applying all improvements:

Run the structural validator:
bash
```
python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/scripts/validate_agent.py \
  <agent-file> --output json
```
Exit 0 = structure clean. Exit 1 = parse the
```
errors
```
array; report each entry's
```
field
```
,
```
message
```
, and
```
severity
```
before delivering final results.
Load
```
${CLAUDE_PLUGIN_ROOT}/skills/repair-agent/references/quality-checklist.md
```
and run the quality standards check followed by the item-by-item checklist. Report any failing items before delivering final results.

应用所有改进后：

运行结构验证器：

bash

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/scripts/validate_agent.py \
  <agent-file> --output json

Exit 0 = 结构合规。Exit 1 = 解析

errors

数组；在交付最终结果前报告每个条目的

field

、

message

和

severity

。

加载
```
${CLAUDE_PLUGIN_ROOT}/skills/repair-agent/references/quality-checklist.md
```
，运行质量标准检查，然后逐项检查清单。在交付最终结果前报告任何未通过的条目。