name: write-agents-entry
description: 按本文件「产出契约」章节为项目撰写或修订根目录下的 AGENTS.md，建立 Agent 入口与行为契约。
tags: [documentation, eng-standards]
version: 1.0.0
related_skills: [refine-skill-design]
recommended_scope: user

Skill: Agent 入口撰写 (Write Agents Entry)

目的 (Purpose)

按本文件下方「产出契约」章节为项目撰写或修订仓库根目录下的 AGENTS.md，使 Agent 在接触该项目时能明确项目身份、权威来源与行为约定，行为一致、可预期。产出契约内嵌于本 SKILL.md，一次加载即可获得完整规范与执行步骤。

适用场景 (Use Cases)

• 新项目接入：为尚无 AGENTS.md 的仓库新增 Agent 入口，按本文件「产出契约」章节的推荐结构与会节产出初稿。
• 既有入口修订：对已有 AGENTS.md 进行审计与补全，补齐缺失会节（如权威来源、行为约定、引用表），或修正与产出契约不一致的表述。
• 他项目采纳规范：其他项目参考本技能时，通过本文件「产出契约」产出符合「身份、权威、行为约定」三要素的 AGENTS.md 初稿，再按项目实际替换资产类型与路径。
• 自检与合规：对已有 AGENTS.md 做合规检查，按产出契约 §3 会节、§4 内容要求、§6 引用表逐项核对并输出修订建议。

行为要求 (Behavior)

1. 先读规范：执行前须读取本文件「产出契约」章节，以该规范为唯一依据，不臆造会节或省略推荐要素。
2. 收集输入：从用户或上下文中获取项目一句话定位、一级资产类型与目录（如 skills/、rules/、commands/ 及对应 spec 路径）、是否提供 Raw URL、主要描述语言等；若信息不足，按技能交互策略向用户询问。
3. 按会节产出：按产出契约 §3 推荐顺序产出或修订 AGENTS.md：开篇 → 项目身份 → 权威来源 → 行为约定 → 发现与加载（概要）→ 语言与沟通 → 引用表。会节标题可微调，但须保持「身份 → 权威 → 行为 → 操作概要 → 语言 → 引用」的逻辑顺序。
4. 行为约定可执行：行为约定须使用「应当」「须」「不得」等明确措辞，每条可引用对应 spec 或文档；不在 AGENTS.md 内重复 spec/docs 的完整内容，仅做索引与摘要。
5. 引用表完整：引用表须至少包含规范来源、本手册 Raw URL（若适用）、定义与测试 spec、使用与安装、入口索引；路径为相对路径或可解析 URL。
6. 自检后提交：产出或修订完成后，按本技能的「质量检查 (Self-Check)」逐项自审，全部通过后再提交；若用户要求仅做合规审计，则输出修订建议列表而非直接改写文件。

输入与输出 (Input & Output)

输入 (Input)

• 项目一句话定位：本项目是什么（如「面向 Agent 的可治理能力资产库」）。
• 一级资产与目录：资产类型（如 Skill / Rule / Command）、所在目录、定义规范路径（如 spec/skill.md、spec/rule.md、spec/command.md）；若无某类资产可注明「无」或省略。
• 可选：是否提供 AGENTS.md 的 Raw URL、现有 AGENTS.md 或 README 片段（用于修订或补全）、主要描述语言（如简体中文）。

输出 (Output)

• 撰写场景：符合本文件「产出契约」的 AGENTS.md 全文（或与现有内容的 diff / 修订后全文）。
• 审计场景：按产出契约 §3–§6 的合规检查清单与修订建议（缺失会节、引用表缺项、行为约定措辞等），不强制改写文件。

禁止行为 (Restrictions)

• 禁脱离规范：不得增加本文件「产出契约」未规定的会节为「必选」，或删除规范推荐的七类会节中的任一类而不说明理由。
• 禁复制全文：不得将 spec/skill.md、spec/rule.md 等完整内容粘贴进 AGENTS.md；仅允许摘要与指向 spec 的链接。
• 禁模糊约定：行为约定不得使用「尽量」「酌情」等模糊措辞；须使用「应当」「须」「不得」等可执行表述。
• 禁遗漏引用表：引用表不得缺失规范来源、定义/测试/使用/安装 spec、入口索引；若项目无某类索引可注明「不适用」或省略该行。

质量检查 (Self-Check)

• [ ] 规范依据：是否已读取本文件「产出契约」并按 §3 会节顺序产出或修订？
• [ ] 三要素：是否明确包含项目身份、权威来源、行为约定？
• [ ] 会节完整：是否包含开篇、项目身份、权威来源、行为约定、发现与加载（概要）、语言与沟通、引用表？
• [ ] 行为可执行：行为约定是否使用「应当」「须」「不得」等措辞，且每条可对应到 spec 或文档？
• [ ] 引用表：是否至少包含规范来源、本手册 Raw URL（若适用）、定义与测试 spec、使用与安装、入口索引？
• [ ] 无冗余：是否避免在 AGENTS.md 内重复 spec/docs 的完整正文，仅做索引与摘要？

