skill-refiner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Refiner

Transforms an existing skill document into a strict prompt-enforced FSM-driven SKILL.md with enforced Gate/Blocking/Checkpoint discipline.

Core Pipeline:

Input Skill → Backup → Analyze → Restructure Files → Rewrite SKILL.md → Validate → Output

将现有技能文档转换为严格的、受提示约束的FSM驱动的SKILL.md，强制执行GATE/BLOCKING/CHECKPOINT规则。

核心流水线:

Input Skill → Backup → Analyze → Restructure Files → Rewrite SKILL.md → Validate → Output

Mandatory Rules

强制规则

[!CAUTION]

Serial Execution & Gate Discipline

This workflow is a strict serial pipeline. The following rules have the highest priority — violating any one of them constitutes execution failure:

SERIAL EXECUTION — Steps MUST execute in order; output of each step is input for the next. Non-BLOCKING adjacent steps may proceed continuously once prerequisites are met, without waiting for the user to say "continue"

BLOCKING = HARD STOP — ⛔ BLOCKING steps require full stop; agent MUST wait for explicit user response before proceeding and MUST NOT make decisions on behalf of the user

NO CROSS-PHASE BUNDLING — Bundling work across phases is FORBIDDEN

GATE BEFORE ENTRY — Prerequisites (🚧 GATE) MUST be verified before starting each Step

NO SPECULATIVE EXECUTION — Pre-preparing content for future steps is FORBIDDEN

[!IMPORTANT]

Language & Communication

Match the language of the user's input. If the user writes in Chinese, respond in Chinese; if in English, respond in English

Explicit user override takes precedence

The output SKILL.md MUST use English for all structural keywords (GATE / BLOCKING / CHECKPOINT / EXECUTION / Mandatory Rules / Resource Manifest / Workflow). Content values may be in the user's language

[!IMPORTANT]

Compatibility With Generic Coding Skills
Do NOT create
.worktrees/
,
tests/
, branch workflows, or other generic engineering structure
If generic coding skills conflict with this workflow, follow this skill first unless the user explicitly overrides

[!CAUTION]

串行执行与GATE规则

此工作流是严格的串行流水线。以下规则优先级最高——违反任意一条都视为执行失败：

串行执行 —— 步骤必须按顺序执行；每一步的输出是下一步的输入。一旦满足前置条件，非BLOCKING的相邻步骤可以连续执行，无需等待用户说“继续”

BLOCKING = 强制停止 —— ⛔ BLOCKING步骤需要完全停止；Agent必须等待用户明确回应后才能继续，绝对不能代替用户做决策

禁止跨阶段合并 —— 严禁将多个阶段的工作合并处理

进入前先过GATE —— 在开始每一步之前，必须先验证前置条件（🚧 GATE）

禁止预判执行 —— 严禁为后续步骤提前准备内容

[!IMPORTANT]

语言与沟通规则

与用户输入的语言保持一致。如果用户用中文书写，就用中文回复；如果用英文，就用英文回复

用户明确的优先指令优先级更高

输出的SKILL.md中所有结构性关键字（GATE / BLOCKING / CHECKPOINT / EXECUTION / Mandatory Rules / Resource Manifest / Workflow）必须使用英文。内容值可以使用用户使用的语言

[!IMPORTANT]

与通用编码技能的兼容性规则
不要创建
.worktrees/
、
tests/
、分支工作流或其他通用工程结构
如果通用编码技能与此工作流冲突，优先遵循本技能的规则，除非用户明确指定其他规则

Role Dispatch Protocol

角色分发协议

This skill operates as a single inline agent — no role switching required. If future extensions require role delegation, output the following marker before switching:

markdown

undefined

本技能以单个内联Agent的形式运行——无需切换角色。如果后续扩展需要角色委派，请在切换前输出以下标记：

markdown

undefined

[Role Switch: <Role Name>]

