Tutorials

%% @trace
	id: hopjit-tutorial-hopskill
	source: [[../../hopbuild/SKILL]]
	source_id: hopbuild-skill
	type: compact
	last_sync: 2026-10-01T17:01+0800
	note: 教程 7——收官应用:经 /hop 分派 hopbuild 把自然语言 skill 翻译成 hopskill（SKILL.md 是翻译器的完整契约，本文是用户视角的上手版）
%%

# 教程 7 · 把你的自然语言 skill 升级为 hopskill

**目标**：拿一个你自己的**自然语言 skill**（纯散文写的 SKILL.md，英文文档中亦称 prose skill），翻译成 HopSpec 规约（**hopskill**），跑起来，体会两者的差别。
**前提**：完成教程 1（引擎和 skill 已装好）。读过 03-05 三篇的话，翻译产物的审计（第 3 步）会做得深得多。

> Codex 用户注：翻译器 hopbuild 目前仅 CC 载体提供（对 /hop 说"把 xxx 翻译成 spec"即分派到它）——在 CC 里完成翻译即可，产物 spec 两载体通用。

## 为什么要升级

自然语言 skill 的纪律靠执行 LLM"读到并记住"。上下文一长，三类事故稳定复现：

| 事故 | 例子 |
|---|---|
| **漏遍历项** | "对每个文件做 X"——做到第 7 个忘了还有 3 个 |
| **跳过审核** | "让用户确认后再继续"——LLM 自己判断"应该没问题"就继续了 |
| **试错期做不可逆操作** | 还在调试就把邮件发出去了 |

hopskill 把这三条从"靠记忆"变成**引擎结构化强制**：遍历翻成 `parallel + for-each`（引擎按列表长度复制、全部完成才 join，想漏都漏不掉）；审核翻成 `confirm`/`check`（引擎暂停等真人，LLM 无权替答）；不可逆操作翻成 `commit` 并强制前序把关闸门。

## 第 1 步：挑一个自然语言 skill

好的候选长这样：有明确步骤序列、有"对每个…"的遍历、有"让用户确认"的审核点、有最终交付物。第一次练手别挑太大的（10 步以内）。

没有现成的？仓库里有一对现成的教学样本：`scripts/audit/test-coverage-audit.md` 就是由同名自然语言 skill 翻译来的 golden sample，可以先读它找感觉（纪律句的结构化落地都在：步骤 5 是 parallel+for-each〔遍历〕、3.3 是 [check final]〔核验〕、2.1.2 是带前序把关的 commit〔提交〕）。

## 第 2 步：翻译

Claude Code 命令（翻译器目前仅 CC 载体提供；Codex 用户在 CC 里翻译，产物两载体通用）：

```
/hop 把 .claude/skills/你的skill/SKILL.md 翻译成 spec
```

（不给路径它会列出你 `.claude/skills/` 下的候选让你挑。）

翻译过程你会被问到的事，都属于"原文意图不清"——翻译器的原则是**忠实翻译，不增删业务逻辑**，拿不准就问你而不是臆断。翻完它自动跑 `hopjit validate`，语法门过了才会把 spec 交给你过目（语义忠实这道门归你）。（产物要在 standalone 跑的，再花几分钟跑一轮 deep-validate 跑前体检——查静态判不了的运行期假设，见 D8）

## 第 3 步：读懂产出（终审你把的是忠实关）

翻译交付三件：spec、**source.md**（你原文的纯副本——终审与日后对读的基准）、**实测报告**（test_report——翻出的 spec 用构造案例核证过能跑）。终审时对着 source.md 抽查关键处：遍历句真变 for-each 了吗？硬约束有 check 落地吗？不可逆操作前面有闸门吗？该你拍板的真问你吗？（对应讲解：遍历→[[05-并行与遍历]]、check/commit→[[03-探索与提交]]、组装范本→[[06-实战-事实核查器]]。）

**source.md 的另一个用处**：日后你改了原 skill，和 source.md 一比对就知道哪些段落变了——对应的 spec 步骤跟着重翻即可，不用整个重来。

