SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsgenerate-agent-entry

generate-agent-entry

Office & productivity

View repository

Updated 10-16 06:50

About this skill

Skill: Generate agent entry

Purpose

Write or modify the following in the repository root according to the "Output Contract" section belowAGENTS.md, so that when an agent encounters the project, it has a clearproject identity、authoritative sourcesandbehavioral expectations, and behaves consistently and predictably. The output contract is embedded in this SKILL.md, so a single load provides the complete specification and steps.

Core Objective

Primary objective: Generate a compliant AGENTS.md file that establishes project identity, authoritative sources, and behavioral expectations for AI agents.

Success criteria(all requirements must be met):

  1. ✅ AGENTS.md exists: The file is written to the repository root and committed to version control
  2. ✅ Three core elements are present: Project identity, authoritative sources, and behavioral expectations sections are present
  3. ✅ Seven sections complete: Opening, project identity, authoritative sources, behavior, discovery/loading summary, language/communication, reference table
  4. ✅ Executable behavior: Behavioral expectations use "must", "should", or "must not" with actionable items
  5. ✅ Reference table complete: Includes spec source, entry Raw URL (if applicable), defining specification, usage/installation, and entry index
  6. ✅ Contract compliance: The output follows the embedded output contract structure and content requirements

AcceptanceTest: Can an AI agent read this AGENTS.md and understand what the project is, where the authoritative sources are, and how to behave when using the project?

Scope boundaries (Scope boundaries)

This skill is responsible for：

  • Writing a new AGENTS.md from scratch
  • Modifying an existing AGENTS.md to ensure compliance
  • Reviewing AGENTS.md against the output contract
  • Generating AGENTS.md according to the embedded contract specification

This skill is not responsible for：

  • Writing a README (use "generate-standard-readme")
  • Bootstrapping the complete project docs/ structure (handled by the AgentFabric runtime or a human according to docs/ARTIFACT_NORMS.md )
  • Refining skill design (use "refine skill design")
  • Writing other document types (out of scope)

Handoff point: After AGENTS.md is written, committed, and passes self-check, hand off to the project documentation workflow or the next documentation task.

Use cases (Use cases)

  • New project: Add an Agent entry for a repository without AGENTS.md; draft an initial version according to the recommended structure and sections of the output contract.
  • Modify an existing entry: Review 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 from elsewhere: Other projects can use this skill's output contract to generate an AGENTS.md with identity, authority, and behavior, then replace their project's asset types and paths.
  • Compliance check: Review an existing AGENTS.md against the contract (§3 sections, §4 content, §6 reference table) and output revision suggestions.

Behavior (Behavior)

  1. Read the contract first: Before execution, read the "Output Contract" section of this file and use it as the sole source of truth; do not invent sections or delete recommended elements.
  2. Collect Inputs: Obtain from the user or context: one-line project positioning, top-level asset types and directories (e.g., skills/ and specification paths), whether a raw URL is provided, and the primary description language. If information is missing, ask according to the skill's interaction policy.
  3. Generate by Section: Output or modify the AGENTS.md order in Contract §3: Opening → Project Identity → Authoritative Sources → Behavioral Expectations → Discovery and Loading (Summary) → Language and Communication → Reference Table. Section headings may be adjusted, but keep the order: Identity → Authority → Behavior → Operational Summary → Language → References.
  4. Executable Behavior: Use "must", "should", "must not" (or equivalents) so that every expectation is actionable; each item can reference a specification or document. Do not paste complete specifications/documents into AGENTS.md; only index and summarize.
  5. Complete Reference Table: Include at least: specification sources, the original URL of this entry (if applicable), defining specifications, usage and installation, and entry index; use relative paths or resolvable URLs.
  6. Pre-Submission Self-Check: After creating or modifying, review and run the skill's self-check; submit only after all pass. If the user only requests a compliance review, output a revision list instead of editing the file.

Input & Output

Input

  • One-line positioning: What the project is (e.g., "agent-first, governance-ready capability inventory").
  • Top-level assets and directories: Asset type (e.g., skills), directories, specification paths; if the type does not exist, say "none" or omit.
  • Optional: AGENTS.md raw URL, existing AGENTS.md or README excerpt (for revision), primary description language (e.g., English).

