编写能被正确触发并通过校验的智能体技能，然后发布

## 技能说明只写“做什么、何时用” 应将描述视为路由元数据，而不是压缩后的操作流程。智能体可能在阅读完整正文前就根据描述选择技能，因此嵌入其中的流程步骤可能覆盖或绕过详细工作流。 描述应先简要说明能力，再列出触发条件，即该技能做什么以及何时使用。描述必须符合当前架构的长度限制，包括适用时不超过 1,024 个字符。切勿在描述中放入有序步骤、实施顺序或故障排除流程；所有操作方法都应写在技能正文中。 使用真实场景的提示词测试描述，确认它会在预期请求中触发、在无关任务中保持不触发，并将智能体引导至完整指令。 ## 前置元数据只用规范定义的字段，关联技能的引用要有效 应遵循当前有效的技能规范，而不是从相邻仓库复制字段。顶层只保留规范定义的字段，包括 `name` 和 `description`；仅按仓库约定使用 `license` 和 `allowed-tools`。如果存在 `allowed-tools`，它必须是以空格分隔的列表。仓库特有字段应放在 `metadata` 下。 名称只能使用字母、数字和连字符。验证描述的长度与触发措辞。作者、语义版本、领域、触发条件、角色、范围、输出格式和相关技能等结构化元数据，必须符合仓库定义的枚举值和格式。 每个相关技能条目都必须能解析到现有技能目录。始终使用仓库批准的许可证值；如果仓库将许可证固定为 MIT，就必须准确写成 `license: MIT`。不能仅因 YAML 解析器能够接受，就允许未知枚举值、失效引用或自定义顶层字段。 ## 主技能文件保持精简，细节移到参考文件 主技能文件应足够精简，以便作为路由和操作上下文载入。实用的第一层通常约为 80 至 100 行，其中包含角色、触发指南、五步核心工作流、强制与禁止行为，以及指向更深入参考资料的路由表。 详细技术内容应放入主题明确的第二层参考文件，每个文件通常为 100 至 600 行。每份参考资料应只涵盖一个主题，提供包含相关类型的完整可运行示例，说明边界情况和反模式，并明确何时应使用及不应使用这些指南。 只载入当前任务所需的参考资料。适当时为相关技能添加交叉链接，但不要重复其全部内容。将上下文用量降低视为设计成果；路由合理的双层结构可以在不省略必要指令的前提下，以减少约 50% 为目标。 ## 示例使用各框架自带的机制 框架专用指南必须使用该框架已确立的机制。如果框架提供全局错误处理、中间件、依赖注入、生命周期钩子或其他内置抽象，示例应使用这些机制，而不是手动重新实现。 不要为了仓库整体的视觉一致性，而向彼此无关的框架强加同一种通用架构。应优先遵循框架在错误处理、组织方式、测试和集成方面的约定。 参考示例应完整且可执行；如果所用语言支持类型，就应包含类型。根据适用范围内的框架版本审查示例，并拒绝重复内置行为或掩盖框架特有限制的模式。 ## 每个技能文件最后放一个文档链接 每个技能文件都必须以唯一一个规范文档反向链接作为最后一行。应使用标签为 `Documentation` 且指向规范 URL 的 Markdown 链接语法，而不是裸 URL，以确保严格的渲染器生成真正的超链接。 根据 `metadata.domain`、技能目录名等稳定元数据推导规范路径。元数据缺失时，使用文档中规定的备用领域。添加技能或重命名技能时，应同时更新目录、领域和反向链接；否则发布的链接可能指向不存在的页面。 明确考虑多个发布界面。原始文件聚合器可能需要通过反向链接支持发现，而文档构建流程可能会从生成页面、镜像和语言模型索引中剔除同一个自引用链接。同步时应保留这两种行为，并测试渲染后的目标页面。 ## 新建或修改技能时检查重叠，并更新相关引用 创建新技能时： 1. 检查现有技能是否存在职责重叠。 2. 编写包含能力与触发元数据的主技能，并将流程步骤留在正文中。 3. 为深入内容添加聚焦的参考资料。 4. 添加从主题到参考资料的路由表。 5. 在最后一行追加唯一一个规范文档反向链接。 6. 测试会触发和不会触发的提示词。 7. 分类体系发生变化时，更新技能指南和领域索引。 修改技能前，应阅读其当前完整正文以及受变更影响的参考资料。保留“能力加触发条件”的描述结构和渐进式披露架构。名称、范围、触发条件或依赖关系发生变化时，应更新路由表、相关技能引用、文档索引和触发测试。 ## 以一个版本文件为准，同步数量和变更日志 使用一个版本清单作为发布版本以及技能、工作流、参考文件等计算数量的唯一事实来源。运行仓库更新工具，从文件系统重新计算数量并同步生成文档。应支持检查模式和试运行模式，使 CI 和审查者无需写入即可检测偏差。 使用稳定的 Added、Changed、Fixed 结构，将新版本添加到变更日志顶部，并维护版本比较链接。在重新生成聚合文档前，先针对新增或修改的内容更新指南、决策树、命令表和交叉引用。 只有嵌入的数量发生变化时，才重新生成含数量信息的社交媒体素材；仅修改版本的补丁不需要新素材。审查生成的差异，避免自动化掩盖无关变更。 ## 发布前运行技能和 Markdown 校验工具 发布前运行技能完整性验证器。它必须检查 YAML 解析、必填字段、名称格式、描述长度与必需的 `Use when` 触发子句、参考目录是否存在、参考资料结构以及数量一致性。应提供针对单个技能或单类验证的范围化检查，并为 CI 提供机器可读的输出。 单独运行 Markdown 验证器。检查破坏表格的 HTML 注释、未闭合的代码围栏、缺失的表格分隔行以及不一致的列数。完成针对性调查后，再验证整个仓库。 将退出代码 0 视为成功，将退出代码 1 视为验证失败，并明确审查警告。不能仅因范围较窄的检查已经通过，就发布仍存在未解决验证错误的版本。 ## 记录命令和结果后，再报告可以发布 同步和验证完成后，搜索过时的版本引用，同时排除有意保留的变更日志历史。手动确认描述、触发测试、路由表、相关技能引用、规范反向链接、生成数量和条件式素材都与本次发布一致。 如果行为模式或流程规范借鉴了其他成果，应保留第三方署名、许可证声明和研究参考资料。清理时不得丢失来源信息。 准确记录更新与验证命令、命令结果、已审查的警告，以及任何有意跳过的条件式步骤。只有在全部必需验证器通过，且最终差异中没有无法解释的变更后，才能报告发布已准备就绪。