skill-retro

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Retro

Analyze how skills performed in the current session and apply improvements via skill-creator.

分析当前会话中Skill的表现，并通过skill-creator应用改进措施。

Process

流程

Step 1: Preprocess Session

步骤1：会话预处理

Run the preprocessing script to extract a clean transcript from the current session's JSONL log:

bash

node ${CLAUDE_SKILL_DIR}/scripts/preprocess.mjs --cwd <current-working-directory>

Capture the JSON output. Key fields:

```
transcript_file
```
— path to the temp file containing the full transcript (at
```
~/.claude/tmp/skill-retro-<session-id>.json
```
)
```
stats.skill_invocations
```
— count of skills used

The script writes the full transcript to a temp file to avoid flooding the main thread's context window. Only the summary (stats + file path) appears in stdout.

If the script fails (e.g., no session files found), report the error and stop.

If
skill_invocations
is 0, tell the user: "No skills were invoked in this session — nothing to analyze." and stop.

运行预处理脚本，从当前会话的JSONL日志中提取清晰的对话记录：

bash

node ${CLAUDE_SKILL_DIR}/scripts/preprocess.mjs --cwd <current-working-directory>

捕获JSON输出。关键字段：

```
transcript_file
```
— 包含完整对话记录的临时文件路径（位于
```
~/.claude/tmp/skill-retro-<session-id>.json
```
）
```
stats.skill_invocations
```
— 已使用Skill的数量

该脚本会将完整对话记录写入临时文件，避免占用主线程的上下文窗口。只有摘要（统计数据+文件路径）会输出到标准输出。

如果脚本执行失败（例如未找到会话文件），请报告错误并停止流程。

如果
skill_invocations
为0，请告知用户："本次会话未调用任何Skill，无可分析内容。"并停止流程。

Step 2: Analyze (Sub-Agent)

步骤2：分析（子Agent）

Spawn an analysis sub-agent (using the Agent tool, model: sonnet):

Load the prompt from

${CLAUDE_SKILL_DIR}/references/analysis-prompt.md

Tell the agent to read the transcript file at the path from
```
transcript_file
```
in Step 1's output
The agent should read the SKILL.md file for each invoked skill to compare intended vs. actual behavior. Skill paths are discoverable from the transcript's system-reminder blocks (which list installed skill base directories) or from
```
[SKILL INVOCATION]
```
markers combined with installed plugin cache paths.
The agent returns a JSON object with
```
findings
```
,
```
well_executed
```
, and
```
severity_summary
```

Parse the agent's response into structured findings.

Once the analysis agent has finished, delete the temp file created in Step 1:

bash

rm <transcript_file>

If the agent returns 0 findings, tell the user: "All skills performed well this session. No improvements identified." Show the

well_executed

list and stop.

启动一个分析子Agent（使用Agent工具，模型：sonnet）：

从

${CLAUDE_SKILL_DIR}/references/analysis-prompt.md

加载提示词

告知Agent读取步骤1输出中
```
transcript_file
```
路径下的对话记录文件
Agent应读取每个被调用Skill的SKILL.md文件，对比预期行为与实际表现。Skill路径可从对话记录的系统提示块（列出已安装Skill的基础目录）或结合
```
[SKILL INVOCATION]
```
标记与已安装插件缓存路径找到。
Agent返回包含
```
findings
```
、
```
well_executed
```
和
```
severity_summary
```
的JSON对象

将Agent的响应解析为结构化的发现结果。

分析Agent完成后，删除步骤1中创建的临时文件：

bash

rm <transcript_file>

如果Agent返回0条发现结果，请告知用户："本次会话所有Skill表现良好，未发现可改进项。"并展示

well_executed

列表，然后停止流程。

Step 3: Interpret and Recommend

步骤3：解读与建议

Don't just present raw findings — interpret them. For each finding, add your own reasoning:

What the fix looks like — Is it a one-line description tweak? A new section in SKILL.md? A script rewrite? Be specific about what changes would actually be made.
Effort estimate — Quick fix (description/wording change), moderate (new section or error handling), or high-lift (architectural change, script rewrite, new scripts).
Recommendation — Whether to action it now, defer it, or skip it entirely. Explain why.

Group findings by skill and present with your interpretation:

undefined

不要仅展示原始发现结果——要进行解读。针对每个发现结果，添加你的推理：

修复方案——是修改一行描述？在SKILL.md中新增章节？重写脚本？明确说明需要做出哪些具体更改。
工作量评估——快速修复（描述/措辞修改）、中等工作量（新增章节或错误处理）、高工作量（架构变更、脚本重写、新增脚本）。
建议——是否立即处理、延后处理或完全跳过。说明原因。

按Skill分组展示发现结果及解读：

undefined

Skill Performance Report

Skill表现报告

scheduler:manage (3 findings)

scheduler:manage（3项发现）

1. [high] gap_coverage — pause command doesn't verify unload succeeded The