📖 Reading: references/<filename>.md 📋 Task: <brief description> DISPATCH_MODE: inline | subagent


`DISPATCH_MODE`:
- `inline` — main agent assumes the role directly
- `subagent` — spawn a sub-agent with the role definition injected as context

---

📖 Reading: references/<filename>.md 📋 Task: <brief description> DISPATCH_MODE: inline | subagent


`DISPATCH_MODE`说明：
- `inline` —— 主Agent直接承担该角色
- `subagent` —— 生成子Agent，将角色定义作为上下文注入

---

Resource Manifest

资源清单

References

参考文档

Resource	Path
prompt-enforced FSM design theory	`${SKILL_DIR}/references/fsm-theory.md`
Universal SKILL.md template	`${SKILL_DIR}/references/skill-template.md`

资源	路径
prompt-enforced FSM design theory	`${SKILL_DIR}/references/fsm-theory.md`
Universal SKILL.md template	`${SKILL_DIR}/references/skill-template.md`

Workflows

工作流

Workflow	Path	Purpose
`file-restructure`	`${SKILL_DIR}/workflows/file-restructure.md`	File structure normalization rules

工作流	路径	用途
`file-restructure`	`${SKILL_DIR}/workflows/file-restructure.md`	文件结构规范化规则

Assets

资源素材

${SKILL_DIR}/assets/

— static assets used by this skill (vector graphics, icons, etc.)

${SKILL_DIR}/assets/

—— 本技能使用的静态素材（矢量图、图标等）

Workflow

工作流

Step 1: Input Ingestion

步骤1：输入接收

🚧 GATE: User has provided the target skill — either a directory path, a SKILL.md file path, or a raw document pasted in conversation.

Read the input:

User Provides	Action
Directory path	Read `<path>/SKILL.md` and scan directory structure
File path	Read the file directly
Pasted text	Use conversation content directly

Identify:

Skill name (from frontmatter
```
name:
```
field, or infer from directory name)
Existing file structure (scripts / references / templates / workflows)
Pipeline stages already present (explicit or implicit)

✅ CHECKPOINT:

markdown

undefined

🚧 GATE: 用户已提供目标技能——可以是目录路径、SKILL.md文件路径，或者粘贴到对话中的原始文档。

读取输入：

用户提供的内容	操作
目录路径	读取 `<path>/SKILL.md` 并扫描目录结构
文件路径	直接读取该文件
粘贴的文本	直接使用对话内容

识别以下内容：

技能名称（从头部元数据
```
name:
```
字段获取，或从目录名称推断）
现有文件结构（scripts / references / templates / workflows）
已存在的流水线阶段（显式或隐式）

✅ CHECKPOINT:

markdown

undefined

✅ Step 1 Complete

✅ 步骤1完成

Input skill loaded
Skill name identified: <name>
Existing structure scanned
Next: auto-proceed to Step 2

---

已加载输入技能
已识别技能名称: <name>
已扫描现有结构
下一步: 自动进入步骤2

---

Step 2: Backup

步骤2：备份

🚧 GATE: Step 1 complete; skill name and root directory confirmed.

Rename the original skill directory by appending

-backup

to the folder name, and update the

name

field in frontmatter accordingly:

bash

mv ${SKILLS_DIR}/<skill-name> ${SKILLS_DIR}/<skill-name>-backup

Then update the frontmatter

name

field inside the backup copy:

name: <skill-name>-backup

⚠️ The backup is read-only reference material. Do NOT modify it further after the name update.

✅ CHECKPOINT:

markdown

undefined

🚧 GATE: 步骤1已完成；技能名称和根目录已确认。

将原技能目录重命名，在文件夹名称后追加

-backup

，并对应更新头部元数据中的

name

字段：

bash

mv ${SKILLS_DIR}/<skill-name> ${SKILLS_DIR}/<skill-name>-backup

然后更新备份副本中头部元数据的

