skill-optimizer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Optimizer

技能优化器（Skill Optimizer）

Born from real-world production usage across multiple projects. Every diagnostic category, every proposal flow, and every guardrail exists because it solved a real problem in a real skill.

Kaizen (改善) for AI agent skills. Observe how a skill performed, find what went wrong or could be better, and propose concrete changes to its SKILL.md.

Diagnoses root causes and proposes improvements — you decide each one. Tracks recurrence in LESSONS.md with automatic importance escalation.

诞生于多个项目的实际生产使用场景，每一个诊断类别、每一个提案流程、每一条防护规则的存在，都是因为它解决了某个真实技能中的实际问题。

专为AI agent技能打造的持续改善（Kaizen，改善）工具：观察技能的执行表现，找出问题或可优化点，为其SKILL.md提出具体的修改建议。

它会诊断根本原因并提出改进方案，由你决定是否采纳；会在LESSONS.md中追踪问题复现情况，自动升级问题优先级。

Execution

执行流程

1. Resolve target

1. 确定目标

```
/skill-optimizer
```
(default) — enter listening mode. Output ONLY this single line: "skill-optimizer is observing the conversation, waiting for a skill to complete..." Nothing else — no explanations, no additional context, no prompts. Be silent. Then wait — do not prompt or block. The user will manually invoke
```
/skill-optimizer --review
```
when ready to analyze. This is the ideal scenario — the optimizer observes the skill in real time.
```
/skill-optimizer <name>
```
— target a specific skill by name
```
/skill-optimizer --diagnose
```
or
```
/skill-optimizer <name> --diagnose
```
— run static diagnostic directly on the SKILL.md without prior observation. Skips conversation friction and file diffs — uses static diagnostic + user feedback only. If no target can be resolved, ask the user: "Which skill do you want to diagnose? Provide the name or path."
```
/skill-optimizer --review
```
— skip to accumulated lessons (no skill execution needed). If no target can be resolved (no name, no prior skill in conversation), ask the user: "Which skill do you want to review? Provide the name or path." If multiple skills were executed in this conversation, ask the user: "Multiple skills detected — which one do you want to review?" If no
```
LESSONS.md
```
exists, inform the user: "No accumulated lessons found — static diagnostic and user feedback will still run. Run
```
/skill-optimizer
```
after a skill execution to start collecting lessons."
```
/skill-optimizer <name> --review
```
— review accumulated lessons for the named skill. Combines target resolution with
```
--review
```
mode. If no
```
LESSONS.md
```
exists, apply the same fallback: inform the user and offer a static diagnostic.

Argument order does not matter —

--review <name>

is equivalent to

<name> --review

--diagnose

and

--review

are mutually exclusive — if both are provided, inform the user: "Cannot use

--diagnose

and

--review

together. Pick one." and stop.

Once resolved, read the target's

SKILL.md

and

LESSONS.md

(if exists).

Skill resolution: Search for

<name>/SKILL.md

in these paths (first match wins):

```
.claude/skills/
```
```
.agents/skills/
```
The parent directory of the skill that invoked the optimizer (peer skills are expected as sibling folders — e.g.,
```
../other-skill/SKILL.md
```
)
Current working directory

If not found in any path, tell the user: "Could not find

<name>/SKILL.md

. Check the skill name or provide the full path." Do not guess or search outside these paths.

Path input: If

<name>

contains

(e.g.,

./my-skill

../other-skill

, or an absolute path), treat it as a direct path — read

<name>/SKILL.md

(or

<name>

if it already ends in

SKILL.md

). Skip the 4-path search. If the file does not exist, report: "File not found at

<path>

. Check the path and try again."

Extra arguments: Any arguments beyond

<name>

--review

, or

--diagnose

are ignored. Inform the user: "Extra arguments ignored: [args]."

Self-optimization: The default mode is observation (conversation friction + file diffs), but when the target is

skill-optimizer

itself, self-observation is unreliable — skip conversation friction and file diffs, fall back to static diagnostic + user feedback instead.

Fallback without prior run: If the target skill was not executed in this conversation (e.g.,

/skill-optimizer <name>

without prior run), fall back to static diagnostic + user feedback. State this to the user before proceeding.

