agent-skill-authoring

Agent 技能编写

每当你创建、完善、拆分、合并、重命名或审查 Agent 技能，或设计其采用情况的评估时，都使用此能力。它能将持久有效的惯例转化为格式完善、易于发现的技能，并为作者提供比较契约，以便评估规则修订，而不会混淆不同行为的证据。

此处编写的技能遵循 agentskills.io 格式。对于宿主项目当前启用的技能清单和主题到技能的路由，请以各技能自身的 description 发现元数据和技能根目录下的目录列表为准；如果宿主还维护书面索引（例如 AGENTS.md），也要确保其保持同步。

指南：

• MUST 运行与改动内容对应的内置校验器——编辑 frontmatter 后运行 scripts/check-skill-frontmatter.mjs，编辑正文后运行 scripts/check-skill-body.mjs，添加、移动或重命名引用文件后运行 scripts/check-skill-references.mjs；如果不确定，则运行全部三个校验器。它们共同构成了本技能未在其他地方说明的 frontmatter、命名、发现长度上限和引用关联规则的强制执行路径（参见 audit-checklist.md）。
• SHOULD 当任何任务揭示了可复用惯例、过时指南、反复出现的审查问题或缺失的项目规则时，提议或实施技能更新——维护技能应当发生在工作揭示持久经验之时，而不是每次小范围修复之后。
• SHOULD 如果工作没有产生可泛化的经验，则跳过技能维护，并说明已跳过。

本文档中的关键词 “MUST”、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、“RECOMMENDED”、“MAY” 和 “OPTIONAL” 应按照 RFC 2119 中的描述进行解释。

范围界定与 MECE

请参见 scoping-and-mece.md，了解以下内容：

• 如何选择连贯的技能边界、技能名称、拆分、合并或事实来源位置
• 添加新指南之前如何检查与相邻技能的重叠
• 如何将可移植的判断和工作流含义与项目策略、宿主执行和技能分发区分开来
• 迁移详细规则之前如何对混合段落和引用进行分类
• 当特定于供应商或运行器的技能隶属于工具无关的上层技能时，如何将每个章节归类为机制或判断
• 如何将章节长度和主题增长作为重组信号

能力表述

请参见 capability-framing.md，了解以下内容：

• 如何将技能表述为 Agent 获得的能力，而非其阅读的文档
• 如何命名技能所支持的活动，以及应避免的文档式后缀
• description 的开头分句、H1 和开篇段落应采用何种语气
• 如何按照固定顺序重新组织现有的指南式技能，同时不改变其要求

Frontmatter 与命名

请参见 frontmatter-and-naming.md，了解以下内容：

• 如何创建或编辑影响发现的 SKILL.md frontmatter
• 如何区分标准必需和可选元数据与宿主特有的调用控制项
• 如何选择技能目录名称，并使其与 name 字段保持一致
• 如何根据选定的宿主和分发路径评估宿主项目的 harness 字段

描述编写

请参阅 description-writing.md，了解如何：

• 起草、精简或审核 description 字段，确保不超过字节上限
• 理解四槽约定——触发条件、身份、边界、覆盖范围——以及为什么只有最后一项可以因宿主的列表截断而牺牲
• 将触发条件和身份融合为一个开篇从句，以及两个单独使用时不成立的半句：单纯的词元列表，以及“The ability to …”
• 说明技能拒绝服务的场景，同时列出将竞争技能引导至其他位置的交接方式
• 加入用户可能使用的表达方式和基于症状的触发条件，同时避免过度扩大技能范围
• 了解约 640 字节这一语料库均值的目标名称，以及为什么它是重心而非每项技能的上限

正文内容风格

请参阅 body-content-style.md，了解如何：

• 编写或修改实质性的技能正文或参考文件章节
• 平衡简洁的主题说明、示例和指南条目
• 在限定版本或复现供应商选项范围的章节中引用上游文档 URL
• 将规范性的 RFC-2119 要求条目放在详细参考内容中，而非父级路由章节

渐进式披露

SKILL.md 只包含三项内容：这项能力是什么、在其范围内始终适用的规则，以及说明何时应阅读哪份参考资料的路由信息。其他所有规范性陈述——MUST 或 SHOULD 背后的细节、流程、表格、示例——都应放在参考资料中。判断某条规则是否应保留在正文中的标准，是读者是否需要在作出路由决策之前了解它，而不是这条规则是否重要：对于变更循环能力，必须在读者选择实现参考资料之前，让其了解只读工作与变更之间的区别。作出路由决策之前也需要了解本约定，因此要在此处说明，而不是留在下方的链接所指向的文件中；这也是紧随其后直接说明承重规则测试，而不将其延后说明的原因。