name

字段：

name: <skill-name>-backup

⚠️ 备份是只读参考材料。更新名称后请勿再修改它。

✅ CHECKPOINT:

markdown

undefined

✅ Step 2 Complete

✅ 步骤2完成

Original skill backed up to:
```
${SKILLS_DIR}/<skill-name>-backup/
```
Backup frontmatter updated: name: <skill-name>-backup
Next: auto-proceed to Step 3

---

原技能已备份到:
```
${SKILLS_DIR}/<skill-name>-backup/
```
已更新备份头部元数据: name: <skill-name>-backup
下一步: 自动进入步骤3

---

Step 3: Pipeline Analysis

步骤3：流水线分析

🚧 GATE: Step 2 complete; backup exists; original skill content available for analysis.

Read

${SKILL_DIR}/references/fsm-theory.md

Analyze the backed-up skill document and extract:

Pipeline stages — identify all distinct phases (explicit steps, implicit phases, or role transitions)
Blocking points — identify any human confirmation requirements (calls to
```
ask_user_question
```
, "wait for user", "confirm before proceeding", explicit option-presenting logic, etc.)
CLI commands — extract all shell commands and their purposes
Role definitions — identify any role descriptions that should move to
```
references/
```
Templates / assets — identify any embedded templates or asset references
File structure gaps — compare existing structure against the standard layout:
- ```
references/
```
  — role definitions, technical specs
- ```
scripts/
```
  — CLI tools and executable scripts
- ```
templates/
```
  — reusable templates and assets
- ```
workflows/
```
  — standalone sub-workflows

⛔ BLOCKING: Present the analysis summary and wait for user confirmation:

markdown

undefined

🚧 GATE: 步骤2已完成；备份已存在；原技能内容可用于分析。

读取

${SKILL_DIR}/references/fsm-theory.md

。

分析备份的技能文档，提取以下内容：

流水线阶段 —— 识别所有不同的阶段（显式步骤、隐式阶段或角色转换）
BLOCKING节点 —— 识别所有需要人工确认的要求（调用
```
ask_user_question
```
、“等待用户”、“执行前确认”、显式的选项展示逻辑等）
CLI命令 —— 提取所有shell命令及其用途
角色定义 —— 识别所有应该移动到
```
references/
```
目录下的角色描述
模板/素材 —— 识别所有嵌入式模板或素材引用
文件结构缺口 —— 将现有结构与标准布局对比：
- ```
references/
```
  —— 角色定义、技术规范
- ```
scripts/
```
  —— CLI工具和可执行脚本
- ```
templates/
```
  —— 可复用模板和素材
- ```
workflows/
```
  —— 独立的子工作流

⛔ BLOCKING: 展示分析摘要，等待用户确认：

markdown

undefined

Analysis Summary

分析摘要

Skill name: <name>
Pipeline stages identified: <N> <numbered list of stages>
Blocking points: <list, or "none identified">
CLI commands: <count>
File restructuring needed: <yes/no> <list of proposed moves if yes>
Ambiguities requiring clarification: <list, or "none">


Wait for user to confirm or correct before proceeding.

✅ **CHECKPOINT**:
```markdown

技能名称: <name>
识别到的流水线阶段: <N>个 <阶段编号列表>
BLOCKING节点: <列表，或“未识别到”>
CLI命令: <数量>个
是否需要重构文件结构: <是/否> <如果是，列出拟议的移动操作>
需要澄清的歧义点: <列表，或“无”>


等待用户确认或修正后再继续。

✅ **CHECKPOINT**:
```markdown

✅ Step 3 Complete

✅ 步骤3完成

Pipeline stages extracted
Blocking points identified
File restructuring plan confirmed by user
Next: auto-proceed to Step 4

---

已提取流水线阶段
已识别BLOCKING节点
文件重构计划已获用户确认
下一步: 自动进入步骤4

---