Output

  • Creation: A complete AGENTS.md that satisfies the output contract (or diff/revised full text).
  • Review: A compliance checklist and revision suggestions for each Contract §3–§6 clause (missing sections, reference table gaps, behavioral wording); do not force a rewrite of the file.

Constraints

Hard Boundaries

  • Do not depart from the contract: Do not add sections not required by the contract as "required", or delete any of the seven recommended section types without justification.
  • Do not paste complete specifications: Do not paste complete specification content into AGENTS.md; only summarize and link.
  • No vague behavior: Do not use "if possible", "as appropriate", etc.; use "must", "should", "must not" (or equivalents).
  • Do not omit the reference table: The table must include specification sources, definition/usage/installation specifications, and entry index; if the project has no index, say "N/A" or omit that row.

Skill Boundaries (avoid overlap)

Do not do these (other skills can handle them)：

  • Write README files: Create or update README.md → use generate-standard-readme
  • Bootstrap complete project documentation: Set up the complete document structure → by AgentFabric runtime or manually according to docs/ARTIFACT_NORMS.md spin up
  • Refine skill design: Review or refactor the SKILL.md file → use refine-skill-design
  • Write other document types: API documentation, user guides, tutorials → out of scope

When to stop and hand off：

  • The user says "AGENTS.md looks good" or "approved" → the skill is complete, hand off to the next documentation task
  • The user asks "Can you also write a README?" → hand off to "Generate standard README"
  • The user asks "Can you set up all project documentation?" → hand off to AgentFabric runtime (according to docs/ARTIFACT_NORMS.md execute)
  • The user asks "Can you review this skill?" → hand off to "Refine skill design"

Self-Check

Core success criteria (all criteria must be met)

  • AGENTS.md exists: a file written to the repository root and committed to version control
  • Three core elements exist: project identity, authoritative sources, and behavioral expectations sections exist
  • Seven sections complete: opening, project identity, authoritative sources, behavior, discovery/loading summary, language/communication, and reference table
  • Executable behavior: behavioral expectations use "must", "should", or "must not" for actionable items
  • Reference table complete: includes canonical source, entry original URL (if applicable), definition specification, usage/installation, and entry index
  • Contract compliance: output follows the embedded output contract structure and content requirements

Process quality check

  • Contract reading: Did I read the output contract section before executing?
  • Collect inputs: Did I collect all required inputs (location, asset type, directory) or ask when missing?
  • Section order: Did I generate AGENTS.md in the contract §3 order (identity→authority→behavior→operations→language→reference)?
  • No specification duplication: Did I avoid pasting complete specification/documentation content and only index and summarize?
  • Executable language: Did I use "must"/"should"/"must not" to express behavioral expectations?
  • Reference table: Did I include all required elements (canonical source, original URL (if applicable), definition specification, usage/installation, index)?

Acceptance test

Can an AI agent read this AGENTS.md and understand what the project is, where the authoritative sources are, and how to behave when using the project?

If no: AGENTS.md is incomplete. Return to collect input or revise sections.

If yes: AGENTS.md is complete. Proceed to commit and hand off.

Example (Example)

Example 1: New project (minimal information)

Input: Project: my-cli. One-liner: a CLI for local batch file renaming. Assets: no skill, only README and source code. Want an agent entry point; primary language English.