示例 (Examples)

示例一：新项目初稿（最小信息）

输入：项目名：my-cli。一句话定位：一个用于本地文件批量重命名的 CLI 工具。资产：无 skills/rules/commands，仅有 README 与源码。希望为 Agent 提供入口，主要语言简体中文。

预期行为：产出一份 AGENTS.md，包含开篇（本文件是 Agent 入口与契约）、项目身份（一句话 + 资产表，可仅含「文档/源码」等简化类型）、权威来源（定义与目录以 README 或 docs/ 为准）、行为约定（若干条「应当」）、发现与加载（若有 INDEX 或等价物则概要说明，否则简要说明 Agent 如何理解本项目）、语言与沟通（简体中文）、引用表（规范来源、本手册 Raw 若适用、文档与入口链接）。不编造不存在的 spec/ 路径。

示例二：边界情况——修订残缺 AGENTS.md

输入：现有 AGENTS.md 仅有「本项目是 XX」和「请读 INDEX」两段，无权威来源、无行为约定、无引用表。项目有 docs/、README，无 skills/rules/commands。请按本文件「产出契约」补全。

预期行为：在保留现有「项目身份」表述的基础上，补全权威来源（定义与目录以何为准）、行为约定（至少 2–3 条可执行约定，如「以 README 与 docs 为据」「能力列表类询问须先读索引再列举」）、发现与加载（概要）、语言与沟通、引用表。不删除用户已有的正确表述；若项目无 INDEX，引用表中入口索引可写「不适用」或仅列 README/docs。输出修订后全文或 diff，并说明新增了哪些会节。

产出契约：AGENTS.md 撰写规范

以下为本技能产出 AGENTS.md 时所依据的规范，内嵌于本 SKILL.md。供采纳“面向 Agent 的可治理能力资产库（Spec + tests）”形态的项目参考；本项目 AGENTS.md 遵循本规范。

1. 目的与定位

• AGENTS.md 是 AI Agent 与项目交互的唯一入口与契约，通常置于仓库根目录。
• 目的：在 Agent 接触本项目时，明确项目身份、权威来源与行为约定，使 Agent 在本仓库内或引用本仓库时行为一致、可预期。
• 受众：具备文件读取能力的智能体（如 IDE Agent、CLI Agent）；亦可被通过 Raw URL 引用的消费方仓库使用。

2. 首要目标

AGENTS.md 的首要目标不是「教 Agent 如何用技能」或「如何跑测试」，而是建立入口与行为契约。具体包含三件事：

3. 推荐结构与会节

建议按以下顺序组织章节，便于 Agent 与人类可解析、可预期：

会节标题与层级可根据项目习惯调整，但建议保持「身份 → 权威 → 行为 → 操作概要 → 语言 → 引用」的逻辑顺序。

4. 内容要求

• 以可执行约定为主：行为约定宜使用「应当」「须」「不得」等明确措辞，便于 Agent 解析与遵守。
• 不重复 spec 与 docs 的完整内容：AGENTS.md 做索引与摘要，具体定义、测试步骤、安装方式等指向 spec/ 或 docs/ 下对应文件。
• 引用稳定：使用相对路径或可解析的 URL 指向本仓库内的规范与索引；若项目可被 Raw URL 引用，建议在引用表中提供 AGENTS.md 的权威 Raw URL。

5. 格式与风格

• 标题：简短、可解析；可带英文副标题，如「Agent 入口 (Agent Entry)」。
• 长度：建议控制在一页内（约 60–80 行），便于 Agent 一次性加载与解析。
• 语言：与项目主要资产语言一致；若项目约定为简体中文，见 spec/rule.md §0 及技能/命令规范中的语言约定。
• 表格：项目身份、权威来源、引用表等宜用 Markdown 表格呈现，便于结构化解析。

6. 引用表 (Reference)

• 文末应包含引用表，至少列出：规范来源、本手册 Raw URL（若支持通过 Raw 引用）、定义与测试规范（如 spec/skill、spec/rule、spec/command、spec/test）、入口索引（如 skills/INDEX.md、rules/INDEX.md、commands/INDEX.md）。使用约定见 AGENTS.md §4。引用表便于 Agent 与工具在无需爬取全站的情况下跳转到权威文档。

7. 与其他规范的关系

• 使用：发现、注入、自检的运行时约定见 AGENTS.md §4；AGENTS.md 为唯一入口与契约。
• 语言：AGENTS.md 中的描述与沟通约定应与 spec/rule.md 语言与描述一致（若项目采用该规范）。

8. 供他项目参考时的适配

采纳本规范的其他项目可：保留「身份、权威、行为约定」三要素与推荐会节顺序，将「项目身份」替换为本项目的一句话定位与资产表；将「权威来源」「行为约定」「发现与加载」中的路径与规范名替换为本项目的 spec/ 或等价文档路径；若项目无 Skills/Rules/Commands 或 INDEX，可省略或替换为该项目的一级资产与目录约定，引用表相应调整。