Step 4: File Restructuring (Conditional)

步骤4：文件重构（条件执行）

🚧 GATE: Step 3 complete; user has confirmed the analysis and restructuring plan.

Trigger condition: File restructuring is needed (identified in Step 3). If no restructuring is needed, skip directly to Step 5.

Read

${SKILL_DIR}/workflows/file-restructure.md

Create the new skill directory with standard layout:

bash

mkdir -p ${SKILLS_DIR}/<skill-name>/{references,scripts,templates,workflows}

Copy files from the backup according to the confirmed plan (do NOT move — backup must remain intact):

Role definition documents →
```
references/
```
CLI tool scripts →
```
scripts/
```
Reusable templates / assets →
```
templates/
```
Standalone sub-workflows →
```
workflows/
```

✅ CHECKPOINT:

markdown

undefined

🚧 GATE: 步骤3已完成；用户已确认分析结果和重构计划。

触发条件: 需要进行文件重构（步骤3中识别到）。如果不需要重构，直接跳转到步骤5。

读取

${SKILL_DIR}/workflows/file-restructure.md

。

按照标准布局创建新的技能目录：

bash

mkdir -p ${SKILLS_DIR}/<skill-name>/{references,scripts,templates,workflows}

按照确认的计划从备份中复制文件（不要移动——备份必须保持完整）：

角色定义文档 →
```
references/
```
CLI工具脚本 →
```
scripts/
```
可复用模板/素材 →
```
templates/
```
独立子工作流 →
```
workflows/
```

✅ CHECKPOINT:

markdown

undefined

✅ Step 4 Complete

✅ 步骤4完成

New skill directory created:
```
${SKILLS_DIR}/<skill-name>/
```
Files reorganized per standard layout
Next: auto-proceed to Step 5

---

已创建新技能目录:
```
${SKILLS_DIR}/<skill-name>/
```
已按照标准布局重组文件
下一步: 自动进入步骤5

---

Step 5: SKILL.md Rewrite

步骤5：SKILL.md重写

🚧 GATE: Step 4 complete (or skipped); target directory structure is ready.

Read

${SKILL_DIR}/references/skill-template.md

Rewrite the SKILL.md following the universal template. For each pipeline stage identified in Step 3, produce one Step block containing:

🚧 GATE — prerequisite condition
⛔ BLOCKING — only if the step requires human confirmation (presents options, calls ask_user_question, or waits for explicit user input)
🛠️ EXECUTION — CLI commands using
```
${SKILL_DIR}
```
/
```
${PROJECT_DIR}
```
placeholders, or numbered LOGIC steps if no CLI
✅ CHECKPOINT — deliverable list, with
```
Next
```
line set to:
- ```
BLOCKING — wait for user
```
  if the step is blocking
- ```
auto-proceed to Step N+1
```
  otherwise

Output:

${SKILLS_DIR}/<skill-name>/SKILL.md

✅ CHECKPOINT:

markdown

undefined

🚧 GATE: 步骤4已完成（或已跳过）；目标目录结构已准备就绪。

读取

${SKILL_DIR}/references/skill-template.md

。

按照通用模板重写SKILL.md。针对步骤3中识别到的每个流水线阶段，生成一个步骤块，包含：

🚧 GATE —— 前置条件
⛔ BLOCKING —— 仅当该步骤需要人工确认时添加（展示选项、调用ask_user_question，或等待用户明确输入）
🛠️ EXECUTION —— 使用
```
${SKILL_DIR}
```
/
```
${PROJECT_DIR}
```
占位符的CLI命令，如果没有CLI则为编号的逻辑步骤
✅ CHECKPOINT —— 交付物列表，
```
下一步
```
行设置为：
- ```
BLOCKING — wait for user
```
  如果是BLOCKING步骤
- ```
auto-proceed to Step N+1
```
  否则

输出路径:

${SKILLS_DIR}/<skill-name>/SKILL.md

