fusion-skill-authoring

创建或现代化技能

适用场景

在 skills/ 下创建新技能，或需要对现有技能进行实质性编写改进时启用。

典型触发情形：

• “为……创建一个技能”
• “搭建 skills/<name>/SKILL.md”
• “将此工作流转化为可复用技能”
• “改进此技能的元数据和激活提示”
• “让此技能更容易被发现”
• “为技能配置参考资料／资源／辅助 Agent”

隐式触发情形：

• 重复任务总是需要相同的说明或安全边界
• 现有技能过于含糊、篇幅过长、路由不佳或缺少结构
• 用户想要的是可复用的工作流包，而非一次性提示词

不适用场景

• 编辑 skills/ 以外的产品或应用代码
• 只需修正小型拼写错误、无需编写流程协助的情况
• 通过文档、模板或脚本（而非可安装技能）更适合解决的请求
• 大型且无关的仓库重构
• 破坏性命令或隐蔽的网络自动化

必要输入

如果缺少必要信息，请先简洁地提出有针对性的问题。 默认使用 assets/follow-up-questions.md 作为问题库。

必须收集

起草前收集：

• 这是新建技能、更新技能，还是根本不是技能
• 目标仓库路径和预期技能目录
• 添加任何前缀／命名空间前的 kebab-case 基础技能名称
• kebab-case 最终技能名称；除非仓库有其他约定，否则默认为 custom-<base-skill-name>
• 一句话说明用途和用户预期成果
• 具体激活提示：触发短语、领域关键词、反触发条件
• 预期输出：技能会生成的文件、命令或决策
• 安全边界和审批要求

有条件时收集

相关时收集：

• 命名前缀、命名空间或目录约定
• 技能类别：能力提升或工作流／编码偏好
• 组合方式：独立、编排器或从属技能
• 仓库特定的所有权、生命周期或发布策略
• 与编排器的关系：从属技能使用 metadata.orchestrator，编排器使用 metadata.skills
• 目标状态（active、experimental、deprecated、archived）
• 技能存在实际环境限制时的 compatibility 文本
• MCP 要求（metadata.mcp.required／metadata.mcp.suggested）
• agents/ 中的辅助 Agent 是否有助于明确范围、审查或优化触发条件
• 确定性自动化是否足以支持创建 scripts/ 目录

可选

如有帮助，可收集：

• 如果目录使用此字段，将 metadata.sponsor 作为备用责任归属
• 入门资源、检查清单、示例或模板
• 如果存在近似匹配项且应改进而非重复创建，记录相关问题以供后续处理

元数据和结构约束

写入文件前进行验证：

• name：1–64 个字符，只能包含小写字母、数字和连字符；必须与文件夹名称一致；不能以连字符开头或结尾，不能包含连续连字符、XML 标签或保留字
• 如果目标仓库没有前缀或命名空间约定，新技能默认使用 custom-<base-skill-name>
• description：非空，长度不超过 1024 个字符，使用第三人称，不含 XML 标签，并说明技能的功能及适用场景
  • 优先使用单引号括起来的 YAML 字符串，并内含 USE FOR: 和 DO NOT USE FOR: 提示
  • 示例：description: 'Drafts release notes from validated repository context. USE FOR: release summaries, changelog preparation. DO NOT USE FOR: publishing releases or editing product code.'
• metadata.version：遵循目标目录的初始版本规则；如果没有本地规则，新技能使用 "0.0.0" 是安全的默认值
• metadata.owner：仅当目标目录要求明确指定所有者时添加；使用稳定的 GitHub 身份或等效的团队标识
• metadata.status：仅当目标目录跟踪生命周期状态时添加；如使用，只能设为 active、experimental、deprecated 或 archived
• metadata.tags：标签应相关，且使用小写字母和 kebab-case 格式
• metadata：使用简单的键值元数据，只有关系字段明确需要时才使用列表或映射
• license：可选顶层字段
• compatibility：可选顶层字段；仅当技能存在实际的运行时、网络、工具或产品限制时添加

仓库特定的前缀规则、所有权和生命周期要求、发布政策及验证命令，应放在仓库本地说明或目录文档中，而不是可移植的技能包中。

说明

步骤 1 — 编辑前检查已安装副本的来源

编辑现有的 SKILL.md（或其 references/、assets/、agents/）之前，检查仓库的 apm.yml 和 apm.lock.yaml。根据锁文件中的依赖来源信息和已部署文件的所有权，判断目标是否来自外部 APM 依赖。如果是，该目标就是一个已安装副本，而不是规范源。