```
/skill-optimizer
```
（默认）—— 进入监听模式，仅输出以下单行内容： "skill-optimizer is observing the conversation, waiting for a skill to complete..." 不要输出其他内容：不需要解释、不需要额外上下文、不需要提示，保持静默。随后等待即可，不要主动发起提示或阻塞流程，用户准备好分析时会手动调用
```
/skill-optimizer --review
```
。这是理想使用场景：优化器可以实时观察技能的运行过程。
```
/skill-optimizer <name>
```
—— 按名称指定要优化的目标技能
```
/skill-optimizer --diagnose
```
或
```
/skill-optimizer <name> --diagnose
```
—— 无需提前观察，直接对SKILL.md运行静态诊断。会跳过会话摩擦和文件差异分析，仅使用静态诊断+用户反馈。如果无法确定目标，询问用户："Which skill do you want to diagnose? Provide the name or path."
```
/skill-optimizer --review
```
—— 直接跳转至积累的经验教训分析，无需执行技能。如果无法确定目标（没有指定名称、会话中没有之前执行的技能），询问用户："Which skill do you want to review? Provide the name or path." 如果本次会话中执行了多个技能，询问用户："Multiple skills detected — which one do you want to review?" 如果不存在
```
LESSONS.md
```
，告知用户："No accumulated lessons found — static diagnostic and user feedback will still run. Run
```
/skill-optimizer
```
after a skill execution to start collecting lessons."
```
/skill-optimizer <name> --review
```
—— 查看指定技能的积累经验教训，结合了目标指定和
```
--review
```
模式。如果不存在
```
LESSONS.md
```
，使用相同的降级逻辑：告知用户并提供静态诊断选项。

参数顺序不影响效果：

--review <name>

和

<name> --review

完全等价。

--diagnose

和

--review

互斥，如果同时传入两个参数，告知用户："Cannot use

--diagnose

and

--review

together. Pick one." 并终止执行。

确定目标后，读取目标的

SKILL.md

和

LESSONS.md

（如果存在）。

技能查找规则：按以下路径搜索

<name>/SKILL.md

，匹配到第一个即停止：

```
.claude/skills/
```
```
.agents/skills/
```
调用优化器的技能所在目录的父目录（同级技能存放在兄弟文件夹中，例如
```
../other-skill/SKILL.md
```
）
当前工作目录

如果在所有路径中都未找到，告知用户："Could not find

<name>/SKILL.md

. Check the skill name or provide the full path." 不要猜测，也不要在上述路径之外搜索。

路径输入规则：如果

<name>

包含

（例如

./my-skill

、

../other-skill

或者绝对路径），将其视为直接路径：读取

<name>/SKILL.md

（如果已经以

SKILL.md

结尾则直接读取该文件），跳过上述4路径搜索。如果文件不存在，提示："File not found at

<path>

. Check the path and try again."

额外参数处理：除了

<name>

、

--review

、

--diagnose

之外的任何参数都会被忽略，告知用户："Extra arguments ignored: [args]."

自优化规则：默认模式是观察（会话摩擦+文件差异），但如果目标是

skill-optimizer

本身，自观察不可靠，会跳过会话摩擦和文件差异分析，降级为静态诊断+用户反馈。

无前置运行的降级逻辑：如果目标技能没有在本次会话中执行过（例如直接运行

/skill-optimizer <name>

而没有提前执行技能），降级为静态诊断+用户反馈，继续执行前告知用户该情况。

2. Gather

2. 收集信息

Collect findings from the appropriate source:

Sources: conversation friction, file diffs, user feedback, static diagnostic

Default — enters listening mode; analysis deferred to
```
--review
```
<name>
without prior run — static diagnostic, user feedback
<name>
with prior run — conversation, diffs, static diagnostic, user feedback
--diagnose
— static diagnostic, user feedback
--review
— conversation, diffs, existing LESSONS.md entries, static diagnostic, user feedback

Conversation friction:

Errors or exceptions during skill execution
User corrections ("no, not that", "I meant...", "undo that")
Retries or repeated attempts at the same step
Manual interventions the user had to make
Confusion about what the skill was supposed to do
Steps the skill skipped or did in the wrong order

File diffs: Use

git diff

(or

git diff --cached

) to inspect changes made during the skill's execution. If not in a git repo, compare file contents against the SKILL.md's expected output. Look for:

Files the skill created or modified — do they match what was expected?
Changes the user had to make after the skill ran (post-corrections)
Incomplete implementations (TODOs, placeholders, missing pieces)
Patterns that deviate from what the SKILL.md prescribed

User feedback: After gathering findings, ask the user: "Want to add anything, or should we review the findings?"

Static diagnostic (used in

--review

--diagnose

, and

<name>

without prior run): Validate against baseline rules:

