skillkit

skillkit

用于个人技能集合的技能编写工具。它会将粗略想法（“我想要一个能完成 X 的技能”）转化为符合约定、采用宿主集合技能布局的精简 SKILL.md，然后为用户提供一套实时测试流程，以便实际试用。每项技能都从头编写，绝不分叉，并遵循下文列出的约定；skillkit 的存在，就是为了让你不必每次都重新推导这些规则。

调用方式

输入 /skillkit，或用任何自然语言提出“创建／编写／搭建技能”的请求。如果用户还没说明技能要做什么，先询问，不要做其他事。按以下流程一次推进一步，并在起草前明确意图、可见性、来源和名称。

对于检查或更新已有技能的请求，跳过创建步骤，转到维护现有技能。

流程

1. 收集意图

询问技能要做什么，以及何时触发（用户实际会怎么措辞）。可以选择询问示例技能链接；如果用户提供了链接，浏览并参考其结构思路。这不是阻塞条件，只有在能够获取链接内容时才值得做。记录任务、触发条件和所有硬性约束（所需工具、禁止事项）。

然后确认新建技能是否合适，因为集合的索引由人来掌握。只有当用户确实想主动选择某项技能时，它才值得拥有自己的目录：这是一个独立时机，用户会有意识地做出独立选择。如果应该由 Agent 根据上下文做选择，就应将其设为现有技能中的模式，因为模式只会在该技能的描述中增加一个分支，而新技能会永久增加一项用户必须记住的条目。指出现有技能名称，让用户决定；不要拒绝请求。当你能说明任务、它处理的每个分支（每个分支至少有一种真实措辞），以及用户在新技能与模式之间的选择时，即为完成。

2. 可见性（内部还是公开？）

询问这是仅限仓库的内部技能，还是可发布的公开技能，因为这会改变后续所有规则。

• 内部：用于维护宿主仓库的元技能。可以依赖仓库，因此可以引用仓库的约定文档、构建工具，并使用相对于仓库的链接。设置 metadata.internal: true。skills.sh 会将其从发现结果中隐藏。
• 公开：可分享的技能。它必须遵循下文的可移植性要求，并设置 metadata.internal: false。推送到公开集合仓库后，它会自动被 skills.sh 发现并列出。

用户选定后，即为完成。

3. 来源（原创还是“我的上游版本”？）

询问这是原创技能，还是基于上游技能的自有版本。无论哪种情况，这里都会从头编写；回答只会影响你在多大程度上参考上游的结构思路（参见收集意图）。用户回答后，即为完成；如果有上游链接，也一并记录。

4. 提议名称

如果宿主集合有命名约定，就遵循该约定。否则，建议 3–5 个 kit 名称并推荐一个：使用一个小写单词，功能词放在前面，以便于搜索（人们会搜索 commit，而不是 kit）；后缀加上 kit；如果词根组合起来很别扭，就缩短词根，而不是强行拼接（humanize → humankit，而不是 humanizekit）。避免与知名工具重名（speckit、shipkit 或任何已有热门工具）：有网络连接时，在网页和 skills.sh 目录中搜索候选名称；离线时，说明已跳过热门度检查。让用户选择。最终名称必须与目录名称一致。用户选定名称，且已完成名称冲突检查或说明跳过该检查后，即为完成。

5. 起草

按照宿主集合文档中规定的布局创建技能，使用下方的 Frontmatter 模板，遵循质量标准，并根据可见性填写 metadata.internal。在集合仓库中，通常使用 skills/<name>/SKILL.md；独立使用时，则使用 Agent 已发现的技能目录，例如 .claude/skills/<name>/SKILL.md。保持精简：流程直通的技能只需一个文件；对于会跳过分支的模式，使用信息层级中的模式卫星结构。

• 如果是公开技能，必须通过下方的可移植性检查清单：技能安装后必须能够独立运行。
• 在草稿旁边编写触发用例：针对每个分支，列出两到三个应该触发该技能的真实提示词，以及两到三个不应该触发的相近提示词（属于相邻技能的提示词，或基础模型可独立处理的请求）。将它们保存到集合存放此类用例的位置；如果没有此类位置，则在技能自己的目录中使用 evals/triggers.md，并分成标题为 Should fire 和 Should not fire 的两个列表。此文件让路由测试可以重复执行：之后每次修改描述，都要重新运行相同的提示词。

完成标准：所有 frontmatter 字段均已填写，每个步骤都有完成判定标准，技能以交接收尾，并且每个分支都有触发用例。

