write-agents-entry

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: Write Agents Entry

Skill: 编写Agent条目

Purpose

目的

Write or revise AGENTS.md at the repo root per the “Output contract” section below, so that when an Agent touches the project it has a clear project identity, authoritative sources, and behavioral expectations, and behaves consistently and predictably. The output contract is embedded in this SKILL.md so one load gives the full spec and steps.

按照下文“输出契约”章节的要求，编写或修订仓库根目录下的AGENTS.md文件，确保Agent接触项目时，能明确了解项目标识、权威来源和行为规范，从而保持行为的一致性和可预测性。本SKILL.md中嵌入了输出契约，加载一次即可获取完整规范和步骤。

Use Cases

适用场景

New project: Add an Agent entry for a repo that has no AGENTS.md; produce a first draft following the output contract’s recommended structure and sections.
Revise existing entry: Audit and complete an existing AGENTS.md (add missing sections such as authoritative sources, behavior, reference table) or fix wording that does not match the contract.
Adopt the format elsewhere: Other projects can use this skill’s output contract to produce an AGENTS.md with identity, authority, and behavior, then replace asset types and paths for their project.
Compliance check: Audit an existing AGENTS.md against the contract (§3 sections, §4 content, §6 reference table) and output revision suggestions.

新项目：为没有AGENTS.md的仓库添加Agent条目；按照输出契约推荐的结构和章节生成初稿。
修订现有条目：审计并完善现有AGENTS.md（补充缺失章节，如权威来源、行为规范、参考表格），或修正不符合契约的表述。
跨项目复用格式：其他项目可使用本Skill的输出契约生成包含标识、权威来源和行为规范的AGENTS.md，再替换为自身项目的资产类型和路径。
合规检查：对照契约（第3章的章节、第4章的内容、第6章的参考表格）审计现有AGENTS.md，并输出修订建议。

Behavior

执行规范

Read the contract first: Before executing, read this file’s “Output contract” section and use it as the only source of truth; do not invent sections or drop recommended elements.
Gather input: From the user or context get: one-line project positioning, top-level asset types and dirs (e.g. skills/ and spec paths), whether a Raw URL is provided, primary description language. If information is missing, ask per the skill’s interaction policy.
Produce by section: Output or revise AGENTS.md in the contract §3 order: opening → Project identity → Authoritative sources → Behavioral expectations → Discovery and loading (summary) → Language and communication → Reference table. Section titles may be adjusted but keep the order: identity → authority → behavior → operations summary → language → reference.
Executable behavior: Use “must,” “shall,” “must not” (or equivalent) so each expectation is actionable; each item can reference a spec or doc. Do not paste full spec/docs into AGENTS.md; only index and summarize.
Complete reference table: Include at least: spec source, this entry’s Raw URL (if applicable), definition specs, usage and install, entry indexes; use relative paths or resolvable URLs.
Self-check before submit: After producing or revising, run this skill’s Self-Check; only submit when all pass. If the user asked only for a compliance audit, output a revision list instead of editing the file.

先阅读契约：执行前需阅读本文件的“输出契约”章节，以此作为唯一的权威依据；不得新增章节或遗漏推荐元素。
收集输入信息：从用户或上下文获取：项目定位一句话总结、顶层资产类型和目录（如skills/和规范路径）、是否提供Raw URL、主要描述语言。若信息缺失，需按照Skill的交互规则询问用户。
按章节生成内容：按照契约第3章的顺序输出或修订AGENTS.md：开篇 → 项目标识 → 权威来源 → 行为规范 → 发现与加载（摘要） → 语言与沟通 → 参考表格。章节标题可适当调整，但需保持顺序：标识 → 权威来源 → 行为规范 → 操作摘要 → 语言 → 参考。
可执行的行为表述：使用“必须”“应当”“禁止”（或等效表述），确保每条规范可落地；每条内容可关联至具体规范或文档。请勿将完整规范/文档内容粘贴到AGENTS.md中，仅做索引和摘要。
完善参考表格：至少包含：规范来源、本条目的Raw URL（若提供）、定义规范、使用与安装说明、条目索引；使用相对路径或可解析的URL。
提交前自检：生成或修订完成后，运行本Skill的自检清单；只有全部通过才可提交。若用户仅要求合规审计，输出修订建议列表而非直接编辑文件。

Input & Output

输入与输出

Input

输入