Frontmatter must have
```
name
```
and
```
description
```
(required)
Description max 1024 characters, third person, with specific trigger phrases
Body should be under 500 lines and under 5k tokens — use
```
references/
```
for overflow. Token count is the primary constraint; line count is a quick heuristic.
Name: lowercase, hyphens only, 1-64 characters
Progressive disclosure: metadata (~100 tokens) → body → resources (as needed)
Check for: dead content (unreferenced sections, commented-out blocks, instructions that no longer match the skill's actual behavior), scope creep (sections that belong in a different skill or exceed the stated purpose), trigger quality (description contains specific verbs and contexts that help the harness match user intent — not just generic terms), token efficiency (redundant paragraphs, verbose phrasing that could be tightened without losing meaning), completeness (all stated flows have matching instructions — no "TODO" or undocumented branches)
When recommending
```
references/
```
: this is a subdirectory alongside SKILL.md that holds supporting material (tables, examples, templates) the agent loads on demand. Files should be markdown, named descriptively (e.g.,
```
references/diagnostic-tables.md
```
), and referenced from the body with explicit load instructions (e.g., "Read
```
references/diagnostic-tables.md
```
for the full list").
If the target SKILL.md is missing frontmatter or required fields (
```
name
```
,
```
description
```
), report it as a
```
high
```
finding and propose adding the missing structure — infer values from the body content.

Cross-reference against the SKILL.md. Read

references/diagnostic-tables.md

(relative to this skill's own directory, NOT the project CWD) for the category and root-cause lookup tables.

Static diagnostic output: Present results as a single unified checklist before proposals:

One line per baseline rule: ✅ for pass, ❌ for findings (include importance + short description)
Cross-reference findings go in the same list with ❌ — no separate section, no numbering
End with finding count: "Found N findings." or "No issues found."

Importance:

high

(breaks output, errors) ·

medium

(suboptimal, friction) ·

low

(style, preferences)

Recurrence: Same pattern in LESSONS.md? Increment

Hits

instead of duplicating. Hits >= 3 escalates:

low

→

medium

medium

→

high

context7 (optional): If the target skill references a specific library or framework (e.g., Angular, NestJS, React), use context7 to verify that code patterns, API calls, or config examples in the SKILL.md match current docs. Report mismatches as findings with diagnostic

outdated content

. If the skill does not reference any library, skip — the baseline rules are sufficient. If context7 is not available in the environment, skip this step — the baseline rules are sufficient.

从对应来源收集诊断结果：

信息来源：会话摩擦、文件差异、用户反馈、静态诊断

默认模式—— 进入监听模式，分析推迟到
```
--review
```
时执行
指定
<name>
且无前置运行—— 静态诊断、用户反馈
指定
<name>
且有前置运行—— 会话、文件差异、静态诊断、用户反馈
--diagnose
模式—— 静态诊断、用户反馈
--review
模式—— 会话、文件差异、现有LESSONS.md条目、静态诊断、用户反馈

会话摩擦：

技能执行期间的错误或异常
用户修正（"no, not that"、"I meant..."、"undo that"等）
同一步骤的重试或重复尝试
用户不得不进行的手动干预
对技能预期功能的困惑
技能跳过的步骤或执行顺序错误的步骤

文件差异：使用

git diff

（或

git diff --cached

）检查技能执行期间产生的变更。如果不在Git仓库中，将文件内容与SKILL.md的预期输出对比，查找以下问题：

技能创建或修改的文件是否符合预期？
技能运行后用户不得不做出的修改（事后修正）
不完整的实现（TODO、占位符、缺失部分）
偏离SKILL.md规定的模式

用户反馈：收集完诊断结果后，询问用户："Want to add anything, or should we review the findings?"

静态诊断（用于

--review

、

--diagnose

以及无前置运行的指定技能场景）：对照基线规则验证：

前言部分必须包含
```
name
```
和
```
description
```
（必填）
描述最多1024字符，使用第三人称，包含明确的触发短语
正文应少于500行、少于5k token，超出部分使用
```
references/
```
目录存放。token数量是核心限制，行数是快速判断指标。
名称：小写、仅使用连字符分隔，长度1-64字符
渐进式信息披露：元数据（约100 token）→ 正文 → 资源（按需加载）
检查项：无效内容（未引用的章节、注释块、与技能实际行为不匹配的指令）、范围蔓延（属于其他技能或超出声明用途的章节）、触发质量（描述包含帮助框架匹配用户意图的具体动词和场景，而不是通用术语）、token效率（冗余段落、可精简且不损失含义的冗长表述）、完整性（所有声明的流程都有对应的指令，没有"TODO"或未文档化的分支）
推荐使用
```
references/
```
：这是SKILL.md同级的子目录，用于存放支撑材料（表格、示例、模板），agent会按需加载。文件应为Markdown格式，命名要清晰（例如
```
references/diagnostic-tables.md
```
），并在正文中通过明确的加载指令引用（例如"Read
```
references/diagnostic-tables.md
```
for the full list"）。
如果目标SKILL.md缺少前言或必填字段（
```
name
```
、
```
description
```
），标记为
```
high
```
级问题，建议补充缺失的结构，从正文内容推断字段值。

与SKILL.md交叉比对，读取本技能自身目录下的

references/diagnostic-tables.md

（不是项目工作目录下的）获取类别和根本原因查找表。

静态诊断输出：在提案前将结果作为统一的检查清单展示：

每条基线规则占一行：✅表示通过，❌表示存在问题（包含优先级+简短描述）
交叉比对发现的问题也放在同一列表中用❌标记，不需要单独章节、不需要编号
最后输出问题统计："Found N findings." 或 "No issues found."

优先级：

high

（破坏输出、错误）·

medium

（不够优化、有摩擦）·

low

（风格、偏好）

复现规则：LESSONS.md中存在相同模式？不要重复记录，增加

Hits

计数即可。Hits >=3时升级优先级：

low

→

medium

，

medium

→

high

。

context7（可选）：如果目标技能引用了特定库或框架（例如Angular、NestJS、React），使用context7验证SKILL.md中的代码模式、API调用或配置示例是否符合最新文档。将不匹配的情况标记为

outdated content

问题。如果技能没有引用任何库，跳过该步骤，基线规则已足够。如果环境中没有context7，跳过该步骤，基线规则已足够。

3. Propose

3. 提出方案

If no findings were identified, report: "No issues found. The skill looks solid." If user feedback was not yet collected (e.g.,

--review

mode), ask for it now. If the user has none, end with no proposals.

Before the first proposal, show the sources legend listing only the sources actually used in the current run (e.g.,

Sources: static diagnostic, user feedback

Present findings one at a time, ordered by importance. For

--review

findings from LESSONS.md, verify the root cause still exists in the current SKILL.md before proposing. If resolved, mark as

(resolved)

and recommend rejecting to clean up the entry. If there are more than 15 findings, present the top 15 (by importance) and offer to log the rest to LESSONS.md: "There are [N] more remaining findings — want me to log them to LESSONS.md for later review?" If the user declines, discard the remaining findings.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  PROPOSAL [N/total] — [importance]
  Source: [conversation | diff | user | lessons | diagnostic]

  Finding: [what was observed]
  Root cause: [diagnostic] — [which line/section and why]
  Hits: [N — omit if first occurrence]

  Proposed change: [what to add/modify/remove]
  Preview:
  - [old line]
  + [new line]
  For additions, show only `+` lines with surrounding context.
  For removals, show only `-` lines.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Use the question tool (e.g.,

AskUserQuestion

in Claude Code) to ask the user for their decision:

Default mode:

question: "Proposal [N/total] — [importance]: [one-line finding summary]"
header: "Proposal [N/total]"
options:
- label: "Accept", description: "Apply the edit to the SKILL.md"
- label: "Postpone", description: "Save to LESSONS.md for later"
- label: "Reject", description: "Discard this finding"
- label: "Don't", description: "Add a permanent negative rule to SKILL.md"

--review
mode:

Same as above but replace "Postpone" with:
- label: "Keep", description: "Leave in LESSONS.md for later review"

Actions:

Accept → apply the edit
Postpone → save to LESSONS.md
Reject → discard (in review: remove from LESSONS.md)
Keep (only in
```
--review
```
):
- Existing LESSONS.md entry → leave it for later
- New finding (from diagnostic or user feedback) → add to LESSONS.md
Don't → ask "This will add a permanent negative rule. Confirm? (y/n)", then on
```
y
```
, append a negative rule at the end of the target's SKILL.md Guardrails section (create one if absent — place it as the last section before any footer like
```
---
```
) using the format:
```
- **Never [action].** [reason from the finding]
```

If the user selects "Other" and types "skip all", write current and all remaining findings to LESSONS.md and end.

Summary:

Done. [N] accepted, [N] postponed, [N] rejected, [N] don'ts.

如果没有发现任何问题，提示："No issues found. The skill looks solid." 如果还没有收集用户反馈（例如

--review

模式），现在询问用户。如果用户没有补充内容，没有提案直接结束。

在第一个提案前，仅列出本次运行实际使用的来源说明（例如

Sources: static diagnostic, user feedback

）。

按优先级排序，逐个展示问题。对于

--review

模式中来自LESSONS.md的问题，提案前先验证当前SKILL.md中是否还存在该根本原因，如果已经解决，标记为

(resolved)

，建议拒绝该提案以清理条目。如果问题超过15个，展示优先级最高的15个，并询问是否将剩余问题记录到LESSONS.md："There are [N] more remaining findings — want me to log them to LESSONS.md for later review?" 如果用户拒绝，丢弃剩余问题。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  PROPOSAL [N/total] — [importance]
  Source: [conversation | diff | user | lessons | diagnostic]

  Finding: [what was observed]
  Root cause: [diagnostic] — [which line/section and why]
  Hits: [N — omit if first occurrence]

  Proposed change: [what to add/modify/remove]
  Preview:
  - [old line]
  + [new line]
  For additions, show only `+` lines with surrounding context.
  For removals, show only `-` lines.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

使用提问工具（例如Claude Code中的

AskUserQuestion

）询问用户的决策：

默认模式选项：

问题："Proposal [N/total] — [importance]: [one-line finding summary]"
标题："Proposal [N/total]"
选项：
- 标签："Accept", 描述："Apply the edit to the SKILL.md"
- 标签："Postpone", 描述："Save to LESSONS.md for later"
- 标签："Reject", 描述："Discard this finding"
- 标签："Don't", 描述："Add a permanent negative rule to SKILL.md"

--review
模式选项：

与上述相同，仅将"Postpone"替换为：
- 标签："Keep", 描述："Leave in LESSONS.md for later review"

对应操作：

Accept → 应用修改
Postpone → 保存到LESSONS.md
Reject → 丢弃（review模式下：从LESSONS.md中移除）
Keep（仅review模式存在）：
- 现有LESSONS.md条目 → 留待后续处理
- 新发现的问题（来自诊断或用户反馈）→ 添加到LESSONS.md
Don't → 询问"This will add a permanent negative rule. Confirm? (y/n)"，如果用户回复
```
y
```
，在目标SKILL.md的Guardrails章节末尾添加否定规则（如果不存在该章节则创建，放在页脚
```
---
```
之前的最后一个章节），格式为：
```
- **Never [action].** [reason from the finding]
```

如果用户选择"Other"并输入"skip all"，将当前和所有剩余问题写入LESSONS.md后结束。

总结：

Done. [N] accepted, [N] postponed, [N] rejected, [N] don'ts.

LESSONS.md Format

LESSONS.md格式

Lives alongside the target's SKILL.md. Read

references/lessons-format.md

(relative to this skill's own directory, NOT the project CWD) for the full format and rules.

存放在目标SKILL.md的同级目录下。读取本技能自身目录下的

references/lessons-format.md

（不是项目工作目录下的）获取完整格式和规则。

Guardrails

防护规则

Never edit without confirmation. Show the diff, wait for explicit approval. No exceptions. The user owns the skill.
Never expose secrets. Redact API keys, tokens, passwords, credentials (
```
sk-...
```
,
```
ghp_...
```
,
```
Bearer ...
```
) with
```
[REDACTED]
```
in all output and LESSONS.md.
Read before proposing. Read SKILL.md + LESSONS.md first to avoid duplicates.
Never invent. Zero findings is a valid outcome. Never fabricate findings or fill gaps with guesses — if you don't know, say "I don't know".
One at a time. Present, decide, move on.
Respect structure. Match existing style when inserting content.
Don'ts need double confirmation. Negative rules are impactful — always confirm.
Never bump versions. Version management is the user's responsibility — do not modify version fields in frontmatter.

Made with <3 by Crystian

未经确认绝不修改。 展示差异，等待明确批准，没有例外，技能所有权属于用户。
绝不泄露密钥。 在所有输出和LESSONS.md中，将API密钥、token、密码、凭证（
```
sk-...
```
、
```
ghp_...
```
、
```
Bearer ...
```
）替换为
```
[REDACTED]
```
。
提案前先读取内容。 先读取SKILL.md + LESSONS.md，避免重复提案。
绝不编造内容。 零问题是合理结果，绝不虚构问题或用猜测填补空白，如果不知道就说"I don't know"。
一次处理一个。 展示、决策、再继续。
尊重现有结构。 插入内容时匹配现有风格。
否定规则需要双重确认。否定规则影响大，必须确认。
绝不修改版本号。 版本管理是用户的责任，不要修改前言中的版本字段。

Made with <3 by Crystian