如果它是已安装副本：

• 不要就地编辑——本地更改可能会被下一次 apm install 或 apm update 覆盖，也无法传递给其他使用者。
• 告知用户该文件是从 <source> 安装的；应在该来源中进行更改。
• 提议切换到 <source> 并在那里进行更改，或针对该来源起草一个错误报告／改进建议。
• 只有在用户明确确认这是一次性覆盖，并接受更改不会持久保留时，才在本地编辑。

如果两个 APM 文件都不存在、目标没有匹配的已部署文件所有权，或来源与当前仓库相同，则正常进行。

步骤 2 — 判断这是否应该是一个技能

1. 先检查现有目录：
   • 如果已有技能涵盖该请求，建议复用或更新，而不是创建重复项
   • 如果某个技能几乎符合需求，建议改进它或提交问题
2. 如果请求更适合以下形式，则不要搭建技能：
   • 普通仓库文档；
   • 不包含可复用 Agent 行为的模板／检查清单；
   • 不具备技能路由价值的独立脚本；或
   • 对现有技能进行微小的文字修改

步骤 3 — 起草前定义有代表性的请求

编写长篇说明前，至少记录三个有代表性的请求：

• 用户请求或触发短语；
• 技能应产生的行为；
• 技能必须防止的错误或遗漏。

将这些内容作为验收标准。如果无法定义实际的请求，则说明范围尚未明确，或不具备足够的可复用性，不适合成为技能。

第 4 步 — 为技能分类并选择最精简的有效结构

确定技能类型：

• 能力提升：封装领域知识、工具或参考资料
• 工作流 / 编码偏好：封装步骤顺序、审核关卡、风格规则或修改顺序

确定组合方式：

• 独立：无需协调技能
• 编排器：路由到配套技能，并管理共享关卡
• 从属：仅在其编排器下运行——记录该依赖关系

选择最精简的文件夹结构：

• 始终包含 SKILL.md
• references/：存放篇幅较长的指南、示例、表格或特定平台的细节
• assets/：存放模板、检查清单、输出示例和静态文件
• agents/：运行时支持技能专属 Agent 时，用于存放专用辅助角色
• scripts/：仅当确定性自动化能显著提升安全性或可靠性时使用

参考资料保持一层目录深度。不要创建会迫使用户分段读取的嵌套链。

第 5 步 — 起草最精简的可用 SKILL.md

先编写最精简且实用的主文档：

• 编写简洁的 frontmatter，包含明确的发现提示
• 包含 When to use 和 When not to use
• 包含 Required inputs
• 包含 Instructions
• 包含 Expected output
• 包含 Safety & constraints

控制在 300 行以内。不同运行时的上下文限制各不相同——超过 300 行的文件在较小的运行时中可能出现性能下降，并触发 CI 警告。超过 500 行的文件会导致 CI 失败。尽早将超出内容移至 references/。

优先使用简洁、具体的指令，而非背景说明。假定 Agent 能够胜任；只补充它无法可靠推断的上下文。

有意识地设定自由度：

• 对依赖上下文的分析或审核，采用高自由度
• 存在首选模式但预期需要调整时，采用中自由度
• 工作流脆弱、安全关键或对顺序敏感时，采用低自由度

在 SKILL.md 中至少提供一个具体示例，或链接到 references/ 中的示例。

第 6 步 — 仅在能减少歧义时添加支持文件

将篇幅较长或较专业的内容移出 SKILL.md：

• references/：存放深入指南、大型示例、API/平台说明或较长的检查清单
• assets/：存放模板和可复用材料
• agents/：运行时支持技能专属 Agent 且工作流能从范围明确的第二意见中受益时，用于存放辅助角色
• scripts/：存放应直接执行而非重新生成的确定性操作

如果添加脚本：

• 记录依赖项和副作用，
• 验证输入，并在出错时提供可操作的错误信息，
• 明确说明网络访问，并给出合理理由，
• 绝不使用远程代码执行模式。

如果运行时忽略打包的辅助 Agent，请在正文中按相同角色行事。

如果技能依赖 MCP，请在 metadata.mcp 中声明，并在技能内容中说明特定客户端的工具命名方式。

步骤 7 — 验证发现、结构和本地策略

完成编写更改后，运行目标环境支持的验证：

• 如果可用，验证技能目录清单或架构
• 检查代码库或目录策略，包括命名、所有权、生命周期或组合元数据
• 如果技能涉及脚本、GraphQL、lint 或测试，请进行相应验证

如果没有专用的技能工具：