One-line positioning: What the project is (e.g. “agent-first, governance-ready capability inventory”).
Top-level assets and dirs: Asset types (e.g. Skill), directories, spec paths (e.g. spec/skill.md); if a type is absent, say “none” or omit.
Optional: AGENTS.md Raw URL, existing AGENTS.md or README excerpt (for revision), primary description language (e.g. English).

项目定位一句话总结：项目的核心定位（如“以Agent为核心、符合治理要求的能力清单”）。
顶层资产与目录：资产类型（如Skill）、目录、规范路径（如spec/skill.md）；若某类型不存在，标注“无”或省略。
可选信息：AGENTS.md的Raw URL、现有AGENTS.md或README片段（用于修订）、主要描述语言（如英文）。

Output

输出

Authoring: Full AGENTS.md that satisfies the output contract (or diff / revised full text).
Audit: Compliance checklist and revision suggestions per contract §3–§6 (missing sections, reference table gaps, behavior wording); do not force-rewrite the file.

编写产出：符合输出契约的完整AGENTS.md文件（或差异对比/修订后的完整文本）。
审计产出：对照契约第3-6章生成的合规检查清单和修订建议（缺失章节、参考表格漏洞、行为表述问题）；不得强制重写文件。

Restrictions

限制条件

Do not leave the contract: Do not add sections as “required” that the contract does not require, or remove any of the seven recommended section types without justification.
Do not paste full specs: Do not paste full content of spec/skill.md or other specs into AGENTS.md; only summarize and link.
No vague behavior: Do not use “where possible,” “as appropriate,” etc.; use “must,” “shall,” “must not” (or equivalent).
Do not omit reference table: The table must include spec source, definition/usage/install spec, entry indexes; if the project has no index, say “N/A” or omit that row.

不得偏离契约：不得新增契约未要求的“必填”章节，若无合理理由，不得删除7个推荐章节类型。
不得复制完整规范：请勿将spec/skill.md或其他规范的完整内容粘贴到AGENTS.md中；仅做索引和摘要。
禁止模糊表述：不得使用“尽可能”“视情况而定”等模糊表述；需使用“必须”“应当”“禁止”（或等效表述）。
不得省略参考表格：表格必须至少包含规范来源、本条目的Raw URL（若适用）、定义规范、使用与安装说明、条目索引；若项目无索引，标注“N/A”或省略对应行。

Self-Check

自检清单

Examples

示例

Example 1: New project (minimal info)

示例1：新项目（基础信息）

Input: Project: my-cli. One-line: A CLI for local batch file renaming. Assets: no skills, only README and source. Want an Agent entry; primary language English.

Expected: Produce AGENTS.md with: opening (this file is the Agent entry and contract), project identity (one line + asset table; can be simplified to “docs/source” etc.), authoritative sources (definitions and catalog from README or docs/), behavioral expectations (several “must” items), discovery and loading (summary if INDEX or equivalent exists, else how the Agent should understand the project), language and communication (English), reference table (spec source, this entry Raw if applicable, docs and entry links). Do not invent spec/ paths that do not exist.

输入：项目：my-cli。一句话定位：用于本地批量重命名文件的CLI工具。资产：无Skill，仅包含README和源码。需要生成Agent条目；主要语言为英文。

预期产出：生成AGENTS.md文件，包含：开篇（说明本文件是Agent条目和契约）、项目标识（一句话定位+资产表格；可简化为“docs/源码”等）、权威来源（定义和目录来自README或docs/）、行为规范（多条“必须”条目）、发现与加载（若存在INDEX或等效文件则做摘要，否则说明Agent应如何理解项目）、语言与沟通（英文）、参考表格（规范来源、本条目的Raw URL（若适用）、文档和条目链接）。不得虚构不存在的spec/路径。

Example 2: Edge case — incomplete AGENTS.md

示例2：边缘场景——不完整的AGENTS.md

Input: Existing AGENTS.md has only “This project is XX” and “Read INDEX,” no authoritative sources, no behavior, no reference table. Project has docs/, README, no skills. Complete per the output contract.

Expected: Keep existing “project identity”; add authoritative sources (where definitions and catalog live), behavioral expectations (at least 2–3 executable items, e.g. “Follow README and docs,” “When listing capabilities, read index then enumerate”), discovery and loading (summary), language and communication, reference table. Do not remove correct user wording; if the project has no INDEX, reference table can say “N/A” or list README/docs. Output revised full text or diff and state which sections were added.

