Write Agents Md

write-agents-md

[English](README.md) | [中文](README.zh-CN.md)

An agent skill for creating or reviewing **AGENTS.md** and related agent instruction files (CLAUDE.md, GEMINI.md) — at global, project, or nested scope.

This is a **guided-writing skill, not an auto-generator**: it gathers evidence read-only, asks only what the evidence cannot answer, and leaves every permission and deletion decision with the user.

How It Works

**Step 1 — Establish scope.** From the request and available context: global (user-level preferences), project (repo root), or nested; create or review; target files; and the language the user wants the files in — which may differ from the conversation language. Only unknowns that change the output or touch permissions become questions; there is no full interview by default. Global files are built from the user's own preferences, not repository scans. Project work reads only the relevant README, manifests, CI, and existing instruction files, and stops once the evidence suffices for the decisions at hand. It does not inventory every omitted implementation detail by default.

**Step 2 — Create or review.**

• Create: the file is built only from verifiable project facts and explicit user preferences. Authorization or completion gaps that affect the intended workflow become questions with options — never silent decisions. Omit unsupported template sections without unnecessary investigation.
• Review: every existing instruction gets a KEEP / DROP / REWRITE verdict with a one-line reason, assessed on five dimensions — provenance, boundary strength, missing permissions, missing completion conditions, and context economics — followed by a complete replacement draft. Separate current facts, user intent, and historical origin; code proves that a feature exists, not its maturity or role. Unknown history stays "unknown"; ambiguous boundaries go back to the user. Accuracy alone does not justify a permanent rule: explain what mistake it prevents or