6. 评审循环

展示草稿。接受修改并反复迭代，直到用户明确批准。完成标准：用户以文字明确批准草稿；只有此后才能开始测试。

7. 实测

不要自行安装技能。提供命令，让用户进行实测。如果集合提供开发链接工具（检查其 README 或 Makefile 是否有链接/取消链接目标），告诉用户使用该工具注入技能；否则，让用户将 skills/<name> 符号链接或复制到 Agent 的技能目录（例如 ~/.claude/skills/<name>）。然后在全新会话中测试，因为技能列表在启动时加载，运行中的会话看不到新技能。不要创建临时测试计划文件；此处的测试应直接在线进行。建议用户结合实际情况进行测试：

• 逐一运行触发用例文件中的每个提示词，每个都使用一个全新会话，并记录哪些提示词触发了技能（相近提示词用于防止过度触发）；
• 确认实际运行从头到尾遵循草拟的流程，并产出技能承诺的成果或结果；
• 对任何你怀疑没有实际作用的步骤，通过运行测试来确认，不要争论。所谓没有实际作用，是指模型默认就会遵循的指令，因此测试结果取决于模型：删除可疑步骤，用相同措辞再次运行；只有行为发生变化时才保留该步骤。

测试完成后，按添加开发链接时相同的方式移除它（使用集合的取消链接命令，或删除符号链接/副本）。完成标准：每个触发用例都有触发或未触发的结果；任何不匹配都已导致描述修改，或用例更改已获用户同意。

8. 交接

本节使用程序性语体：每句话只写一条指令，使用主动语态和现在时，不使用比喻。

先完成收尾工作。如果仓库包含以下内容，请更新集合用于列出或记录其技能的每一处：

• README 技能表；
• skills.sh.json 目录分组文件（仅限公开技能）；
• 文档索引中该技能的链接（例如 docs/wiki/index.md）；
• 生成的速查表：运行集合用于生成速查表的命令（例如 make cheatsheet）。

然后运行集合的技能 lint（如果有），修复错误并处理警告。如果没有 lint，请根据 Conventions、Quality bar，以及公开技能的 Portability 进行自检。完成条件：仓库包含的每一处都已更新，且 lint 报告没有错误。然后结束交接：

变更内容。 报告创建的技能（名称、可见性、文件数量）、更新的列表和文档位置、触发用例结果，以及 lint 或自检结果。

存放位置。 提供技能目录路径，并说明来自 Live test 的开发链接是否仍然存在（此时应已移除；如果没有，请说明）。

下一步。 工作尚未提交，因此下一步是提交：建议一条 Conventional Commit 格式的提交信息（例如 feat(<name>): add <name> skill），供用户执行。绝不自动提交，因为是否提交由用户决定。

维护现有技能

适用于已存在且刚刚发生更改的技能。运行每项检查，然后按照创建技能时相同的三部分交接内容结束。

1. 重新运行触发用例。 在全新会话中运行技能触发用例文件中的每个用例；如果技能还没有触发用例，先按 Draft 中的方式编写。完成条件：每个用例都有结果，且每处不匹配都已修复或报告。
2. 对照分支检查描述。 每种模式或分支都必须有一个触发条件，且不能有触发条件指向技能已不再包含的分支。完成条件：每个分支都对应一个触发条件。
3. 更新 Hand off 中受此次更改影响的文档位置：描述更改后重新生成速查表；可见性或名称更改后，更新 README 行和文档索引。完成条件：此次更改影响的每一处都已更新。
4. 运行集合的 lint。 完成条件：lint 报告没有错误。

约定

Frontmatter 模板

---
name: <matches directory>
description: >-
  <what it does>. Use when <explicit English trigger>.
license: MIT
allowed-tools: <only if the skill needs a restricted set>
metadata:
  internal: true   # true = repo-only meta skill; false = public/publishable
---

信息层级

一个技能由步骤（Agent 执行的有序操作）和参考资料（按需查阅的定义、规则和事实）构成。两者可以自由组合：可以全是步骤、全是参考资料，也可以兼有。对每项内容，你要决定它在阶梯上的位置，依据是 Agent 需要它的紧迫程度。文件内步骤是主要层级；文件内参考资料按需查阅，同一层级上平铺一组规则是合理的安排，并非问题；外置参考资料则放入技能自身目录中的辅助文件，只有在指针指向时才加载。

