new-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: new-skill

Adding a skill touches four places — the canonical

skills/<name>/SKILL.md

, its

llmwiki/skills/<loop>/<name>.md

mirror, the

sync-skills.py

LOOP_MAP, the

marketplace.json

publish list, and a row in the AGENT.md/CLAUDE.md

## Skills

table. Miss one and the trees drift (that is how

marketplace.json

fell ~30 skills behind). This skill drives

fdk/tools/new-skill.py

, which writes the two mechanical files identically and prints the exact lines for the three curated places — it never edits them itself.

添加一个 skill 会涉及四个位置——canonical

skills/<name>/SKILL.md

、其

llmwiki/skills/<loop>/<name>.md

镜像、

sync-skills.py

中的 LOOP_MAP、

marketplace.json

发布列表，以及

AGENT.md

CLAUDE.md

的

## Skills

表中对应的一行。遗漏任何一处都会导致目录树漂移（

marketplace.json

就是因此落后了约 30 个 skill）。此 skill 负责驱动

fdk/tools/new-skill.py

，该工具会以完全相同的内容写入两个模板文件，并打印三个 curated 注册面需要添加的准确行——工具本身绝不编辑这些注册面。

WHAT

Purpose và context

目的与上下文

Purpose: tạo một skill mới ở cả hai cây phát hành cùng lúc (canonical + mirror byte-identical) theo khung
```
solid-what-how/1
```
, rồi đưa đúng các dòng cần dán để đăng ký nó trên các bề mặt curated.
Trigger (when to use):
The user asks to create / add / scaffold a new skill, or invokes
```
/new-skill
```
.
You are about to hand-create a
```
skills/<name>/SKILL.md
```
and would otherwise forget the mirror or the registry surfaces.

Viết cho đúng nghề — đọc
[[skill-craft]]
trước. Bộ từ vựng để một skill đoán được: hai loại phí (context load ↔ cognitive load — skill chỉ-gọi-tay thì khai
disable-model-invocation: true
, khỏi tốn context), completion criterion cho mỗi bước, leading word thay ba câu, và năm failure mode phải tránh (duplication/sediment/sprawl/no-op/negation).
/lint
bước 8b đo các thứ này bằng máy.

Non-goals: không tự sửa LOOP_MAP / marketplace.json / AGENT.md / CLAUDE.md; không migrate skill đã có (sửa tại chỗ); không tạo skill kéo từ upstream (thứ đó vào
```
skills/external/
```
).

**目的：**按照
```
solid-what-how/1
```
框架，同时在两个发布目录树中创建一个新 skill（canonical + mirror 逐字节一致），然后提供需要粘贴的准确行，以便在 curated 注册面上注册它。
触发条件（何时使用）：
用户要求创建、添加或搭建新 skill，或调用
```
/new-skill
```
。
你即将手动创建
```
skills/<name>/SKILL.md
```
，但可能忘记创建镜像或更新注册面。

要写得专业——先阅读
[[skill-craft]]
。使一个 skill 可被准确推断的准则包括：两类成本（context load ↔ cognitive load——仅手动调用的 skill 应声明
disable-model-invocation: true
，避免消耗 context）、每一步的 completion criterion、以 leading word 代替三句话，以及必须避免的五种 failure mode（duplication/sediment/sprawl/no-op/negation）。
/lint
的第 8b 步会通过机器测量这些指标。

**非目标：**不自动修改 LOOP_MAP、marketplace.json、AGENT.md 或 CLAUDE.md；不迁移已有 skill（应就地修改）；不从 upstream 拉取 skill（此类内容应放入
```
skills/external/
```
）。

Mental model

心智模型

tên + loop + description (trigger) → new-skill.py → skills/<tên>/SKILL.md (khung WHAT/HOW) + llmwiki/skills/<loop>/<tên>.md → điền TODO → swh-lint → sync-skills → đăng ký 3 bề mặt curated → sync-skills --check + skill-registry --check

name + loop + description (trigger) → new-skill.py → skills/<name>/SKILL.md（WHAT/HOW 框架）+ llmwiki/skills/<loop>/<name>.md → 填写 TODO → swh-lint → sync-skills → 注册 3 个 curated 注册面 → sync-skills --check + skill-registry --check

。

Input và output contract

输入与输出契约

	Field	Required?	Ý nghĩa