Expected: Generate AGENTS.md with content including: Opening (this file is the agent entry point and contract), Project identity (one line + asset table; can be simplified to "docs/source" etc.), Authoritative sources (definitions and directory from README or docs/), Behavioral expectations (a few "must" items), Discovery and loading (if INDEX or equivalent exists, summarize it; otherwise how the agent should understand the project), Language and communication (English), Reference table (canonical sources, this entry's original (if applicable), doc and entry links). Do not invent canonical sources/paths that do not exist.

Example 2: Edge case — incomplete AGENTS.md

Input: The existing AGENTS.md only has "this project is XX" and "read INDEX", with no authoritative sources, no behavior, and no reference table. The project has docs/, README, and no skill. Complete it according to the output contract.

Expected: Keep the existing "project identity"; add authoritative sources (where definitions and directory exist), behavioral expectations (at least 2-3 actionable items, e.g. "follow the README and docs", "when listing capabilities, read the index and then enumerate"), discovery and loading (summary), language and communication, reference table. Do not delete correct user wording; if the project has no INDEX, the reference table can say "N/A" or list README/docs. Output the revised full text or a diff and state which sections were added.

Output Contract: AGENTS.md authoring standard

The following is the standard this skill uses when producing AGENTS.md; it is embedded in this SKILL.md. Projects in the form of an "agent-first, governance-ready capability inventory (Spec)" can use it; this repository's AGENTS.md follows immediately after.

1. Purpose and role

  • AGENTS.md is the AI agent's single entry point and contractfor interacting with the project; it is usually located at the repo root.
  • Purpose: define when an agent comes into contact with the projectproject identity、authoritative sourcesandbehavioral expectations, so that the agent behaves consistently and predictably when referencing the repository or when referencing the repository.
  • Audience: agents that can read files (e.g. IDE agents, CLI agents); it can also be used by consumer repositories that reference it via a raw URL.

2. Primary goals

The primary goal of AGENTS.md is not to "teach the Agent how to use the skill", but to establishentry and behavior. This means three things:

Goal Description
Project identity One sentence stating what the project is; list the top-level asset types (e.g. skills), their directories, and defining specifications.
Authoritative sources Where "definitions" and "directory/list" are located; agents treat these as facts, not verbal or scattered documentation.
Behavioral expectations What the agent, when referencing the project,must or must notdo (e.g. follow the spec, self-check before submitting, read the index and then enumerate when listing capabilities).

3. Recommended structure and sections

Both agents and humans organize in the following order:

Order Section Content
1 Opening One sentence: this file is the Agent's entry and contract; purpose (identity + authority + behavior).
2 Project Identity One-line positioning + asset type/directory/spec table + directory and inventory (if any).
3 Authoritative Sources Where definitions, directories/lists, and usage contracts are located; provide pointers only, no detailed explanations.
4 Behavioral Expectations Numbered expectations that the agent must follow; each may reference a spec or document.
5 Discovery and Loading (Summary) Asset root, how to discover, how to inject; details in AGENTS.md §4 or equivalent; avoid duplication in AGENTS.md.
6 Language and Communication Primary description language and terminology; keep consistent with specs/skills or equivalent.
7 References Table: spec sources, original URL of this entry (if applicable), defining specs, usage and installation, entry index.

Section titles and levels may follow project style, but keep the order: identity → authority → behavior → operational summary → language → references.

4. Content Requirements

  • Executable expectations: use "must", "should", "must not" (or equivalents) so that the agent can parse and follow them.
  • Do not duplicate specs and documents: AGENTS.md indexes and summarizes; point to "specs/" or "docs/" for full definitions and installation.
  • Stable references: use relative paths or resolvable URLs for specs and indexes in the repository; if the project can be referenced via its original URL, provide the canonical original URL of AGENTS.md in the reference table.

5. Format and Style

  • Headings: short and parseable; optional English subtitle (e.g., "Agent Entry").
  • Length: aim for about one page (e.g., 60-80 lines) so that the agent can load and parse it in one pass.
  • Language: match the project's primary asset language.
  • Tables: use Markdown tables for project identity, authoritative sources, and references for structured parsing.

6. Reference Table

  • End with areference table, listing at least: spec sources, the original URL of this entry (if original referencing is supported), defining specs (e.g., specs/skills), entry index (e.g., skills/INDEX.md). For usage, see AGENTS.md §4. This table allows agents and tools to jump to authoritative documents without crawling the repository.

7. Relationship with Other Specs

  • Usage: the runtime behavior for discovery, injection, and self-check is in AGENTS.md §4; AGENTS.md is the single entry and contract.
  • Language: the description and communication expectations of AGENTS.md should be consistent with the project's primary asset language.

8. Adapting to Other Projects

Other projects adopting this contract may: keep the three elements (identity, authority, behavior) and the recommended section order; replace "Project Identity" with one-line positioning and an asset table; replace the paths and spec names in "Authoritative Sources", "Behavior", and "Discovery and Loading" with "specs/" or equivalents; if the project has no skills or index, omit or replace them with the project's top-level assets and directories, and adjust the reference table accordingly.