new-skill

技能：new-skill

添加一项技能涉及五处——规范文件 skills/<name>/SKILL.md、其镜像文件 llmwiki/skills/<loop>/<name>.md、sync-skills.py 中的 LOOP_MAP、marketplace.json 发布列表，以及 AGENT.md/CLAUDE.md ## Skills 表格中的一行。漏掉任何一处都会导致目录树不一致（marketplace.json 落后约 30 项就是这么造成的）。此技能会调用 fdk/tools/new-skill.py，该脚本会以相同内容写入两个机械生成的文件，并打印三个由人工维护的位置需要的确切行——它不会自行编辑这些位置。

内容

用途和上下文

• 用途： 按照 solid-what-how/1 框架，同时在两棵发布目录树（规范目录 + 镜像目录）中创建一项新技能，确保两个文件逐字节相同，然后提供需要粘贴到精选页面以完成注册的准确行。
• 触发条件（何时使用）：
• 用户要求创建／添加／搭建一项新技能，或调用 /new-skill。
• 你准备手动创建 skills/<name>/SKILL.md，否则可能会忘记镜像文件或注册页面。

写出专业水准的技能——先阅读 [[skill-craft]]。 让技能可被正确判断的一套术语：两类成本（上下文加载 ↔ 认知负担——仅由用户调用的技能应声明 disable-model-invocation: true，以免占用上下文）、每个步骤的完成标准、用一个引导词替代三句话，以及必须避免的五种失败模式（duplication/sediment/sprawl/no-op/negation）。/lint 第 8b 步会用机器检测这些事项。

• 非目标： 不自行修改 LOOP_MAP／marketplace.json／AGENT.md／CLAUDE.md；不迁移已有技能（应直接修改原文件）；不创建从上游拉取的技能（此类内容应放入 skills/external/）。

心智模型

名称 + loop + description（触发条件）→ new-skill.py → skills/<名称>/SKILL.md（WHAT/HOW 框架）+ llmwiki/skills/<loop>/<name>.md → 填写 TODO → swh-lint → sync-skills → 注册到 3 个精选页面 → sync-skills --check + skill-registry --check。

输入和输出约定

	字段	必填？	含义
输入	<name>	是	kebab-case，且 skills/ 中尚不存在
输入	--loop	是	dev-loop · orchestrate · wiki-loop · utils
输入	--desc	是	一行包含丰富的触发短语（路由器会根据它进行匹配）
输出	skills/<name>/SKILL.md + 镜像文件	是	两个文件完全相同，且 SWH 框架中的 TODO 已填写完毕
输出	已注册到 3 个精选页面	是	最后的两条检查命令均通过

规则和能力

• RULE-01（MUST）：此工具只会写入两个机械生成的文件（规范文件 + 镜像文件）。它不会编辑 LOOP_MAP、marketplace.json、AGENT.md 或 CLAUDE.md——这些由用户维护；你需要手动添加打印出的行。
• RULE-02（MUST）：编辑生成的骨架后，必须重新运行 sync-skills.py——该工具会强制保持一致性，而你的编辑会导致镜像文件过时。
• RULE-03（MUST）：含糊的 --desc 会导致技能永远不会触发。请在其中加入具体的触发短语和 / 命令。
• RULE-04（MUST）：绝不覆盖已有技能——如果名称已被占用，请直接修改 skills/<name>/SKILL.md，或另选名称。
• 能力：写入两个技能文件；读取现有技能索引（BM25）以提示重复；精选页面由用户手动粘贴维护。

失败边界

• 名称已存在 → 阻止（工具会拒绝），请直接修改原文件或更换名称。
• BM25 相似度超过阈值 → 发出警告；使用 --strict 时则会阻止。
• swh-lint 或最后两条检查命令返回错误 → 尚未完成，请修正后重新运行。

操作

主工作流

