AGENTS.md authoring skill A developer has published a structured skill for authoring and auditing AGENTS.md files, designed to produce short, scoped guidance that changes agent behavior without restating obvious codebase facts. The skill enforces a workflow of suggesting changes before editing, compressing bloated files, and preserving only non-obvious deltas such as project direction, non-negotiables, and architecture seams. It provides templates for repo-level and nested files, and supports modes including audit, draft, rewrite, and split. | name | agents-md | |---|---| | description | How to write, audit and edit AGENTS.md files. | Create and improve AGENTS.md files that are short, scoped, and useful to coding agents. Preserve intent and non-obvious rules; do not summarize the repo. - Suggest changes before editing; discuss first unless the user explicitly asks for direct edits. - Normal repo/brownfield AGENTS.md should aim for ~20 lines or less. - Do not restate what an agent can infer from code, package files, folder names, or a quick search. - Prefer compressed, high-signal half-sentences over full prose, except for greenfield/founder notes and personal/global files. - Nested AGENTS.md files should mostly contain local edge cases, local pointers, or skill/doc routing. - Use RFC2119 caps MUST , SHOULD , REQUIRED sparingly for true non-negotiables. - Do not use XML-ish wrappers by default. - Target path or repo/folder scope. - Desired mode: audit, suggest, draft, rewrite, split, or create missing root guidance. - Project type when known: greenfield, brownfield, nested, or personal/global. - User intent, preferences, or comments about tone/strictness. If the target or project type is unclear, inspect briefly and infer. Ask only when the edit direction or blast radius is ambiguous. - Scope the work. - Identify whether the target is repo-level, nested, greenfield, brownfield, or personal/global. - Stay inside the user-requested scope. Do not wander into unrelated dependencies or archives just because they contain AGENTS.md. - Inspect only what matters. - Read existing AGENTS.md files in scope and nearest parent/child scopes when relevant. - Read README/package/Cargo/build files only enough to find non-obvious commands, boundaries, and hazards. - Use targeted search for repeated patterns instead of copying repo documentation. - Classify useful content. - Keep rules that change agent behaviour. - Drop generic language, obvious stack summaries, motivational filler, duplicated docs, and stale boilerplate. - Preserve founder/product intent when the project is greenfield and the code cannot express it yet. - Suggest before editing. - Present proposed changes as a short list or compact draft. - Explain what will be removed, kept, or added. - Wait for user direction unless the user already asked for direct edits. - Edit if approved or explicitly requested. - Prefer editing existing AGENTS.md over creating duplicates. - For nested files, write only the local delta. - For bloated files, compress first; suggest splitting runbook/spec material into docs only when needed. - Validate the result. - Scoped, short, non-verbose, actionable. - No duplication of obvious codebase facts. - Root and nested files do not repeat each other. Include only non-obvious deltas: - direction not encoded in code - non-negotiables agents might violate - verification exceptions, not obvious package scripts - architecture seams agents are likely to bypass - nested AGENTS / skill / doc routing Template: AGENTS.md -