• 从头到尾阅读 SKILL.md 和所有直接引用的文件
• 验证每个代表性请求都能正确触发该技能
• 验证所有引用的文件路径和工作流假设均有效

使用步骤 3 中的代表性请求进行审查：

• 描述能否在正确的请求中触发技能，并避免误触发？
• Agent 能否找到所有直接引用的文件，而无需追踪嵌套链接？
• 输出、审批关卡和安全约束是否明确？

如果有子 Agent 可用：

• 起草前使用 agents/scoper.md，判断应新建、更新还是不属于技能
• 在范围界定和起草期间使用 agents/devils-advocate.md，指出关键问题；如果用户要求严格审问或检测到重大歧义，则进行完整的结构化访谈
• 起草后使用 agents/reviewer.md，审查发现、结构、安全和验证证据
• 如果主要风险是激活提示较弱，则使用 agents/trigger-tuner.md

便携式包正确无误后，应用任何特定于代码库的发布或版本管理规则。

步骤 8 — 报告变更内容和仍需提供的信息

以明确的约定形式返回编写结果：

• 新建或更新了哪些内容，
• 技能如何分类，
• 使用了哪些代表性请求作为验收标准，
• 使用了哪些辅助 Agent（如果有），
• 运行了哪些验证命令，以及验证结果证明了什么，
• 尚未解决的问题或建议后续处理的事项。

需要保留的核心行为

• 编辑现有技能前，检查已安装副本的来源
• 优先复用，再考虑新建
• 先保证便携性，再添加代码库覆盖内容
• 先确定代表性请求，再进行长篇措辞润色
• 采用渐进式披露，避免 SKILL.md 内容过载
• 对高风险操作明确设置安全和审批关卡
• 依靠真实的验证证据，而非假设正确

可选辅助 Agent

借鉴 Anthropic skill-creator 模式，但将范围缩小到 Fusion 特定的技能范围界定、审查和触发优化。

• agents/scoper.md — 判断应新建技能、更新技能还是不应创建技能；选择最精简的文件夹结构
• agents/reviewer.md — 根据发现、结构、安全和验证情况审查已起草的技能
• agents/trigger-tuner.md — 优化描述措辞；比较不同的激活提示版本
• agents/devils-advocate.md — 始终参与质量审查的协作者；编写期间采用适度模式，用户提出要求或检测到重大歧义时采用审问模式

如果运行环境不提供子 Agent，则在主流程中进行相同的审查循环。

示例

• 用户：“创建一个用于撰写事件复盘的技能。”
  • 结果：在目标目录中创建一个面向工作流的新技能，定义至少三个复盘撰写场景，搭建 SKILL.md，并仅在需要模板时添加 assets/。
• 用户：“改进 fusion-skill-authoring 的激活提示和结构。”
  • 结果：更新现有技能，刷新辅助参考资料和资源，并运行目标代码库的验证流程。
• 用户：“为应用添加一个新的 CLI 标志。”
  • 结果：不要使用此技能，因为该请求属于产品代码工作，而非技能编写。

预期输出

返回：

• 已创建或更新的文件路径
• 技能分类：新建／更新／非技能、能力型还是工作流型、独立型／编排型／从属型
• 最终激活提示和反触发条件
• 所选文件夹结构及原因
• 至少三个作为验收标准的代表性请求
• 使用了哪些辅助 Agent（如有）
• 运行的验证命令、通过／失败状态及结果解读
• 在便携式草案之后应用的仓库专属覆盖内容
• 后续操作、未解决的问题或建议关联的 issue

默认文件夹结构和基线模板请参阅 references/skill-template-baseline.md。

验证

成功信号、失败信号和恢复步骤请参阅 references/validation-signals.md。

技能就绪检查清单

使用 assets/skill-readiness-checklist.md 作为最终质量检查清单。仓库专属的 PR 要求应写入仓库说明，而不是可安装的技能资产中。

安全与约束

绝不：

• 请求或泄露机密或凭据
• 未经用户明确确认就运行破坏性命令
• 捏造验证结果或评估证据
• 修改超出请求范围的不相关文件
• 添加隐蔽的网络访问、远程代码执行或不安全的脚本指南
• 未先说明 APM 安装副本的源代码仓库并获得明确确认，就直接修改该副本

始终：

• 保持 SKILL.md 简洁；将过长内容移至直接引用的文档
• 在描述中明确发现契约
• 优先采用确定性验证循环，避免含糊的建议
• 严格限定辅助 Agent 的职责范围；即使运行时不调用它们，核心工作流也应能够正常运作
• 遵守目标目录的命名、所有权、生命周期和发布政策