技能（Skill）：生成代理条目
目的 (Purpose)
根据下面的“输出合约”部分在存储库根目录编写或修改AGENTS.md，以便当代理接触项目时，它具有明确的项目身份、权威来源和行为期望，并且行为一致且可预测。输出合同嵌入在此 SKILL.md 中，因此一次加载即可提供完整的规范和步骤。
核心目标（Core Objective）
首要目标：生成一个合规的 AGENTS.md 文件，该文件为 AI 代理建立项目身份、权威来源和行为期望。
成功标准（必须满足所有要求）：
- ✅ AGENTS.md 存在：文件写入存储库根目录并提交给版本控制
- ✅ 存在三个核心要素：存在项目身份、权威来源和行为期望部分
- ✅ 七部分完成：开场、项目身份、权威来源、行为、发现/加载摘要、语言/沟通、参考表
- ✅ 可执行的行为：行为期望将“必须”、“应该”或“不得”与可操作的项目一起使用
- ✅ 参考表完整：包含 spec 来源、条目 Raw URL（如适用）、定义规范、使用/安装与条目索引
- ✅ 合同合规性：输出遵循嵌入的输出合同结构和内容需求
验收测试：AI 代理能否阅读此 AGENTS.md 并了解该项目是什么、权威来源在哪里以及在使用该项目时如何表现？
范围边界（范围边界）
本技能负责：
- 从头开始编写新的 AGENTS.md
- 修改现有的 AGENTS.md 以确保合规性
- 根据输出合同审核 AGENTS.md
- 根据嵌入式合约规范生成 AGENTS.md
本技能不负责：
- 编写自述文件（使用“generate-standard-readme”）
- 引导完整的项目文档（使用“bootstrap-docs”）
- 精炼技能设计（使用“精炼技能设计”）
- 编写其他文档类型（超出范围）
转交点：当AGENTS.md编写、提交并通过自检后，移交给项目文档化工作流程或下一个文档化任务。
使用场景（用例）
- 新项目：为没有 AGENTS.md 的存储库添加 Agent 条目；根据输出合同的推荐结构和部分制定初稿。
- 修改现有条目：审核并完成现有的 AGENTS.md（添加缺少的部分，例如权威来源、行为、参考表）或修复与合同不匹配的措辞。
- 采用其他地方的格式：其他项目可以使用该技能的输出合约来生成具有身份、权限和行为的 AGENTS.md，然后替换其项目的资产类型和路径。
- 合规性检查：根据合同审核现有 AGENTS.md（§3 部分、§4 内容、§6 参考表）并输出修订建议。
行为（行为）
- 先阅读合约：在执行之前，阅读此文件的“输出合约”部分，并将其作为唯一的事实来源；不要发明部分或删除推荐元素。
- 收集输入：从用户或上下文获取：单行项目定位、顶级资产类型和目录（例如技能/和规范路径）、是否提供原始 URL、主要描述语言。如果信息丢失，请根据技能的交互政策进行询问。
- 按部分生成：输出或修改合同§3中的AGENTS.md顺序：开放→项目标识→权威来源→行为期望→发现和加载（摘要）→语言和沟通→参考表。章节标题可以调整，但保持顺序：身份→权限→行为→操作摘要→语言→参考。
- 可执行的行为：使用“必须”、“应该”、“不得”（或同等词），以便每个期望都是可操作的；每个项目都可以引用规范或文档。不要将完整的规范/文档粘贴到 AGENTS.md 中；仅索引和总结。
- 完整参考表：至少包括：规格来源、本条目的原始URL（如果适用）、定义规格、使用和安装、条目索引；使用相对路径或可解析的 URL。
- 提交前自检：制作或修改后，运行该技能的自检；全部通过后才提交。如果用户仅要求进行合规性审核，则输出修订列表而不是编辑文件。
输入与输出 (Input & Output)
输入（输入）
- 单行定位：项目是什么（例如“代理优先、治理就绪的能力清单”）。
- 顶级资产和目录：资产类型（例如技能）、目录、规范路径（例如specs/skill.md）；如果类型不存在，请说“无”或省略。
- 可选：AGENTS.md 原始 URL、现有 AGENTS.md 或自述文件摘录（用于修订）、主要描述语言（例如英语）。
输出（输出）
- 创作：满足输出合同的完整 AGENTS.md（或 diff/修订后的全文）。
- 审核：每个合同第 §3–§6 条的合规性检查表和修订建议（缺失部分、参考表差距、行为措辞）；不要强制重写该文件。
限制（限制）
硬边界（Hard Boundaries）
- 不要离开合同：不要将合同不需要的部分添加为“必需”，或者在没有正当理由的情况下删除任何七种推荐的部分类型。
- 不要粘贴完整规范：不要将specs/skill.md或其他规范的完整内容粘贴到AGENTS.md中；仅总结和链接。
- 没有含糊的行为：不要使用“如果可能”、“酌情”等；使用“必须”、“应当”、“不得”（或同等词）。
- 不要省略参考表：该表必须包含规格来源、定义/使用/安装规格、条目索引；如果项目没有索引，请说“N/A”或省略该行。
技能边界 (Skill Boundaries)（避免重叠）
不要做这些（其他技能可以处理它们）：
- 编写 README 文件：创建或更新 README.md → 使用
generate-standard-readme - 引导完整的项目文档：设置完整的文档结构 → 使用
bootstrap-docs - 精炼技能设计：审核或重构 SKILL.md 文件 → 使用
refine-skill-design - 编写其他文档类型：API 文档、用户指南、教程 → 超出范围
何时停止并交接：
- 用户说“AGENTS.md 看起来不错”或“已批准”→ 技能完成，移交给下一个文档化任务
- 用户问“你也可以写自述文件吗？” → 移交给“生成标准自述文件”
- 用户询问“您可以设置所有项目文档吗？” → 移交给“bootstrap-docs”
- 用户问“你能复习一下这个技能吗？” → 交给“精炼技能设计”
自检（Self-Check）
核心成功标准（必须满足所有标准）
- AGENTS.md 存在：写入存储库根目录并提交给版本控制的文件
- 存在三个核心要素：存在项目身份、权威来源和行为期望部分
- 七部分完成：开场、项目身份、权威来源、行为、发现/加载摘要、语言/沟通和参考表
- 可执行行为：行为期望对可操作的项目使用“必须”、“应该”或“不得”
- 参考表完整：包括规范源、条目原始 URL（如果适用）、定义规范、使用/安装和条目索引
- 合同合规性：输出遵循嵌入式输出合同结构和内容 需求
流程质量检查
- 合约读取：执行前我是否读取了输出合约部分？
- 收集输入：我是否收集了所有必需的输入（定位、资产类型、目录）或在丢失时询问？
- 章节顺序：我是否按照合同§3顺序（身份→权限→行为→操作→语言→参考）生成了AGENTS.md？
- 没有规范重复：我是否避免粘贴完整的规范/文档内容而仅索引和总结？
- 可执行语言：我是否使用“必须”/“应该”/“不得”来表达行为期望？
- 参考表：我是否包含了所有必需的元素（规范来源、原始 URL（如果适用）、定义规范、使用/安装、索引）？
验收测试
AI 代理能否阅读此 AGENTS.md 并了解该项目是什么、权威来源在哪里以及在使用该项目时如何表现？
如果否：AGENTS.md 不完整。返回以收集意见或修改部分。
如果是：AGENTS.md 已完成。继续提交并转交。
示例（示例）
示例 1：新项目（最少信息）
输入：项目：my-cli。一行：用于本地批处理文件重命名的 CLI。资产：没有技能，只有自述文件和源代码。想要一个代理入口；主要语言英语。
预期：生成 AGENTS.md，内容包括：打开（此文件是代理条目和合同）、项目标识（一行 + 资产表；可以简化为“文档/源”等）、权威来源（自述文件或文档/中的定义和目录）、行为预期（几个“必须”项目）、发现和加载（如果存在 INDEX 或同等项，则进行摘要，否则代理应如何理解项目）、语言和沟通（英语）、参考表（规范来源、此条目原始（如果适用）、文档和条目链接）。不要发明不存在的规范/路径。
示例 2：边缘情况 — 不完整的 AGENTS.md
输入：现有的AGENTS.md只有“这个项目是XX”和“读取INDEX”，没有权威来源，没有行为，没有参考表。项目有 docs/、README，没有技巧。按照输出合同完成。
预期：保留现有的“项目标识”；添加权威来源（其中存在定义和目录）、行为期望（至少 2-3 个可执行项目，例如“遵循自述文件和文档”、“列出功能时，阅读索引然后枚举”）、发现和加载（摘要）、语言和通信、参考表。请勿删除正确的用户措辞；如果项目没有 INDEX，参考表可以说“N/A”或列出 README/docs。输出修订后的全文或差异并说明添加了哪些部分。
输出（Output）合约：AGENTS.md 创作标准
以下是该技能在制作AGENTS.md时使用的标准；它嵌入在此 SKILL.md 中。采用“代理优先、治理就绪的能力清单（Spec）”形态的项目可以使用；此存储库的 AGENTS.md 紧随其后。
1. 目的和作用
- AGENTS.md 是 AI 代理与项目交互的 单一条目和合约；它通常位于 repo 根目录。
- 目的：当代理接触项目时，定义项目身份、权威来源和行为期望，以便代理在引用存储库时或在引用存储库时表现一致且可预测。
- 受众：可以读取文件的代理（例如 IDE 代理、CLI 代理）；也可以由通过原始 URL 引用它的消费者存储库使用。
2. 主要目标
AGENTS.md 的主要目标不是“教 Agent 如何使用技能”，而是建立入口和行为。这意味着三件事：
| 目标 | 描述 |
|---|---|
| 项目身份 | 一句话说明项目是什么；列出顶级资产类型（例如技能）、其目录和定义规范。 |
| 权威来源 | “定义”和“目录/列表”所在的位置；特工将这些视为事实，而不是口头或分散的文档。 |
| 行为期望 | 代理在引用项目时必须或不可以做什么（例如遵循规范、提交前自检、读取索引然后在列出功能时枚举）。 |
3. 推荐的结构和部分
代理和人类都按以下顺序组织：
| 订单 | 部分 | 内容 |
|---|---|---|
| 1 | 开幕 | 一句话：这个文件是Agent的条目和合同；目的（身份+权威+行为）。 |
| 2 | 项目身份 | 一行定位+资产类型/目录/规格表+目录和清单（如果有）。 |
| 3 | 权威来源 | 定义、目录/列表和使用合同所在的位置；仅提供指针，无详细说明。 |
| 4 | 行为期望 | 特工必须遵循的编号期望；每个都可以引用规范或文档。 |
| 5 | 发现和加载（摘要） | 资产根，如何发现，如何注入； AGENTS.md §4 或同等内容中的详细信息；避免在 AGENTS.md 中重复。 |
| 6 | 语言和沟通 | 主要描述语言和术语；与规格/技能或同等内容保持一致。 |
| 7 | 参考 | 表：规范来源、本条目原始 URL（如果适用）、定义规范、用法和安装、条目索引。 |
章节标题和级别可以遵循项目风格，但保持顺序：身份→权限→行为→操作摘要→语言→参考。
4.内容需求
- 可执行的期望：使用“必须”、“应该”、“不得”（或同等内容），以便代理可以解析和遵循。
- 不要重复规范和文档：AGENTS.md 索引和总结；指向“specs/”或“docs/”以获取完整定义并安装。
- 稳定引用：使用存储库中规范和索引的相对路径或可解析 URL；如果可以通过原始 URL 引用该项目，请在引用表中提供 AGENTS.md 的规范原始 URL。
5. 格式和风格
- 标题：简短且可解析；可选英文字幕（例如“特工进入”）。
- 长度：目标是大约一页（例如 60-80 行），以便代理可以一次性加载和解析。
- 语言：匹配项目的主要资产语言；如果项目使用英语，请参见specs/skill.md语言需求。
- 表格：使用 Markdown 表格作为项目标识、权威来源和结构化解析的参考。
6.参考表
- 以参考表结尾，至少列出：规范源、此条目原始 URL（如果支持原始引用）、定义规范（例如规范/技能）、条目索引（例如技能/INDEX.md）。用法见 AGENTS.md §4。该表允许代理和工具跳转到权威文档，而无需爬行存储库。
7. 与其他规范的关系
- 用法：发现、注入和自检的运行时行为位于 AGENTS.md §4 中； AGENTS.md 是单一条目和合同。
- 语言：AGENTS.md 的描述和沟通期望应与 specs/skill.md 语言需求保持一致（如果项目使用该规范）。
8. 适应其他项目
其他采用该合约的项目可以： 保留三要素（身份、权限、行为）和推荐的节序；将“项目标识”替换为一行定位和资产表；将“权威来源”、“行为”和“发现和加载”中的路径和规范名称替换为“specs/”或等效项；如果项目没有技能或索引，则省略或替换为该项目的顶级资产和目录，并相应地调整参考表。