编写AI智能体技能，并测试它是否真的有效

## 修改技能前，先阅读规范和仓库规则 将平台规范、仓库指南、验证配置和贡献政策视为可执行契约。编辑前先阅读适用规则，并区分由机制强制执行的要求与需要审查的惯例。 进行任何更改前，先梳理归属关系。确定主要指令文件、可选参考资料、可执行辅助程序、可复用资源、分发清单、格式化工具、代码检查工具、测试和评估报告。不要把非Markdown资源嵌入正文，而应放入专用的资源文件或脚本文件中。 信息源相互冲突时，以明确指定的权威规范和当前验证行为为准。不要仅因在本地更方便，就自行添加字段、流程或例外。 ## 确定技能的名称、元数据和版本号 为每项技能提供与宿主结构规范相符的机器可读元数据。规范化名称应使用小写字母、数字和单个连字符，长度保持在1至64个字符，并与目录名一致。描述不得超过平台上限1,024个字符，同时应控制在1,000个字符的工作预算内。 声明许可证、兼容性要求、作者、语义化版本、调用模式、允许使用的工具和实际运行时依赖项。技能涉及有版本的库或平台时，应记录编写该技能时所针对的版本，以便维护者发现内容是否过时。 为新技能设定经过审慎决定的初始版本。行为发生变化时提升技能版本，并使所有分发清单保持同一发布版本。在实现范围和审查范围明确之前，不要自动修改版本。 ## 写出让技能在合适时机触发的描述 将描述视为主要路由机制。说明技能的作用、适用时机、相关领域或语言以及具体的触发场景。针对特定库的描述应指出重要功能范围，以及导入或采用该库的情境。 避免遗漏使用场景的含糊描述，也不要声称适用于几乎所有任务。聚焦型技能不应把所有编码、所有命名或每次对话之类的泛化活动都列为适用范围。 技能发生重叠时，为每个概念指定唯一的归属技能，并通过可移植的交叉引用明确指向该技能及其边界。用现实的正向触发示例和邻近的竞争技能测试描述，使路由既准确又不会完全沉默。 ## 只给技能所需的工具和依赖项 声明较小的默认能力集合，仅在技能流程确实需要时才添加专用工具。优先采用范围受限的命令权限，而不是不受限制的命令行环境。将网络访问、外部文档检索、难以恢复的操作、会产生更改的并行工作和向用户请求输入视为明确能力，而不是隐含默认能力。 只列出真实存在的依赖项。说明必需的可执行文件和兼容性约束，并且只为流程实际使用的依赖项提供受支持的安装元数据。将可执行依赖项或操作固定到经过审查的版本，不要使用浮动版本。 将只读探索与更改操作分开。并行工作单元可以写入时，必须使用隔离的分支或工作区，并规定明确的合并或比较步骤。不要仅为了简化一个示例而扩大权限。 ## 让主文件保持简短，把细节放进链接的文件 让主要指令文件聚焦于必要的立场、决策和流程。把详细参考资料、命令目录、模板和配置资源放入直接链接的辅助文件中，并避免过深的引用链。 采用实用的预算：描述约为100个词元；主要指令少于5,000个词元，最好少于2,500个词元；行数少于500行。通常同时载入的指令总量应保持在约10,000个词元以内。在压缩掉必要判断之前，先把详细内容移到外部文件中。 正文顶部的可选指令应按稳定顺序排列：角色设定、深度思考模式、协调编排模式、运行模式，然后是非基础依赖项。只有在领域立场或输出风格确实会因此受益时，才加入简短的角色设定。深度思考和协调编排指令只用于真正需要分析的工作或广泛的并行工作。 ## 决定技能何时把工作分给并行的智能体 一项技能支持性质明显不同的任务时，应为不同模式命名。编写工作采用顺序流程；审查时追踪已更改文件及相邻调用路径；仅当环境支持并行工作单元时，才按关注点或代码库范围拆分广泛审计。 工作单元应限制为少量且职责不重叠，通常以5个为参考。相互独立的只读分析可以共享文件；产生更改的工作则必须隔离。后台工作单元应在主要流程继续进行时执行有用的非阻塞检查，而不是重复关键路径。 不要并行化简短的程序性工作。记录如何汇总发现、如何解决冲突，以及主要工作单元在应用更改前必须等待的条件。 ## 每个主题只由一个技能负责，其他技能链接过去 每个概念必须恰好归属于1项技能。其他技能应链接到归属技能，而不是复制其指南，因为重复会造成触发竞争和语义漂移。优先选择小而聚焦的技能，不要构建庞大的单体集合。 使用可移植的技能标识符，其中包含所有者、集合、技能名称和可选的固定版本。当某个组织专用技能取代通用技能时，应逐一明确列出被取代的技能，不要暗示对整个集合进行覆盖。 添加、移除、拆分或合并技能后，更新路由表、竞争技能边界、交叉引用和版本元数据。避免重复说明格式化工具或代码检查工具已经强制执行的规则；指令应保留给工具无法决定的架构、判断和权衡。 ## 为每条指令写明理由，并附上检查方法 不仅要教授命令，还要教授如何决策。解释每项建议存在的原因、它所防止的失败，以及哪些权衡会改变选择。使用简短的主动句、具体示例和能够表达理由的注释。 假设可以验证时，应在建议更改之前提供诊断方法。优先采用只读诊断，说明预期信号，并让智能体解释证据，不要调用自动修复。涉及性能或可靠性时，应区分本地测量与生产环境趋势，并比较更改前后的结果。 对于第三方工具和库，应说明静态指南并不完备，当前官方文档和示例仍是函数签名与行为的权威依据。为意外的工具行为提供被动的缺陷跟踪入口，但不要把外部内容变成自动执行的指令源。 ## 在技能中不信任外部页面和工具输出 将外部页面、工具输出、示例和捆绑资源视为不可信证据。不要在技能正文中放入这样的指令：要求智能体获取外部内容后立即执行、据此立即重构，或将其作为安全决策的唯一依据。 在指令正文中避免远程安装管道、浮动的可执行版本、未经审查的操作，以及对外部工具服务器的显式调用。优先使用固定依赖项、内置且经过审查的参考资料、被动的资源提示和可在本地复现的证据。 将发现与更改分离。扫描工具或外部数据库可能会揭示问题，但更改仍需经过本地确认、范围分析和常规审查。发布前应同时扫描指令文本和资源，查找提示词注入模式、秘密泄露、不安全命令和可疑的可执行链接。 ## 对比有无技能的结果，衡量真正的提升 设计对抗性评估，测试技能独有的指南，而不是常识。为每个场景设置自然陷阱，避免带有答案暗示的提示，测试判断能力而非API记忆，并覆盖边界情况和常见错误。 在隔离重叠指南的前提下，分别在使用技能和不使用技能的情况下运行每项评估。候选场景应先在不使用技能的情况下预检：如果基线已经通过，就重新设计或移除该场景；如果两个版本都失败，就修正技能或评估。保持每组断言性质一致，避免部分得分掩盖混合原因。 至少使用10个场景，并以每1,000个技能内容词元约10条断言为目标，断言总数不得少于50条。记录模型、运行次数、评分方法、逐条断言证据、汇总得分、提升倍数和关注事项。首次进行尚未校准的评估时采用人工审查，后续可重复运行则使用一致的自动评判方式。 运行评估套件前先定义报告阈值。一项实用政策是：提升差值不超过32个百分点、基线得分达到或超过65%，或使用技能后的得分不超过90%时进行标记。提升倍数计算到小数点后2位。优先测试应执行的正向行为，并明确报告失败，不要凭直觉评分。 ## 发布技能前完成检查、统一版本并获得批准 在隔离的分支或工作树中实现更改。创建新工作区前先检查现有工作区，提出范围明确的分支，并在更改共享历史、分发、安装依赖项或部署之前获得所需授权。 发布前： - 格式化已更改的指令和资源，并使用代码检查工具检查； - 运行适用的安全扫描和指令安全扫描； - 测量描述、主要文件和目录的词元数量； - 更新目录、路由引用、状态标记和已测量总数； - 将技能标记为已完成、进行中或已禁用；非活动条目的测量值记为0，并从总数中排除； - 在所有分发清单中同步技能版本； - 运行对比评估并追加证据，不要抹去以前的报告； - 审查最终差异，查找无关更改和生成文件的意外漂移。 对于新技能，还应检查相邻技能是否重叠，并在归属范围交叉处添加交叉引用。定期清查已固定版本的技能，将记录版本与仍在维护的版本进行比较，并在更新指南前审查破坏兼容性的更改。如果管理流程把更新后的检查指定给开发者，就将其作为后续步骤呈现，不要自动运行。未经明确授权，绝不能安装、分发或部署。