_launchctl_unload

helper silently swallows errors, so the registry can say "paused" while the job is still running.

Fix: Add return-code checking to
```
_launchctl_unload
```
in the manage script, and add a post-unload verification step in SKILL.md's Pause operation.
Effort: Moderate — script change + SKILL.md update
Recommend: Action — This caused real user confusion in this session.

2. [medium] gap_coverage — No error recovery entry for "task still runs after pausing" The assistant had to improvise the entire investigation.

Fix: Add a new row to the Error Recovery table in SKILL.md.
Effort: Quick — one table row addition
Recommend: Action — Low effort, high value.

3. [low] execution_quality — list command shows registry status without cross-checking launchd Would require the list command to shell out to

launchctl list

and reconcile.

Fix: Add launchd state reconciliation to the list operation in the manage script.
Effort: High-lift — requires new script logic and testing across platforms.
Recommend: Defer — Nice-to-have but significant work. Not worth addressing now.

1. [高优先级] gap_coverage — pause命令未验证卸载是否成功

_launchctl_unload

辅助工具会静默忽略错误，导致注册表显示"已暂停"但任务仍在运行。

修复方案：在manage脚本中为
```
_launchctl_unload
```
添加返回码检查，并在SKILL.md的Pause操作中添加卸载后验证步骤。
工作量：中等——脚本修改 + SKILL.md更新
建议：立即处理——本次会话中这一问题已造成用户实际困惑。

2. [中优先级] gap_coverage — 无"暂停后任务仍运行"的错误恢复条目 助手不得不自行完成整个排查过程。

修复方案：在SKILL.md的错误恢复表中新增一行。
工作量：快速——仅需添加一行表格内容
建议：立即处理——工作量低，价值高。

3. [低优先级] execution_quality — list命令仅显示注册表状态，未与launchd交叉验证 需要list命令调用

launchctl list

并进行状态比对。

修复方案：在manage脚本的list操作中添加launchd状态比对逻辑。
工作量：高——需要新增脚本逻辑并跨平台测试。
建议：延后处理——虽为锦上添花，但工作量大，目前不值得处理。

Well Executed

表现良好项

list presented clean, accurate registry data
Assistant correctly went outside the skill to diagnose the real issue

I recommend actioning findings 1 and 2. Finding 3 is high-lift and better deferred.

Proceed with these? (y/adjust/none)


**Key principles:**
- Lead with your recommendation — don't make the user figure out what's worth doing
- Be honest about high-lift items — don't propose changes that would require major rewrites unless they're clearly worth it
- Group related findings that would be addressed together
- The user can adjust your recommendation (add/remove items) or accept it

Wait for user confirmation. If "none", show summary and stop.

list命令展示了清晰、准确的注册表数据
助手正确跳出Skill范围诊断实际问题

我建议立即处理发现结果1和2。发现结果3工作量高，宜延后处理。

是否按此执行？(y/调整/不处理)


**核心原则：**
- 先给出建议——不要让用户自行判断哪些值得处理
- 如实告知高工作量项——除非明确有价值，否则不要提出需要重大重写的更改
- 将可一并处理的相关发现结果分组
- 用户可调整你的建议（添加/移除项）或直接接受

等待用户确认。如果用户选择"不处理"，展示摘要并停止流程。

Step 4: Resolve Source Locations

步骤4：确定源文件位置

For each skill with selected findings, determine where to edit:

Resolution order:

Project-level skill — path contains
```
.claude/skills/
```
relative to a project → Candidate: edit in place (user owns it)
User-level skill — path is under
```
~/.claude/skills/
```
→ Candidate: edit in place (user owns it)
Installed plugin — path is under
```
~/.claude/plugins/cache/
```
→ Try to trace to source: a. Extract plugin name from the path b. Check if cwd is a marketplace project containing that plugin's source (look for
```
<plugin-name>/skills/<skill-name>/SKILL.md
```
) c. If not found, ask user: "Where is the source code for the
```
<plugin-name>
```
plugin? Provide a path, or type 'installed' to edit the installed copy." → If "installed": warn that changes will be overwritten on plugin update, proceed only if user confirms → If user provides a path: verify it exists and contains the skill
Current project contains source — cwd has
```
./<plugin-name>/skills/<skill-name>/SKILL.md
```
→ Candidate: edit in place

For each resolved path, confirm with the user before proceeding:

I'll make changes to <skill-name> at:
→ /path/to/resolved/source/SKILL.md

Is this the right location? (y/n or provide correct path)

Do NOT proceed to implementation until every path is confirmed.

针对每个有选中发现结果的Skill，确定编辑位置：

优先级顺序：