步骤	类型	输入	操作	输出/退出	失败/下一步
W01	判断	用户需求	确定 <name>、--loop、包含丰富触发短语的 --desc	3 项输入	含糊 → 询问
W02	效果	3 项输入	运行 new-skill.py --dry-run（打印匹配的目录模板），然后正式运行——有合适模板时使用 --from <asset_id> --params p.json	2 个文件 + 配方 reuse_decision	名称重复 → blocked · 参数错误 → INVALID_PARAMETER
W03	判断	框架	填写 WHAT/HOW 中的所有 TODO，运行 swh-lint	符合结构要求的 skill	未通过 → 修改，重复 W03
W04	效果	skill	运行 sync-skills.py，使镜像保持一致	镜像完全相同	—
W05	效果	工具打印的行	注册到 LOOP_MAP、marketplace、AGENT/CLAUDE 表格	3 个位置	—
W06	确定性	仓库	运行 sync-skills.py --check + skill-registry.py --check	两项检查均通过	未通过 → 修改不一致的位置

每个步骤的详细信息（W01–W06 的事实来源）：

1. 确定 3 项输入：一个 kebab-case <name>、一个 --loop（dev-loop | orchestrate | wiki-loop | utils），以及一个包含丰富触发短语的 --desc（skill 路由器会根据描述进行匹配）。仅手动调用的 skill（只能由用户输入调用，不会由其他 skill 调用）→ 添加 disable-model-invocation: true，将 --desc 缩短为一行面向读者的描述（参见 [[skill-craft]]）。
2. 先预览，再创建：

   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>/ 已存在，工具会拒绝操作。
3. 填写生成的 skills/<name>/SKILL.md——其骨架采用精简的 solid-what-how/1 模板（## WHAT 包含用途/契约/规则/失败，## HOW 包含主工作流表格/分支/示例，参见 [[solid-what-how]]）。将每个 TODO 替换为真实、可验证的内容，然后检查结构：

   python3 fdk/tools/swh-lint.py --skills <name> --ci
   

4. 编辑后重新生成镜像，确保 llmwiki 副本保持逐字节一致：

   python3 harness/scripts/sync-skills.py
   

5. 将工具打印的确切行粘贴到精选位置进行注册：在 harness/scripts/sync-skills.py 中添加 LOOP_MAP 条目，（可选）在 .claude-plugin/marketplace.json 中添加 ./skills/<name> 行，并在 llmwiki/AGENT.md 和 llmwiki/CLAUDE.md 的 ## Skills 表格中各添加一行。
6. 验证每个位置保持一致——两项检查都必须通过：

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

分支

ID	类型	条件	行为	跳过/失败	重新汇合
B01	必需条件	仅手动调用的 skill	添加 disable-model-invocation: true，将 --desc 缩短为一行面向读者的描述	由模型调用的 skill → 跳过	W02
B03	用户可选	目录中有与契约匹配的模板（先筛选 effect，再排序）	--from 会渲染类型化模板，并将 sha256 固定到 fdk/skill-catalog/recipes/<name>.recipe.json；没有合适模板则从头创建，并附带 --reason	无法读取目录 → decision 为 catalog_unavailable，仍生成精简框架	W03
B02	恢复	BM25 报告能力重复	改用变体名称并使描述有所区别，或修改已有 skill	--strict → 停止	W01

验证与停止条件

每次运行都会记录 reuse_decision（reuse · scratch · catalog_unavailable）——Reuse Layer SWH v1.1，目录 fdk/skill-catalog/，工具 fdk/tools/skill-reuse.py。复用不免除任何关卡：从模板生成的 skill 仍必须通过 swh-lint。 当 swh-lint --skills <name> --ci、sync-skills.py --check 和 skill-registry.py --check 均返回 rc 0 时，即视为完成。实际行为（skill 是否能被正确调用）应使用 1–2 个示例句子进行测试；lint 无法证明这一点。

示例

• 正例： new-skill.py csv-preview --loop utils --desc "预览 CSV… Trigger: 'preview csv'" → 生成两个框架文件，填写 WHAT/HOW，三项检查均通过。
• 边界/失败： new-skill.py ship … → 工具因 skills/ship/ 已存在而拒绝；直接修改现有的 skills/ship/SKILL.md。