## 第 4 步：跑起来

Claude Code 命令：

```
/hop 跑 生成的spec.md
```

Codex 命令（spec 两载体通用）：

```
$hop 跑 生成的spec.md
```

体感上和教程 1 一样，但注意与自然语言版跑同一任务的差别：

- 遍历是引擎 fan-out 的（parallel worker 并发），不是 LLM 凭记性逐个来；
- 到 confirm 时**必定**停下问你——哪怕答案"显而易见"；
- 中断后对 `/hop` 说"接着跑"从断点继续——自然语言 skill 断了只能重头。

## 第 5 步（可选）：迭代——小改自己动手，成批修正交给 hopfix

翻译不是一锤子买卖。跑几次后想调整（加步骤、改约束），**改 spec 文件本身**——它就是普通 markdown，改完 `hopjit validate` 过了就能跑。别忘了 spec 是唯一权威，不要一份逻辑在自然语言 skill 和 spec 里各改各的。

改一两个字自己动手就好；**要改的地方多了、或者你担心手改引入新问题，用 hopfix**——它是专门做定向修正的工具：你把修正意见写成一段话（哪一步有什么问题、想改成什么样），它定位到具体步骤逐处改，改完自动把三道关：机械核对"只有你点名的地方变了"、语义核对"改的确实是你要的"、然后把修正稿和改动清单呈给你确认，你点头它才写回（写回前自动留原件快照，随时可回滚）。

```
/hop 修一下 生成的spec.md：步骤 3 的说明里××是错别字；步骤 5 的阈值应该是 30000 不是 300000
```

（一句话把"哪份 spec、要改什么"说清就行——不用记参数格式；意见多的时候直接把整份检查报告贴进来也行。）

两件事它替你把住：**改不该改的**——修正意见之外的步骤一个字都不会变（机器保证，不靠自觉；新增/删除步骤时，后面步骤的编号会相应顺延——这个顺延也是机器管的）；**改不动的如实说**——如果你的意见其实是"这一段整个拆法要换"这种结构性变更，它不会硬改，会明确告诉你这超出定向修正的范围、该重新翻译那一段（回到第 2 步的翻译流程）。修正意见也可以直接贴一份检查报告（比如 deep-validate 的风险报告）——查出什么修什么，不用自己转写。

## 第 6 步（推荐）：打包成具名 skill

翻译产物验证满意后，把它包装成一个**独立具名 skill**——让不知道 HopSpec 存在的人也能用：

```bash
hopjit pack 生成的spec.md
```

生成项目级 `.claude/skills/<spec的Id>/`（薄 SKILL.md + spec + 知识文档——pack 产物跟项目走;要装到用户级或别处用 `--dir` 显式指定）。此后用户直接说"帮我做 XX"就能触发，参数由 skill 引导收集，执行仍走 hopspec 驱动协议——但那是实现细节，用户不用知道。这就是完整闭环：**自然语言 skill →（翻译）→ spec →（pack）→ 更可靠的具名 skill**，用户视角是"skill 升级了"，用法零变化。

## 教程主线到此走完——之后去哪

你已经能跑、能读、能写、能把自己的 skill 升级成引擎强制执行的 hopskill。之后按需取用：

- **任务变长变频、想换轻量模型省成本** → 独立模式，配置一次：`USAGE.md` §6；
- **写更大的 spec** → 拿 `examples/hop-fact-check.md`（完整版）当范本——自查回路、推演分流那些进阶件的讲解在 [[06-实战-事实核查器]]；语法权威随手查：`docs/concepts/HopSpec V3语法参考.md`；
- **翻译器的深层判据**（审计产物时用）：四类纪律落点判据/模板/反例、NL 措辞→步骤类型映射——统一在 `skills/hopbuild/hopbuild-primer.md`（统一知识源——判据/语法/骨架单文档）；
- **要让 spec 调外部能力**（搜索/知识库/云端 API）→ [[08-接入MCP服务]]；
- **想参与 HOP 生态开发** → 换线去 [[D0-生态开发者导读]]。