按分支拆分，而非按篇幅拆分。 将每个分支都需要的内容内联，只把部分分支会用到的内容放到指针之后；例如，每次运行只读取按模式筛选目录中三分之一的内容，就是理想情形。拆分过多会隐藏 Agent 需要的材料；拆分过少则会让顶层内容臃肿。两个方向都不是稳妥的默认做法。

模式辅助文件采用固定结构。 如果技能的模式是跳过式分支（每次运行只采用一种模式，绝不读取其他模式），就应拆分为路由根文件 SKILL.md，以及每种模式各自对应的 modes/<mode>.md 文件。根文件保留模式选择、约束条件和所有模式共用的词汇，并为每种模式设置一个指针：以列表项列出模式名称，链接到其 modes/<mode>.md 文件，并说明要读取该文件，然后按其指示执行。模式文件默认根文件已加载，不重复其中内容；每种模式的交接内容随其模式正文一起移动。对于每次运行都会从头到尾遍历全文的直通式技能，无论篇幅多长，都应保持为单个文件。

将相关概念放在一起：将定义、规则和注意事项置于同一标题下，而不是散落在文件各处。散落并不等同于重复：重复是在两处重复同一个含义，而散落是将一个含义拆成多部分分布在多个地方；两者造成的问题也不同，因为 Agent 可能只读到其中一部分，再也看不到其余部分。

内容膨胀是指技能过长，即使每一行都有用且内容独特，仍然会出现的失效模式。内容过多会分散注意力。解决办法是使用层级结构，而非删减内容。

完成标准

每个步骤都以完成标准收尾，即明确告知 Agent 工作何时完成的条件。 没有完成标准的步骤会在 Agent 自认为完成时结束，这是不同运行之间差异最大的单一来源。两个特性使它成为有效杠杆。清晰度：Agent 能否分辨已完成与未完成？模糊的界限（“达成理解”“保持精简”）会导致过早完成，因为注意力已经转移到前方仍可见的步骤上，当前步骤便会提前结束。要求程度：措辞提出了多高的要求。“每个已修改的模型都已核查”会促使 Agent 真正深入检查，而“生成一份更改清单”则不会，因此应优先采用穷尽式要求，而非产出式要求。要求程度并非只适用于步骤；“已应用每条规则”同样能约束一组平铺的参考资料，这也是全参考资料型技能仍能设定标准的方式。最强的标准既可核查，又要求穷尽。

先收紧仓促步骤的界限，因为这种修改局部且成本低。只有当界限本质上模糊不清，且你已经观察到步骤确实被仓促跳过时，才拆分流程；并且要注意，拆分只有跨越真正的上下文边界时才有效，也就是交接文档或子 Agent 调度。内联调用会让后续步骤仍留在上下文中，不会隐藏任何内容。

正文格式

不要强制换行。 每个段落和列表项都写成一条连续行；让编辑器和渲染器自动换行。在句中按固定宽度换行毫无益处，因为无论有没有换行符，Agent 都会读取文本，而且所有 Markdown 渲染器都会自动换行。只在结构有意义的地方保留行结构：代码围栏、表格和 YAML frontmatter（折叠式 description: >- 标量也可以）。

行文风格

技能要为两类截然不同的读者写作。 技能写给自己的操作者的文本（QA 步骤、交接文档、状态快照、Hand off 部分、后续操作说明、预览和确认说明）属于操作性文本：使用 ASD-STE100 简明技术英语。每句话只写一条指令。操作性句子不超过 20 个单词，描述性句子不超过 25 个单词。使用主动语态和现在时，并明确指出执行者。不使用隐喻、习语或有歧义的表达。每个概念只选用一个术语，并在单个文档内保持一致；此规则不跨文档适用。供人形成观点时阅读的文本（计划背景、研究建议、ADR 理由、评审结论）属于解释性文本，应保留不均匀的节奏并明确表达立场；不要对其应用 STE。机器读取或受格式约束的文本不受此规则限制：提交说明、问题标题、提示词、设计令牌、代码、路径、命令和引用的源文本。技能为第三方受众创作的内容完全不在此规则范围内，包括项目文档、已发布的文本和 UI 文案，因为这类内容面向会话之外的读者，且需要留出解释概念的空间。优先级：明确的用户指令，其次是目标仓库中记录的规范，最后才是行文风格。在公开技能中内嵌此规则，不要链接到其他位置。

文档产物命名