In	`<name>`	có	kebab-case, chưa tồn tại trong `skills/`
In	`--loop`	có	`dev-loop` · `orchestrate` · `wiki-loop` · `utils`
In	`--desc`	có	một dòng giàu trigger phrase (router khớp theo nó)
Out	`skills/<name>/SKILL.md` + mirror	có	hai file giống hệt, khung SWH đã điền xong TODO
Out	3 bề mặt curated đã đăng ký	có	hai lệnh check cuối đều xanh

	字段	必填？	含义
输入	`<name>`	是	使用 kebab-case，且尚未存在于 `skills/` 中
输入	`--loop`	是	`dev-loop` · `orchestrate` · `wiki-loop` · `utils`
输入	`--desc`	是	包含丰富触发短语的单行描述，router 会据此匹配
输出	`skills/<name>/SKILL.md` + mirror	是	两个完全相同的文件，SWH 框架中的 TODO 已全部填写
输出	3 个 curated 注册面已完成注册	是	最后两条检查命令均为绿色

Rules và capabilities

规则与能力

RULE-01 (MUST): The tool writes ONLY the two mechanical files (canonical + mirror). It never edits LOOP_MAP, marketplace.json, AGENT.md, or CLAUDE.md — those are user-curated; you add the printed lines by hand.
RULE-02 (MUST): After editing the generated skeleton, ALWAYS re-run
```
sync-skills.py
```
— parity is enforced, and your edits will have made the mirror stale.
RULE-03 (MUST): A vague
```
--desc
```
is a skill that never fires. Put concrete trigger phrases and
```
/
```
-commands in it.
RULE-04 (MUST): Never overwrite an existing skill — if the name is taken, edit
```
skills/<name>/SKILL.md
```
in place or pick another name.
Capabilities: ghi hai file skill; đọc chỉ mục skill hiện có (BM25) để cảnh báo trùng; các bề mặt curated do người dán tay.

RULE-01（MUST）：工具仅写入两个按模板生成的文件（canonical + mirror）。它绝不编辑 LOOP_MAP、marketplace.json、AGENT.md 或 CLAUDE.md——这些位置由用户维护，需要手动添加工具打印的行。
RULE-02（MUST）：编辑生成的骨架后，必须始终重新运行
```
sync-skills.py
```
——一致性由工具强制检查，而且你对生成内容的编辑会使 mirror 过期。
RULE-03（MUST）：模糊的
```
--desc
```
意味着 skill 永远不会被触发。应在其中加入具体的触发短语和
```
/
```
命令。
RULE-04（MUST）：绝不覆盖已有 skill——如果名称已被占用，应就地编辑
```
skills/<name>/SKILL.md
```
或选择其他名称。
能力：写入两个 skill 文件；读取现有 skill 索引（BM25）以警告功能重复；curated 注册面由用户手动粘贴更新。

Failure boundaries

失败边界

Tên đã tồn tại → blocked (tool từ chối), sửa tại chỗ hoặc đổi tên.
Trùng năng lực trên ngưỡng BM25 → cảnh báo; với
```
--strict
```
thì blocked.
```
swh-lint
```
hoặc hai lệnh check cuối đỏ → chưa xong, sửa rồi chạy lại.

名称已存在 → blocked（工具拒绝执行），应就地修改或更换名称。
功能重复度超过 BM25 阈值 → 发出警告；使用
```
--strict
```
时则 blocked。
```
swh-lint
```
或最后两条检查命令为红色 → 尚未完成，修复后重新运行。

HOW

Main workflow

主工作流

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	yêu cầu user	chốt `<name>` , `--loop` , `--desc` giàu trigger	3 input	mơ hồ → hỏi
W02	effect	3 input	`new-skill.py --dry-run` (in mẫu catalog khớp) rồi chạy thật — có mẫu hợp thì `--from <asset_id> --params p.json`	2 file + recipe `reuse_decision`	tên trùng → blocked · tham số sai → INVALID_PARAMETER
W03	judgment	khung	điền mọi TODO của WHAT/HOW, chạy `swh-lint`	skill đạt cấu trúc	đỏ → sửa, lặp W03
W04	effect	skill	`sync-skills.py` để mirror khớp	mirror giống hệt	—
W05	effect	dòng tool in ra	đăng ký LOOP_MAP, marketplace, bảng AGENT/CLAUDE	3 bề mặt	—
W06	deterministic	repo	`sync-skills.py --check` + `skill-registry.py --check`	cả hai xanh	đỏ → sửa bề mặt lệch

Chi tiết từng bước (nguồn chân lý cho W01–W06):