如果 Agent 加载 SKILL.md 后不打开任何参考资料，就会因缺少某条规则而产出错误结果，那么这条规则就是承重规则。规则陈述应保留在所属参考资料中；上级路由信息应列出该参考资料适用的情形。单独再列出这些情形作为「必须阅读」条目，不会增加任何选择信息。因此，路由信息只包含 See ... for: 或 See ... when 链接，以及描述适用情形的条目，不包含 **Guidelines:** 区块。

指南：

• 当 Agent 仅加载 SKILL.md 就会因缺少某条规则而产出错误结果时，MUST 将其视为承重规则；此类规则包括固定顺序、封闭集合，或违反后无法仅凭输出本身显而易见的约束。其他情况则视为细化说明。
• MUST 将承重规则本身的陈述、其 RFC-2119 条目，以及所有细化说明，都放在适用的参考文件中，而不是 SKILL.md。
• MUST 将参考资料路由限制为 See ... for: 或 See ... when 链接，后接描述适用情形、用例或咨询该参考资料的条件的条目。
• MUST NOT 在参考资料路由中附加 **Guidelines:** 区块，即使该区块为空，或只包含阅读义务也不例外；应在描述性条目中说明选择参考资料的条件。
• 一旦参考资料中已陈述承重规则，MUST NOT 在 SKILL.md 中重述该规则或其 RFC-2119 条目，以下述例外情况为准。
• 如果某条规则的触发条件在其所属技能的范围内无条件成立，MUST 将规则本身保留在 SKILL.md 中，绝不可移至参考资料。每一轮都会触发的链接只会增加阅读成本，却毫无意义。

有关以下内容，请参阅 progressive-disclosure.md：

• 判断某项技能应保留为单文件，还是拆分到 references/ 中
• 三部分角色约定和完整的「作出路由决策之前需要了解」测试，以及承重规则测试和无条件范围例外之间的关系
• 承重规则测试的完整分类表，以及参考资料路由所列出的选择条件
• 表明技能或参考文件过大的尺寸阈值
• 拆分技能或重组其参考资料布局时，采用仅含描述性内容的上级路由章节格式
• 将参考资料选择条件表述得足够具体，以便跳过无关的参考资料
• 直接说明路由条目所指向的事实——按名称指出标志、限制或规则——而不是宣告存在该事实
• 避免在上级路由条目中使用 RFC-2119 风格的要求关键词，使其保持为路由提示，而非重复规则
• 判断正文中的规则应放在路由列表的什么位置

交叉引用与发现

请参阅 cross-referencing.md，了解如何：

• 添加、重命名、移动、删除或链接技能和参考文件
• 选择唯一事实来源，而不是在多个技能中复制详细规则
• 使用基于主题的跨技能引用、验证技能内相对链接，并保持技能发现信息最新（以及宿主维护的任何书面索引）
• 仅路由到适用的负责人和宿主，包括可选负责人或项目宿主文档不存在的情况

项目技能原型

请参阅 project-skill-archetypes.md，了解如何：

• 创建脚手架流程所需的项目专属技能：结构、组件和 UI/设计
• 使用三方所有权关系，以及每种原型的骨架、主题清单或表格模式
• 通过完整示例和机械化边界检查扩展原型骨架

技能采用评估设计

请参阅 skill-adoption-evaluation.md，了解如何：

• 设计技能采用评估，或在执行前比较有意进行的规则修订
• 冻结任务、处理、评分者、机会和声明范围约定，同时不将评分者答案提供给执行者材料
• 区分自然任务和边界控制，并保留不完整样本和零适用样本群体
• 区分合成报告检查与实时资格判定，仅向范围覆盖充分的 QA 实践提供路由证据充分性，并在其他情况下保留审查限制

审计与验证

请参阅 audit-checklist.md，了解如何：

• 审计多个技能，或报告技能树质量
• 运行三个捆绑的结构验证器——check-skill-frontmatter.mjs、check-skill-body.mjs 和 check-skill-references.mjs——以及它们分别用于检查哪类编辑
• 按计划运行捆绑的链接时效审计（scripts/link-freshness/check.mjs），以发现引用的供应商 URL 是否已返回 404；了解为什么只有确认失效的链接才会导致检查失败，以及为什么在其上设置 pull_request 触发器会构成请求伪造原语
• 检查清单、技能发现、章节结构、RFC-2119 要求项、基于主题的跨技能引用和相对链接
• 识别重叠、过时假设、孤立引用和缺失的事实来源链接
• 应用所有权和可移植性清单，避免将有界更改扩大为整个库的迁移

受保护的 Markdownlint 执行

请参阅 markdownlint-execution.md，了解如何：

• 在使用方项目中安装捆绑的原生 ESM 包，而不导入作者检出目录中的内容
• 声明技能/集合根目录、原始来源快照和有针对性的部分检查
• 在不使用行内、配置或忽略抑制的情况下运行 AS001 实际 YAML 检查和 AS010 显式围栏闭合检查
• 区分真正的警示与加载/运行时故障及有效覆盖缺口
• 扩展共享规则/上下文执行，同时保留现有结构和网络审计