当技能在 docs/ 下创建持久性 Markdown 产物时，如果宿主集合有命名规范，则遵循该规范；否则使用 NNNN-<type>-<slug>-YYYY-MM-DD.md：四位序号、小写类型前缀、简短的小写 kebab-case 主题别名，以及末尾的产物 ISO 创建日期（例如，docs/plans/0001-plan-sso-login-2026-07-23.md）。序号按目录计算，补齐为四位，单调递增且不得重复使用：查找此工作树、git worktree list 列出的所有其他工作树以及 origin/HEAD 中该目录的最大前缀序号，然后加一；从 0001 开始。扫描这三个来源，因为并行工作树可能会取得相同序号。跳过失败的来源，例如没有远程仓库；如果没有 git，则只列出该目录。编辑文件时保持完整文件名不变，并原地更新同一产物。ADR 使用其决策编号作为序号：docs/adr/NNNN-adr-<slug>-YYYY-MM-DD.md。多文件产物将此命名规范用于其集合目录，例如 docs/verify/NNNN-verify-<slug>-YYYY-MM-DD/，而结构性子项名称保持固定。技能按名称查找产物时，应匹配可选的前缀 NNNN-，这样也能找到序号规则实施前创建的文件。在每个会创建此类产物的公开技能中内嵌适用规则，以确保已安装的技能自成一体；若技能将序号规则交由目标仓库的 Agent 指南处理，则在每个全新仓库中创建的文件都不带序号。

交叉引用步骤