Settle three inputs: a kebab-case
```
<name>
```
, a
```
--loop
```
(
```
dev-loop
```
|
```
orchestrate
```
|
```
wiki-loop
```
|
```
utils
```
), and a
```
--desc
```
that is rich with trigger phrases (the description is what the skill router matches on). Skill chỉ-gọi-tay (chỉ user gõ, không skill nào khác gọi) → thêm
```
disable-model-invocation: true
```
,
```
--desc
```
rút thành một dòng người-đọc (xem
```
[[skill-craft]]
```
).

Preview first, then create:

bash

python3 fdk/tools/new-skill.py <name> --loop <loop> --desc "<description>" --dry-run   # preview body + next steps
python3 fdk/tools/new-skill.py <name> --loop <loop> --desc "<description>"             # write both files

It refuses if

skills/<name>/

already exists.

Fill in the generated
```
skills/<name>/SKILL.md
```
— the skeleton is the compact
```
solid-what-how/1
```
template (
```
## WHAT
```
purpose/contract/rules/failure +
```
## HOW
```
main workflow table/branches/examples, see
```
[[solid-what-how]]
```
). Replace every TODO with real, verifiable content, then check the shape:
bash
```
python3 fdk/tools/swh-lint.py --skills <name> --ci
```
Re-mirror after editing so the llmwiki copy stays byte-identical:
bash
```
python3 harness/scripts/sync-skills.py
```
Register on the curated surfaces by pasting the exact lines the tool printed: add the LOOP_MAP entry in
```
harness/scripts/sync-skills.py
```
, (optionally) the
```
./skills/<name>
```
line in
```
.claude-plugin/marketplace.json
```
, and one row in BOTH
```
llmwiki/AGENT.md
```
and
```
llmwiki/CLAUDE.md
```
```
## Skills
```
tables.

Verify every surface agrees — both must pass:

bash

python3 harness/scripts/sync-skills.py --check        # mirror parity
python3 harness/scripts/skill-registry.py --check      # cross-surface drift

步骤	类型	输入	操作	输出/退出状态	失败/下一步
W01	judgment	用户需求	确定 `<name>` 、 `<loop>` 以及包含丰富触发条件的 `<desc>`	3 个输入	需求模糊 → 询问用户
W02	effect	3 个输入	先运行 `new-skill.py --dry-run` （打印匹配的 catalog 样本），然后正式运行——存在匹配模板时使用 `--from <asset_id> --params p.json`	2 个文件 + `reuse_decision` recipe	名称重复 → blocked · 参数错误 → INVALID_PARAMETER
W03	judgment	骨架	填写 WHAT/HOW 中的所有 TODO，运行 `swh-lint`	skill 符合结构要求	红色 → 修复并重复 W03
W04	effect	skill	运行 `sync-skills.py` 使 mirror 保持一致	mirror 完全一致	—
W05	effect	工具打印的行	注册 LOOP_MAP、marketplace 以及 AGENT/CLAUDE 表	3 个注册面	—
W06	deterministic	repo	`sync-skills.py --check` + `skill-registry.py --check`	两者均为绿色	红色 → 修复不一致的注册面

以下各步骤的详细信息是 W01–W06 的事实来源：

确定三个输入：使用 kebab-case 的
```
<name>
```
、一个
```
--loop
```
（
```
dev-loop
```
|
```
orchestrate
```
|
```
wiki-loop
```
|
```
utils
```
），以及一个包含丰富触发短语的
```
--desc
```
（skill router 会根据描述进行匹配）。对于仅手动调用的 skill（只有用户输入，没有其他 skill 调用），应添加
```
disable-model-invocation: true
```
，并将
```
--desc
```
精简为一行便于阅读的描述（参见
```
[[skill-craft]]
```
）。

先预览，再创建：

bash

python3 fdk/tools/new-skill.py <name> --loop <loop> --desc "<description>" --dry-run   # preview body + next steps
python3 fdk/tools/new-skill.py <name> --loop <loop> --desc "<description>"             # write both files

如果

skills/<name>/

已存在，工具会拒绝执行。