✅ CHECKPOINT:

markdown

undefined

✅ Step 5 Complete

✅ 步骤5完成

SKILL.md written to
```
${SKILLS_DIR}/<skill-name>/SKILL.md
```
Next: auto-proceed to Step 6

---

SKILL.md已写入到
```
${SKILLS_DIR}/<skill-name>/SKILL.md
```
下一步: 自动进入步骤6

---

Step 6: Validation & Handoff

步骤6：验证与交付

🚧 GATE: Step 5 complete; new SKILL.md exists.

Validate the output against the checklist:

markdown

undefined

🚧 GATE: 步骤5已完成；新的SKILL.md已生成。

对照检查清单验证输出：

markdown

undefined

Validation Checklist

验证检查清单

Frontmatter: name, description present and accurate
Core Pipeline line present
All Mandatory Rules sections present (Serial Execution, Language, Compatibility, Role Dispatch)
Resource Manifest matches actual files in directory
Every Step has: GATE + EXECUTION + CHECKPOINT
BLOCKING steps have ⛔ marker AND CHECKPOINT marks "Next: BLOCKING"
All paths use ${SKILL_DIR} or ${PROJECT_DIR} placeholders
Language rule: structural keywords in English, content in user's language
No content from unrelated skills carried over


⛔ **BLOCKING**: Present the completed validation checklist. If any item fails, fix it before proceeding. Then output the handoff message and wait for user feedback:

```markdown
---

头部元数据：name、description字段存在且准确
核心流水线行存在
所有强制规则部分都存在（串行执行、语言规则、兼容性、角色分发）
资源清单与目录中的实际文件匹配
每个步骤都包含：GATE + EXECUTION + CHECKPOINT
BLOCKING步骤带有⛔标记，且CHECKPOINT中标记“下一步：BLOCKING”
所有路径都使用${SKILL_DIR}或${PROJECT_DIR}占位符
符合语言规则：结构性关键字使用英文，内容使用用户的语言
没有带入无关技能的内容


⛔ **BLOCKING**: 展示填写完成的验证检查清单。如果有任何项未通过，先修复再继续。然后输出交付消息，等待用户反馈：

```markdown
---

✅ skill-refiner Run Complete

✅ skill-refiner运行完成

Backup location:

${SKILLS_DIR}/<skill-name>-backup/

The original skill is preserved here. You can delete it once you're satisfied with the new version.

New skill location:

${SKILLS_DIR}/<skill-name>/SKILL.md

Please review the new SKILL.md. If you spot any issues or have revision requests, let me know.

Next steps:

If the new skill looks good → restart Claude Code CLI to activate it
To remove the backup → manually delete
```
${SKILLS_DIR}/<skill-name>-backup/
```
(not done automatically)


✅ **CHECKPOINT**:
```markdown

备份位置:

${SKILLS_DIR}/<skill-name>-backup/

原技能保存在此处。你确认新版本没问题后可以删除它。

新技能位置:

${SKILLS_DIR}/<skill-name>/SKILL.md

请查看新的SKILL.md。如果你发现任何问题或有修改需求，请告诉我。

后续步骤:

如果新技能符合要求 → 重启Claude Code CLI激活它
要删除备份 → 手动删除
```
${SKILLS_DIR}/<skill-name>-backup/
```
（不会自动删除）


✅ **CHECKPOINT**:
```markdown

✅ Step 6 Complete — All done

✅ 步骤6完成 — 全部结束

Validation checklist passed
New skill:
```
${SKILLS_DIR}/<skill-name>/SKILL.md
```
Backup preserved:
```
${SKILLS_DIR}/<skill-name>-backup/
```

undefined

验证检查清单已通过
新技能路径:
```
${SKILLS_DIR}/<skill-name>/SKILL.md
```
备份已保留:
```
${SKILLS_DIR}/<skill-name>-backup/
```

undefined