绝不要通过步骤编号引用步骤（例如，单独写“参见步骤 N”）。单独的数字指向步骤的位置，因此插入或重新排列步骤会导致引用悄然指向错误步骤。应引用步骤的标识：对于带标题的步骤，使用 GitHub 锚点按名称链接到该步骤（[Gather intent](#1-gather-intent)；GitHub 会根据完整标题文本生成锚点：转换为小写、移除标点并将空格替换为连字符）；对于没有标题的列表项，用文字说明操作，而不是引用序号。

结束交接

每项技能结束时都要报告已完成的工作，并说明接下来该做什么，并在名为 ## Hand off 的结束部分中说明（在编号流程中使用 ### N. Hand off；按模式分节的技能则每种模式各设一个）。技能若在结束时戛然而止，用户就得自行还原磁盘上的变更以及下一步该做什么，而这正是技能旨在免除的工作。按顺序分三个要点。变更内容：具体说明所做的更改，包括未发生的更改。变更位置：列出路径、分支、URL，确保无需四处查找。下一步：给出最合适的一项行动，而不是提供一组选项。指明后续操作，而非直接执行：写出后续操作及其单行调用方式，但不要调用它；只有在某个同类技能已安装时才提及它，并始终提供简单的备选方案（“使用 PR 技能创建 PR，否则运行 gh pr create”）。终结型技能应明确说明没有下一步，而非凭空编造；只读技能可以省略确实为空的要点，切勿凑数。

质量标准

起草时请遵循以下要求；它们决定了一项技能能否被触发，以及内容是否易于阅读：

• 把核心词前置。 核心词是简洁概括技能用途的词，而 name 和 description 的开头几个词负责触发调用，因此应把核心词放在那里。如果这个词是模型已知的词（commit、review、slop、ledger），效果会加倍：预训练词能免费锚定一种行为，而自造词则需要额外消耗定义 token 来建立同样的锚点。在正文中重复使用它作为 token；不要把它改写成句子。
• “Use when” 触发条件。 description 先说明技能的用途，再用浅显英语写一个 “Use when …” 子句，并略微加强语气以避免触发不足（列出应该触发技能的说法或命令）。description 是一个上下文指针，无论技能是否触发，每一轮都会加载，因此应把它用于每个分支设置一个触发条件，而非每个同义说法设置一个：涵盖所有模式，并合并那些只是换个说法表达同一种模式的表述。删去正文已经体现的身份信息，因为指针只说明材料是什么、何时该查阅，绝不应说明技能的规则或范围免责声明。精简同义说法，但不要缩减覆盖面；没有触发条件的分支永远不会触发。
• 技能应解决模型本身无法完成的任务。 只有基础模型无法直接处理的任务才会触发技能。如果指导内容显而易见，无论措辞如何都不会触发。
• 保持精简；按分支披露。 遵循信息层级，包括具有跳过分支模式的技能所采用的模式卫星结构：内联每个分支都需要的内容，将只有部分分支会用到的内容放入技能自身目录中的卫星文件，并将每个概念归入一个标题之下。注意避免内容膨胀，事后精简也无法解决这个问题。
• 每个步骤都以完成标准收尾，遵循完成标准。明确界定标准，让 Agent 能判断是否完成；优先采用穷尽式表述（“每个 X 均已处理”），而非产出式表述（“列出 X”）。以感觉收尾的步骤会导致每次运行的结果不一致。
• 意图优先于咒语。 技能应说明要完成什么以及为什么，让 Agent 自行确定具体调用方式。只有当命令是稳定的公开契约（git commit、gh pr create、grep、jq）时，才固定写出确切命令，因为每次运行都重新推导只会浪费 token 并带来差异；即使如此，也要让说明具备自我纠正能力（“运行 gh pr create …；如果标志被拒绝，请查看 gh pr create --help”）。绝不要硬编码易变的工具或供应商工具语法，也不要把工具的内部行为写成契约（解析输出格式、抓取帮助文本、假设默认结构），因为这些内容最脆弱，工具一更新就会失效；应描述目标，让 Agent 查阅文档。两端都要避免的失败模式是：固定脆弱语法，导致错误明显暴露；或者把固定不变的命令过度抽象成“自行想办法”，悄悄增加每次运行的负担。
• 一种含义，一个位置。 不要重复。对于内部技能，应指向宿主仓库的约定文档，而不是重复说明；对于公开技能，则应内联所需内容（参见“可移植性”）。环境也是事实来源（package.json 脚本、Makefile、配置文件、--help 输出），重复说明这些内容的技能只是一个缓存；只有查找成本高时，缓存才值得加载。缓存未成文的约定及选择背后的原因；把只需一个命令即可查询的内容留在不会过时的地方。
• 以正面方式提示。 通过禁止来引导，会把被禁止的行为带入上下文，使其变得更容易被采用，而非更难。直接说明目标行为（“写单行注释”胜过“不要写长注释”）。只有无法用正面措辞表达的硬性护栏才值得写成禁止；即便如此，也要同时给出正面目标。
• 删去无效指令。 无效指令是模型默认就会遵守的指令，写出来只会消耗加载成本，却毫无作用。判断标准取决于模型，而非读者：两个人对某条指令是否无效意见不一，争论的其实是模型的默认行为，因此应在实时测试期间运行技能来确定，而不是争论。删除整句话，不要只删减措辞。规则不明显时，要解释其原因。
• 不要硬换行，遵循正文排版。
• 判定输出的语体，遵循正文语体。技能写给操作者的文本属于程序性文本，应遵循 STE；读者需要据此权衡观点的文本属于解释性文本；面向第三方受众生成的内容不在此范围内，应遵循其自身标准。判断错误会让结论失去力度，或让运行手册变得冗长。
• 以交接收尾。 按照结束交接以 Hand off 章节收尾：说明改了什么、改动落在哪里，以及一个明确的下一步，并采用程序性语体。
• 持久文档产物。 当技能在 docs/ 下写入 Markdown 时，遵循文档产物命名，并在公开技能中内联适用的约定。
• kit 命名 + frontmatter。 严格遵循提议名称中的命名规则和Frontmatter 模板；name 必须与目录名称一致；声明 metadata.internal。

可移植性（仅限公开技能）

公开技能会单独安装到任意环境中。只有技能自身的目录会随之迁移，因此必须能够独立运行：

• 自包含。 将所依赖的约定内联写入。不要使用相对于仓库的链接（../…），也不要硬性依赖宿主仓库的 Makefile、约定文档或辅助工具。如果需要辅助脚本，请将其打包在技能自身的目录中。
• 适用于各种机器和操作系统。 不使用绝对路径，不作特定平台假设；优先采用适用于任何 Shell 环境或无需 Shell 的说明。
• 适应环境的输出。 有文件系统和 Shell 时，直接写入或编辑文件；如果没有（例如基于浏览器的 Agent），则将完成的产物以代码块形式输出，供用户保存，并跳过仅适用于仓库的步骤，例如创建开发链接和运行代码检查。

内部技能不受此限制，因为它们只在自己的仓库中存在和运行，可以自由使用仓库的工具。

备注

• skillkit 本身是公开的（metadata.internal: false）。在其所属集合中，它可以依赖仓库的链接和代码检查工具；但编写技能所需的一切内容都已内联在此处，因此无论安装在哪里，都能独立运行。
• 只有在新技能确实需要脚本或附属文件时才添加，切勿臆测需求。每个技能的脚本都应放在技能自身的目录中，而不是仓库根目录下的任何位置。