把AI技能文档集中在一处管理，并写成便于AI查找的形式

## 只修改源文件，其他文件用生成工具重新生成 确定规范的技能文档，并将生成的集成内容、清单或特定平台的投影视为派生物。编辑权威来源及其引用，然后使用仓库的生成器重新生成派生物。 绝不手动编辑由CI管理的产物。在持续集成中保留检查模式，使其在内存或临时区域中重新生成内容，并在已提交的派生物偏离权威来源时判定失败。 当同一技能通过多个平台分发时，应共享内容，而不是维护多个分支版本。记录由哪个文件管理内容、元数据和版本值，防止贡献者创建相互竞争的权威来源。 将安装方法和最终用户的使用方法放在贡献者指令之外。贡献者文档应说明维护、验证、测试和发布行为，不要重复产品指南。 ## 选择路径的信息放在入口文档，详细步骤放进参考文件 将主要技能文档用作检索入口，仅在需要时加载详细参考资料。按以下方式放置内容： - 将决策框架和高频模式放在入口文档中； - 将详细指南、模板和扩展示例放在参考文件中； - 将基准场景和决策依据记录放在测试文档中； - 将安装方法和使用方法放在面向用户的文档中； - 将贡献者流程的细节放在贡献指南中。 在入口文档与相邻参考资料之间使用稳定的相对链接。即使重组较低层级的子节，也要保留路由表使用的顶层参考锚点。 采用一项放置测试：如果某个项目决定选择哪条路径，就将其保留在入口附近；如果它深入说明如何执行一条已经选定的路径，就将其移到参考资料中。 ## 先放判断表，用简短直接的指令来写 针对能够分类意图、选择分支并执行的智能体进行优化，而不是针对从头到尾阅读指南的读者。 当多种方法都有效时，在操作手册之前放置紧凑的决策表。每一节都按以下顺序组织： 1. 决策表； 2. 默认流程； 3. 替代方案； 4. 简洁规则和易错点。 使用祈使语气，每个项目符号只表达一个事实。将“你应该考虑”“请注意”或“请记住”等建议性铺垫改为直接行动。对于不明显的区别，优先使用简短的肯定规则和否定规则。 每个表格、示例和代码块都必须补充尚未陈述的事实。如果流程本身已传达指令，应去掉前后差异、重复的理由说明、教学性旁白和仅为追求完整而添加的示例。 理由说明最多保留为开头的一句话。为每个子节设定词元量目标；如果超出目标，应拆分或压缩该节，但不得去掉决策标准、必要操作、约束或例外。 ## 修改后自动检查文档结构，并测试AI的行为 使验证方式与产物相匹配。面向文档的技能可能不需要编译，但仍然需要自动结构检查和手动行为测试。 自动检查必需的frontmatter字段、命名规则、行数或词元量预算、内部链接、生成产物的同步状态以及仓库特有的lint规则。将宽松的大小目标视为警告，将严格的完整性约束视为失败。 对于内容变更： 1. 编辑规范技能或参考资料； 2. 运行本地结构验证； 3. 在宿主环境中重新加载技能； 4. 执行会进入已变更分支的现实用户查询； 5. 将行为与基准场景进行比较，检查是否出现回归。 要求在拉取请求中提供受影响场景的变更前后证据。对于实质性的信息架构变更，应安排独立审查，重点检查检索结构、压缩方式和缺失的决策分支。 ## 必须通过拉取请求检查，版本号交给自动发布设置 保护主分支：要求使用拉取请求、通过验证检查，并使用符合约定式提交规范的有效标题。如果变更通过压缩合并，并且拉取请求标题会成为发布提交，就必须验证该标题，因为它将决定版本。 将约定式变更类型映射到版本增量，并提供明确的重大变更信号。让发布工作流在一次发布变更中更新变更日志、权威版本元数据、平台清单和生成产物。 绝不手动编辑需要保持同步的版本号。只保留一个权威版本来源，并在创建标签之前由发布流水线将其传播到各处。 合并前确认： - 生成产物与权威来源一致； - 决策表位于包含分支的操作手册之前； - 冗余铺垫和示例已经去掉； - 用于路由的锚点保持稳定； - 已变更的基准场景包含证据； - 必需的验证和标题检查均已通过。