项目级Skill——路径包含相对于项目的
```
.claude/skills/
```
→ 候选方案：原地编辑（用户拥有所有权）
用户级Skill——路径位于
```
~/.claude/skills/
```
下 → 候选方案：原地编辑（用户拥有所有权）
已安装插件——路径位于
```
~/.claude/plugins/cache/
```
下 → 尝试追溯到源代码： a. 从路径中提取插件名称 b. 检查当前工作目录是否为包含该插件源代码的市场项目（查找
```
<plugin-name>/skills/<skill-name>/SKILL.md
```
） c. 如果未找到，询问用户："
```
<plugin-name>
```
插件的源代码在哪里？请提供路径，或输入'installed'编辑已安装的副本。" → 如果输入"installed"：提醒用户插件更新时更改会被覆盖，仅在用户确认后继续 → 如果用户提供路径：验证路径存在且包含该Skill
当前项目包含源代码——当前工作目录存在
```
./<plugin-name>/skills/<skill-name>/SKILL.md
```
→ 候选方案：原地编辑

针对每个确定的路径，在继续前需获得用户确认：

我将对<skill-name>进行修改，位置：
→ /path/to/resolved/source/SKILL.md

这是正确的位置吗？(y/n 或提供正确路径)

在所有路径确认前，请勿进入实施阶段。

Step 5: Implement Improvements (Parallel Sub-Agents)

步骤5：实施改进（并行子Agent）

For each affected skill (with confirmed source path), spawn an implementation sub-agent:

One agent per skill — can run in parallel since they edit different files
Agent prompt:

"You are improving a Claude Code skill based on performance analysis findings.
Skill:
```
<skill-name>
```
Source path:
```
<confirmed-path-to-skill-directory>
```
SKILL.md location:
```
<confirmed-path>/SKILL.md
```
Findings to address: <list all selected findings for this skill with full observation, evidence, and proposed_improvement>

Instructions:
1. Read the current SKILL.md at the source path
2. Invoke the
```
skill-creator:skill-creator
```
  skill
3. When skill-creator asks what you want to do, explain you are improving an existing skill based on session analysis
4. Provide the findings as the basis for changes
5. Follow skill-creator's process to apply the improvements
6. After changes are made, report what was modified"

针对每个受影响的Skill（已确认源路径），启动一个实施子Agent：

每个Skill对应一个Agent——可并行运行，因为它们编辑不同的文件
Agent提示词：

"你需要基于表现分析结果改进Claude Code Skill。
Skill：
```
<skill-name>
```
源路径：
```
<confirmed-path-to-skill-directory>
```
SKILL.md位置：
```
<confirmed-path>/SKILL.md
```

需要处理的发现结果： <列出该Skill所有选中的发现结果，包含完整观察内容、证据和建议改进方案>

说明：

读取源路径下当前的SKILL.md
调用
```
skill-creator:skill-creator
```
Skill
当skill-creator询问你要做什么时，说明你正在基于会话分析改进现有Skill
提供发现结果作为更改依据
遵循skill-creator的流程应用改进措施
更改完成后，报告修改内容"

Step 6: Summary

步骤6：总结

After all implementation agents complete, present a summary:

undefined

所有实施Agent完成后，展示总结：

undefined

Skill Retro Complete

Skill Retro完成

Changes Applied

已应用的更改

Skill	Source Path	Changes
scheduler:manage	/path/to/SKILL.md	Added return-code checking to _launchctl_unload, post-unload verification step
scheduler:manage	/path/to/SKILL.md	Added "task still runs after pausing" to Error Recovery table

Skill	源路径	更改内容
scheduler:manage	/path/to/SKILL.md	为_launchctl_unload添加返回码检查，新增卸载后验证步骤
scheduler:manage	/path/to/SKILL.md	在错误恢复表中添加"暂停后任务仍运行"条目

Deferred

延后处理项

scheduler:manage #3 (launchd state reconciliation) — high-lift, deferred

scheduler:manage #3（launchd状态比对）——工作量高，延后处理

Well Executed

表现良好项

list operation presented clean, accurate registry data

undefined

list操作展示了清晰、准确的注册表数据

undefined

Important Notes

重要说明

This skill is designed to run late in sessions when context may be full. All analysis and implementation happens in sub-agents to preserve main thread context.
The preprocessing script writes the full transcript to
```
~/.claude/tmp/skill-retro-*.json
```
and only outputs a summary to stdout. Clean up the temp file after the analysis sub-agent has finished reading it.
The preprocessing script has zero dependencies beyond Node.js.
Never edit a skill without user confirmation of the source path.
When invoking skill-creator in implementation agents, let it guide the process — don't bypass its workflow.

本Skill设计用于会话后期（此时上下文可能已满）。所有分析和实施工作都在子Agent中进行，以保留主线程的上下文。
预处理脚本会将完整对话记录写入
```
~/.claude/tmp/skill-retro-*.json
```
，仅将摘要输出到标准输出。分析子Agent读取完成后，请清理临时文件。
预处理脚本除Node.js外无其他依赖。
未获得用户确认源路径前，请勿编辑任何Skill。
在实施Agent中调用skill-creator时，请遵循其流程——不要绕过工作流。