技能（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/”或等效项；如果项目没有技能或索引，则省略或替换为该项目的顶级资产和目录，并相应地调整参考表。

附录：输出合约 (Appendix: Output Contract)

本技能产出 AGENTS.md 或修订建议：

元素	格式	必填字段	路径模式
AGENTS.md 主体	Markdown	章节：项目身份 / 权威源链 / 行为期望 / 入口指令 / 路由表	项目根 AGENTS.md
权威源链	列表项	自顶向下排列，例如 AGENTS.md > specs/ > protocols/ > rules/ > docs/	「权威源链」节
路由表	表格	trigger / target_skill / scope / handoff_artifact	「路由表」节
审计模式输出	Markdown	章节：缺口清单 / 修订 diff 建议；不直接覆写 AGENTS.md 时使用	临时输出，不落盘

generate-agent-entry