输入：现有AGENTS.md仅包含“本项目为XX”和“请阅读INDEX”，缺少权威来源、行为规范和参考表格。项目包含docs/、README，无Skill。需按照输出契约完善。

预期产出：保留现有的“项目标识”；补充权威来源（定义和目录的存放位置）、行为规范（至少2-3条可执行条目，如“遵循README和docs中的要求”“列举能力时，先读取索引再逐一列出”）、发现与加载（摘要）、语言与沟通、参考表格。不得删除用户的正确表述；若项目无INDEX，参考表格可标注“N/A”或列出README/docs。输出修订后的完整文本或差异对比，并说明新增的章节。

Output contract: AGENTS.md authoring standard

输出契约：AGENTS.md编写规范

The following is the standard used by this skill when producing AGENTS.md; it is embedded in this SKILL.md. Projects adopting the “agent-first, governance-ready capability inventory (Spec)” shape can use it; this repo’s AGENTS.md follows it.

以下是本Skill生成AGENTS.md时遵循的标准，已嵌入本SKILL.md中。采用“以Agent为核心、符合治理要求的能力清单（Spec）”架构的项目可直接使用；本仓库的AGENTS.md即遵循此规范。

1. Purpose and role

1. 目的与角色

AGENTS.md is the single entry and contract for AI Agents interacting with the project; it is usually at the repo root.
Purpose: When an Agent touches the project, define project identity, authoritative sources, and behavioral expectations so the Agent behaves consistently and predictably in or when referencing the repo.
Audience: Agents that can read files (e.g. IDE Agent, CLI Agent); can also be used by consumer repos that reference it via Raw URL.

AGENTS.md是AI Agent与项目交互的唯一条目与契约；通常存放于仓库根目录。
目的：当Agent接触项目时，定义项目标识、权威来源和行为规范，确保Agent在仓库内或引用仓库时行为一致且可预测。
受众：可读取文件的Agent（如IDE Agent、CLI Agent）；也可供引用本仓库的其他项目通过Raw URL使用。

2. Primary goals

2. 核心目标

AGENTS.md’s main goal is not “teach the Agent how to use skills” but to establish entry and behavior. That means three things:

Goal	Description
Project identity	One sentence on what the project is; list top-level asset types (e.g. Skills), their directories, and definition specs.
Authoritative sources	Where “definitions” and “catalog/list” live; the Agent treats these as truth, not verbal or scattered docs.
Behavioral expectations	What the Agent must or must not do in or when referencing the project (e.g. follow spec, self-check before submit, read index then enumerate when listing capabilities).

AGENTS.md的核心目标并非“教Agent如何使用Skill”，而是确立交互入口与行为准则。具体包含三点：

目标	描述
项目标识	一句话说明项目定位；列出顶层资产类型（如Skill）、对应的目录和定义规范。
权威来源	指明“定义”和“目录/清单”的存放位置；Agent需将这些内容视为唯一依据，而非口头说明或分散的文档。
行为规范	明确Agent在仓库内或引用仓库时必须做/禁止做的事项（如遵循规范、提交前自检、列举能力时先读取索引再逐一列出）。

3. Recommended structure and sections

3. 推荐结构与章节

Organize in this order for both Agents and humans:

Order	Section	Content
1	Opening	One sentence: this file is the Agent entry and contract; purpose (identity + authority + behavior).
2	Project identity	One-line positioning + asset type/dir/spec table + catalog and manifest (if any).
3	Authoritative sources	Where definitions, catalog/list, and usage contract live; pointers only, no long detail.
4	Behavioral expectations	Numbered expectations the Agent must follow; each can reference a spec or doc.
5	Discovery and loading (summary)	Asset root, how to discover, how to inject; details in AGENTS.md §4 or equivalent; avoid repeating in AGENTS.md.
6	Language and communication	Primary description language and terminology; align with spec/skill or equivalent.
7	Reference	Table: spec source, this entry Raw URL (if applicable), definition spec, usage and install, entry indexes.

Section titles and levels can follow project style, but keep the order: identity → authority → behavior → operations summary → language → reference.

需按照以下顺序组织内容，兼顾Agent和人类的可读性：