填写生成的
```
skills/<name>/SKILL.md
```
——骨架使用紧凑的
```
solid-what-how/1
```
模板（
```
## WHAT
```
包含目的、契约、规则和失败边界；
```
## HOW
```
包含主工作流表、分支和示例，参见
```
[[solid-what-how]]
```
）。将每个 TODO 替换为真实且可验证的内容，然后检查结构：
bash
```
python3 fdk/tools/swh-lint.py --skills <name> --ci
```
编辑后重新同步镜像，确保 llmwiki 副本保持逐字节一致：
bash
```
python3 harness/scripts/sync-skills.py
```
通过粘贴工具打印的准确行，在 curated 注册面上完成注册：在
```
harness/scripts/sync-skills.py
```
中添加 LOOP_MAP 条目，在
```
.claude-plugin/marketplace.json
```
中添加
```
./skills/<name>
```
行（可选），并在
```
llmwiki/AGENT.md
```
和
```
llmwiki/CLAUDE.md
```
的
```
## Skills
```
表中各添加一行。

验证所有注册面保持一致——两项检查都必须通过：

bash

python3 harness/scripts/sync-skills.py --check        # mirror parity
python3 harness/scripts/skill-registry.py --check      # cross-surface drift

Branches

分支

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	conditional_required	skill chỉ-gọi-tay	thêm `disable-model-invocation: true` , rút `--desc` thành một dòng người đọc	skill model-invoked → skip	W02
B03	user_optional	catalog có template khớp contract (lọc effect trước, xếp hạng sau)	`--from` render template typed + pin sha256 vào `fdk/skill-catalog/recipes/<name>.recipe.json` ; không hợp thì scratch kèm `--reason`	catalog không đọc được → decision `catalog_unavailable` , vẫn sinh khung compact	W03
B02	recovery	BM25 báo trùng năng lực	đổi tên dạng biến thể + làm description khác biệt, hoặc sửa skill có sẵn	`--strict` → dừng	W01

ID	类型	Guard	行为	跳过/失败	汇合点
B01	conditional_required	skill 仅可手动调用	添加 `disable-model-invocation: true` ，将 `--desc` 精简为一行便于阅读的描述	skill 由 model 调用 → 跳过	W02
B03	user_optional	catalog 中存在符合契约的模板（先按 effect 过滤，再排序）	使用 `--from` 渲染强类型模板，并将 sha256 固定到 `fdk/skill-catalog/recipes/<name>.recipe.json` ；不适配时使用 scratch，并附带 `--reason`	catalog 无法读取 → 决策为 `catalog_unavailable` ，仍生成紧凑骨架	W03
B02	recovery	BM25 报告功能重复	改用名称变体并让 description 产生明显差异，或修改已有 skill	使用 `--strict` → 停止	W01

Validation và stopping

验证与停止条件

Mỗi lần chạy đều ghi

reuse_decision

(reuse · scratch · catalog_unavailable) — Reuse Layer SWH v1.1, catalog

fdk/skill-catalog/

, tool

fdk/tools/skill-reuse.py

. Reuse không miễn cổng nào: skill sinh từ template vẫn phải qua

swh-lint

. Xong khi

swh-lint --skills <name> --ci

sync-skills.py --check

và

skill-registry.py --check

đều rc 0. Hành vi thật (skill có được gọi đúng không) thử bằng 1–2 câu mẫu, lint không chứng minh được.

每次运行都会记录

reuse_decision

（reuse · scratch · catalog_unavailable）——使用 Reuse Layer SWH v1.1、catalog

fdk/skill-catalog/

和工具

fdk/tools/skill-reuse.py

。Reuse 不会跳过任何关卡：即使 skill 由 template 生成，仍必须通过

swh-lint

。当

swh-lint --skills <name> --ci

、

sync-skills.py --check

和

skill-registry.py --check

均返回 rc 0 时即完成。实际行为（skill 是否能够被正确调用）应使用 1–2 条示例提示进行测试，lint 无法证明这一点。

Examples

示例

Positive:

new-skill.py csv-preview --loop utils --desc "Xem trước CSV… Trigger: 'preview csv'"

→ hai file khung, điền WHAT/HOW, ba check xanh.

Boundary/failure:
```
new-skill.py ship …
```
→ tool từ chối vì
```
skills/ship/
```
đã tồn tại; sửa
```
skills/ship/SKILL.md
```
tại chỗ.

正向示例：
```
new-skill.py csv-preview --loop utils --desc "预览 CSV… Trigger: 'preview csv'"
```
→ 生成两个骨架文件，填写 WHAT/HOW，三项检查均为绿色。
边界/失败示例：
```
new-skill.py ship …
```
→ 工具拒绝执行，因为
```
skills/ship/
```
已存在；应就地修改
```
skills/ship/SKILL.md
```
。