skill-builder

技能构建器

创建、修复、审计或导出一个规范技能包，或将受支持的专业知识转化为一份精简的编写提案。

判断是否要创建内容

在执行任何创建步骤之前，都要应用以下规则，包括请求已明确指定要创建的新技能或文件时：

1. 找到现有的归属方。 搜索技能、参考资料、检查清单和指令文件，看看是否已有内容负责处理该行为。应扩展现有归属方，而不是新增根目录。
2. 统计相互独立的出现次数。 新技能、关卡、库或工作流必须有三个经独立证实的真实案例，并且能够在不缺少上下文的情况下成功应用于一个源案例。少于三个案例时，只能在现有归属方中添加范围有限的说明；单个事件只是观察结果，不是技能。权威来源只支持对该来源内容的忠实陈述。
3. 为每项新产物指定使用者。 拟议的流程产物（报告、台账、计数器、仪表板或跟踪器）需要明确的使用者、其提供决策依据的决定、其要解决的已观察缺陷，以及退役条件。若缺少任何一项，就不要纳入；仅为使用该产物而编写的代码不算使用者。
4. 不采取行动也是有效结果，在现有归属方中简短补充内容也同样有效。起草之前，先说明证据支持什么；只构建调用方随后授权的内容；除非对方要求提供持久化提案，否则直接以内联形式返回提案。
5. 构建技能包并不能证明它有益。 行为效果评估应交由 技能评估，验收判断应交由 验证。

选择所需操作

需求	入口点
创建源技能包	使用 scripts/build.sh，并指定 from-scratch、from-template 或 absorb-external
检查技能包结构	scripts/heal.sh --check [--strict] skills/<slug>
修复自有投影	scripts/heal.sh --fix skills/<slug>
检查审计证据	`scripts/audit.sh [--profile canonical
合并重叠技能	整合
导出到其他平台	转换
让可重复运用的专业知识变得可复用	提炼专业知识

只运行所选操作。技能只是原生调用方在其授权结果范围内可选用的工具；本技能不会增加执行阶段、承接工作、操作 Git、验证软件候选版本，也不会决定交付和重试。输入、报告目标位置、退出代码以及从部分创建中恢复的方法，参见构建与检查机制。

创建和维护

将外部技能仅视为结构信号。以洁净室方式生成的内容不得复制其名称、正文、提示词、脚本或示例。from-template 会复用元数据默认值；absorb-external <slug> --from <path> 会验证输入并创建一个空白源包。两者都不会导入其他技能的内容。

scripts/build.sh 会创建一个不完整的源包，其中仅包含带有 metadata.authoring_state: scaffold 的 SKILL.md；是否包含辅助文件、参考资料和资源，取决于实际行为。替换占位符，并在最清晰的布局中说明适用性、输入、权威依据、结果、完成条件和失败情形。像“移交”或“然后停止”这样的结尾，在技能内联运行时可能会结束调用方的轮次；撰写此类结尾前，请阅读结尾。只有在撰写完行为后，才移除 scaffold 状态；严格的源检查会拒绝该状态。移除它是作者的声明，并不能证明语义完整。

在遇到遗漏或审查发现问题后编辑技能之前，请阅读修改现有文本；该文档会说明何时保持文本不变、何时保留明确列出的清单，以及删去某行前应检查什么。

将 skills/<slug>/ 作为源文件的维护位置。使用 scripts/heal.sh --check --strict skills/<slug> 检查已完成的源文件，然后通过仓库对应的维护命令重新生成其所属投影。检查生成的差异；不要手动编辑任何投影。检查通过并不能说明行为正常：如果编辑改变了技能的路由时机、提问内容、停止时机、提交或发布的内容、降级方式，或者删去了一行受记录的来源信息保护的内容，则除非 Skill Eval 的结果测量了该行为，否则应将其报告为未经测量，并说明缺少了什么（运行器、宿主或调用方授权）。拼写、路径和格式编辑无需此类说明。

创建过程分阶段进行，并非原子操作。如果后续阶段失败，请保留已创建的源文件和任何报告，记录退出状态和诊断信息，并分别报告源文件创建情况以及投影生成和检查的完成情况。不要将部分结果称为已完成的包，也不要删除它后重新运行创建流程。缺少必需的脚本、参考资料或运行时支持，只会阻止依赖它们的操作；请指出缺少的资源，并继续执行不依赖它们的工作。

检查模式为只读；修复模式会为明确指定的目标重新生成所属投影，不会臆造源文件中的行为。默认审计会分别报告静态符合性、已定位的效果、行为证据和不设门槛的编写疑点，不给出总分、评级或综合结论。由于审计不会运行技能或试验，效果和行为始终为 NOT_PROVEN。具体检查项、退出代码和可选的旧版架构见审计检查项、编写规范和Codex 一致性。

整合

只有两个技能负责相同的行为时才合并；共用一段内容或相互链接不算合并。应用上述决策规则，然后选定一个归属技能：保留契约更完善的技能（适用范围、权威性、结果和失败路径更明确），并只将另一个技能有而它缺少的规则移入其中。停用另一个名称之前，搜索 skills、references、目标提示词、工作流和文档，查找按名称调用它的调用方，并将每个调用方指向归属技能，然后在 docs/MIGRATION.md 中记录被停用的名称及其新的归属技能。在其他技能或目标仍按名称调用某个技能时，保留该技能，直到停用它时将其 slug 加入 scripts/check-cathedral-cut-conformance.py 中的 REMOVED_SKILLS；如果该技能重新出现，检查脚本就会失败。绝不可在没有此标记的情况下删除技能。 合并可能改变路由，因此，除非路由或 Skill Eval 结果已测量，否则应报告为未经测量：原先由已停用技能处理的请求现在是否会到达归属技能。

转换

如需显式导出到源目录之外的位置，请使用 bash skills/skill-builder/scripts/converter/convert.sh <skill-dir> <target> [output-dir]。目标为 codex、cursor 和 test；--all 会选择所有源包，--codex-layout inline 会选择旧版 inline Codex 布局。格式细节很重要时，请阅读 SkillBundle。只解析一次源文件，然后渲染目标格式，再验证资源一致性和目标格式。报告布局以及省略的 Cursor 引用。

默认导出目录为 .agents/projections/converter/<target>/<skill-name>/。 导出器会清空并重新写入输出目录，因此只能使用明确指定的派生目标：如果目标是源包、其祖先目录或仓库根目录，则必须拒绝。保持源文件不变，并修复源文件或适配器，而不是编辑输出。解析、写入、格式或必需资源失败时，导出结果不完整。 所有运行时（包括 Codex）都直接加载 skills/；这个临时导出器绝不会生成可发布的目录树。

提炼专业知识

当调用方需要一条可复用的规则时，应用上述决策规则，然后从带有引用的实例或具名权威来源入手。说明触发条件、期望行为、输入、输出、反例和限制。保留简短的源摘录或命令结果，并附上可解析的引用。当主张需要范例和留出集才能打包时，使用 Research 的 pattern mode。展示一个反例或留出集案例，并说明提议的规则如何做出正确判断。最精简的恢复状态也必须指出明确的证据丢失或损坏风险。

遵循 Memory 的来源和目标规则处理挖掘出的材料。证据不能自行成为政策。仅要求提出方案的请求应以方案结束。在现有权限范围内修复已知的一般缺陷；工具故障应作为明确事实告知原生调用方，而不是自动触发辅助链。

如需实际编辑包，请使用源模板了解必填字段，并在决定哪些内容值得保留时参考上下文密度指南。两者都不要求新增技能。