整理面向 AI 的研究技能库，只发布检查过的技能

## 把每个技能归入研究流程中的一个阶段 在选择文件夹之前，先定义技能库的使命。面向研究的集合应支持从提出问题和文献综述，到构思、数据准备、实验、训练、评估、部署及沟通的完整路径。 使用编号或其他稳定的类别来反映该生命周期。保留一个中央编排技能，由它将工作分派给专门技能，但不重复这些技能的详细指导。 对于每个拟议的技能： - 确定其生命周期阶段和一个归属类别。 - 说明它解决的用户问题以及使用条件。 - 列出相邻的替代方案，并说明它们在什么情况下更合适。 - 避免范围重叠，防止同一任务看起来有两个负责人。 将分类体系视为导航契约。每当归属关系或收录内容发生变化时，都要更新目录、数量、说明和路线图。 ## 把一个技能需要的文件都放进同一个文件夹 为每个技能建立自己的目录，并放入必需的主指南。只添加该技能需要的辅助文件夹： - `references/`：存放深入的官方文档、API说明、教程、问题模式和发布历史。 - `scripts/`：存放可重复执行的辅助操作。 - `templates/`：存放可复用的起点。 - `examples/`：存放完整且有代表性的实现。 - `assets/`：存放指南使用的非代码材料。 主指南是入口，而不是百科全书。它应说明操作路径，并直接链接到下一层的详细参考资料。不要创建这样的链条：一份参考资料将读者引向另一份参考资料，读者必须继续跳转才能找到必需的指示。 将执行技能所需的所有文件保留在包内，使验证、归档创建和注册中心同步都在一个清晰的边界内运行。 ## 在主指南开头写好名称、版本等固定项目 每份主指南都应以有效的YAML前置元数据开头，并采用固定的字段契约： - `name`：唯一的kebab-case标识符，最好采用描述活动的动名词。 - `description`：采用第三人称的文本，同时说明技能的作用及其使用时机。 - `version`：每当行为或指导发生变化时都要更新的语义化版本。 - `author`：注册中心来源分类所使用的归属值。 - `license`：分发许可证。 - `tags`：采用标题式大小写的术语，但约定俗成的缩略语保持大写。 - `dependencies`：带有明确版本约束的可选包。 除非YAML语法要求，否则不要为标量值加引号。说明应短于配置的字符上限，并避免使用helper、tools或utilities等含糊的标识符。 通过解析而不是目视检查来验证描述符。将缺少必填字段、版本无效、名称重复和依赖关系格式错误视为阻断性错误。 ## 主指南保持简短，详细内容移到参考资料 主指南以200到500行为目标。如果必要指导超过500行，应将高级细节移入可直接访问的参考文件，不得压缩掉必要的判断，也不得任由入口无限增长。 指南应包含： - 简洁的目的和明确的触发条件。 - 与相关替代方案的比较。 - 针对复杂用例的两到三个完整工作流。 - 在顺序重要时可直接复制使用的检查清单。 - 具体的输入和输出示例。 - 用于验证、纠正并重复质量关键型工作的反馈循环。 - 包含具体解决方法的常见问题部分。 假定读者具备相应能力。说明领域特定的选择和失败模式，而不是任务已经隐含的基本概念。为每个围栏式代码示例指定语言标识符。 使用权威来源构建充实的参考资料；当领域需要时，设定明确的覆盖目标，例如约300 KB。不得为了达到大小指标而填充文档；目标仍然是完整性、可追溯性和实际用途。 ## 新增或改进技能时，每次都按同样的步骤做 对于新技能： 1. 选择已获批准的路线图项目和归属类别。 2. 创建标准包结构。 3. 在扩展正文之前编写并验证描述符。 4. 构建主要工作流和决策指导。 5. 根据需要添加可直接访问的参考资料、辅助程序、模板和示例。 6. 使用有代表性的真实任务测试技能。 7. 在同一变更中更新目录、统计信息和路线图。 对于现有技能，应保留描述符契约、递增版本、使主指南保持在限制内、补充缺失的工作流或故障排除内容，并重新运行有代表性的用例。 使用功能分支和范围集中的审查请求。将整个包及其目录变更一并提交，使仓库绝不会宣称提供一个不完整的技能。 ## 用自动检查和真实任务来检查技能 在审查之前运行机械检查： - 确认主文件存在且其前置元数据能够解析。 - 对照200到500行的目标检查主指南行数。 - 验证每个代码围栏都声明了语言。 - 按照选定的目标衡量参考资料覆盖度。 - 检查被引用的文件是否恰好位于主指南下一层。 - 确认名称、标签、版本和依赖关系符合各自的模式。 然后执行行为验证： - 使用现实输入运行每个主要工作流。 - 验证明示的输出和恢复步骤。 - 至少触发一种常见失败。 - 确认当该技能不是正确工具时会推荐替代方案。 - 每次进行实质性编辑后都要重复验证。 庞大的参考资料文件夹无法弥补含糊的工作流，精美的概述也无法弥补无法使用的示例。 ## 审批后自动把有改动的技能上传到技能目录 默认分支上的变更获得批准后，检测哪些顶层技能包发生了变化。对于每个发生变更的包： 1. 要求提供主指南并解析其描述符。 2. 按照声明的归属政策对来源进行分类。 3. 将完整的包归档，但排除操作系统和版本控制产生的隐藏文件。 4. 将归档上传到匹配的注册中心命名空间。 5. 创建或更新注册中心记录。 6. 报告被跳过或失败的包，不得暗中将其视为已同步。 端点和身份验证值只能存储在自动化平台的机密存储区中。应支持手动触发以用于恢复和测试，但必须确保自动模式与手动模式运行相同的验证和打包逻辑。 使用无害的版本化变更验证工作流，检查自动化运行，确认注册中心记录和归档；不要仅仅为了触发流水线而使用未经审查的编辑。 ## 只有版本号变了才发布新的包 以默认分支上包描述符的版本变更驱动包的发布。仅变更锁文件不得发布新版本。 使用包管理器的版本命令，使描述符和锁文件同步前进。根据兼容性选择补丁版本、次版本或主版本；只有当仓库的发布流程要求单独提交时，才抑制自动创建版本控制标签。 通过已配置的可信发布者进行身份验证，不要使用长期有效的注册中心令牌。为每个已发布的制品附加构建来源证明或同等的供应链认证。 发布之前，验证： - 可信发布者的身份与仓库名称和工作流名称完全匹配。 - 环境变量没有使用过期令牌覆盖可信身份验证。 - 能够从已提交的锁文件完成全新安装。 - 新版本与上一个修订版不同。 - 包内容与经过审查的源内容一致。 如果跳过发布或身份验证失败，应修复版本关卡或可信身份；不得绕过来源证明。 ## 与其增加数量，不如改进现有技能 应根据可执行的专业知识而不是目录数量来评判技能库。有用的技能会将可靠实践提炼成智能体可以遵循、验证并从故障中恢复的形式。 合并之前，确认： - 范围适合一个类别，且不与现有负责人重复。 - 描述符、命名和版本规则通过检查。 - 主指南保持聚焦，所有必需细节仍然可以访问。 - 在需要之处提供了工作流、检查清单、示例、替代方案和故障排除内容。 - 真实任务验证了指导。 - 目录、路线图、归档自动化和包发布数据保持一致。 与其添加近乎重复的技能，不如改进现有技能；与其提供大量浅薄示例，不如提供一个带有有效反馈循环的完整工作流。当某项指标与清晰度或正确性冲突时，应保留有用的决策指导，并记录该指标为何不是合适的替代衡量方式。