顺序	章节	内容
1	开篇	一句话说明：本文件是Agent条目与契约；核心作用（标识+权威来源+行为规范）。
2	项目标识	一句话定位+资产类型/目录/规范表格+目录清单与清单文件（若有）。
3	权威来源	指明定义、目录/清单、使用契约的存放位置；仅提供指向，无需详细内容。
4	行为规范	列出Agent必须遵循的编号规范；每条可关联至具体规范或文档。
5	发现与加载（摘要）	资产根目录、发现方式、注入方式；详细内容见AGENTS.md第4章或等效章节；避免在AGENTS.md中重复。
6	语言与沟通	主要描述语言和术语；需与spec/skill或等效文件保持一致。
7	参考表格	表格：规范来源、本条目的Raw URL（若适用）、定义规范、使用与安装说明、条目索引。

章节标题和层级可遵循项目风格，但需保持顺序：标识 → 权威来源 → 行为规范 → 操作摘要 → 语言 → 参考。

4. Content requirements

4. 内容要求

Executable expectations: Use “must,” “shall,” “must not” (or equivalent) so the Agent can parse and follow.
Do not duplicate spec and docs: AGENTS.md indexes and summarizes; point to
```
spec/
```
or
```
docs/
```
for full definitions and install.
Stable references: Use relative paths or resolvable URLs to specs and indexes in the repo; if the project can be referenced via Raw URL, provide the canonical Raw URL for AGENTS.md in the reference table.

可执行规范：使用“必须”“应当”“禁止”（或等效表述），确保Agent可解析并遵循。
避免重复规范与文档：AGENTS.md仅做索引和摘要；完整定义和安装说明需指向
```
spec/
```
或
```
docs/
```
目录。
稳定引用：使用仓库内的相对路径或可解析的URL指向规范和索引；若项目支持通过Raw URL引用，需在参考表格中提供AGENTS.md的标准Raw URL。

5. Format and style

5. 格式与风格

Headings: Short and parseable; optional English subtitle (e.g. “Agent Entry”).
Length: Aim for about one page (e.g. 60–80 lines) so the Agent can load and parse in one go.
Language: Match the project’s main asset language; if the project uses English, see spec/skill.md language requirements.
Tables: Use Markdown tables for project identity, authoritative sources, and reference for structured parsing.

标题：简洁且易于解析；可添加英文副标题（如“Agent Entry”）。
篇幅：控制在约一页（如60-80行），确保Agent可一次性加载并解析。
语言：与项目主要资产的语言保持一致；若项目使用英文，需遵循spec/skill.md的语言要求。
表格：使用Markdown表格展示项目标识、权威来源和参考内容，便于结构化解析。

6. Reference table

6. 参考表格

End with a reference table listing at least: spec source, this entry Raw URL (if Raw reference is supported), definition specs (e.g. spec/skill), entry indexes (e.g. skills/INDEX.md). Usage is in AGENTS.md §4. The table lets Agents and tools jump to authoritative docs without crawling the repo.

文件末尾需包含参考表格，至少列出：规范来源、本条目的Raw URL（若支持Raw引用）、定义规范（如spec/skill）、条目索引（如skills/INDEX.md）。使用说明见AGENTS.md第4章。该表格可让Agent和工具直接跳转至权威文档，无需遍历仓库。

7. Relation to other specs

7. 与其他规范的关系

Usage: Runtime behavior for discovery, injection, and self-check is in AGENTS.md §4; AGENTS.md is the single entry and contract.
Language: AGENTS.md’s description and communication expectations should align with spec/skill.md language requirements (if the project uses that spec).

使用说明：发现、注入和自检的运行时行为见AGENTS.md第4章；AGENTS.md是唯一的交互入口与契约。
语言一致性：AGENTS.md的描述和沟通规范需与spec/skill.md的语言要求保持一致（若项目采用该规范）。

8. Adapting for other projects

8. 跨项目适配

Other projects adopting this contract can: keep the three elements (identity, authority, behavior) and the recommended section order; replace “project identity” with their one-line positioning and asset table; replace paths and spec names in “authoritative sources,” “behavior,” and “discovery and loading” with their

spec/

or equivalent; if the project has no Skills or INDEX, omit or replace with that project’s top-level assets and dirs, and adjust the reference table accordingly.

其他项目采用本契约时：需保留三大核心要素（标识、权威来源、行为规范）和推荐的章节顺序；将“项目标识”替换为自身的一句话定位和资产表格；将“权威来源”“行为规范”“发现与加载”中的路径和规范名称替换为自身项目的

spec/

或等效路径；若项目无Skill或INDEX，可省略或替换为项目的顶层资产和目录，并相应调整参考表格。