29 lines
2.1 KiB
Markdown
29 lines
2.1 KiB
Markdown
---
|
|
name: generate-agents-md
|
|
description: Create, revise, or audit AGENTS.md repository instructions when explicitly requested.
|
|
---
|
|
|
|
# Generate AGENTS.md
|
|
|
|
Produce a concise guide that changes the agent's decisions: verified commands with working directories, non-obvious constraints, and links to context needed for specific tasks. Use the project's language and structure; no required headings or line count.
|
|
|
|
## Approach
|
|
|
|
Inspect the existing guide and the repository evidence relevant to the request. A small edit needs a small investigation; a new guide may need manifests, CI, and contributor docs. Preserve useful user rules. Remove stale or redundant guidance when the evidence supports it; surface unresolved conflicts rather than inventing facts or permissions.
|
|
|
|
Keep shared rules at the root. Add a child guide only when that area needs distinct instructions. Link long procedures with their read conditions. Do not copy a repository map, formatter rules, or generic engineering advice into always-loaded context.
|
|
|
|
For a new guide, scope changes, command ambiguity, or a substantial audit, consult [the reference](references/agents-md-reference.md). It covers evidence, Codex loading, optional content, and validation limits. Ordinary wording fixes do not need the full reference.
|
|
|
|
## Checks and delivery
|
|
|
|
Review whether each retained instruction is accurate, scoped, useful, and consistent with the user's authorization. Check only what the change requires. For mechanical checks, run the bundled helper without executing the guide's commands:
|
|
|
|
```bash
|
|
python scripts/validate_agents_md.py --repo /path/to/repo --file /path/to/repo/AGENTS.md
|
|
```
|
|
|
|
Resolve the script relative to this skill directory. Use `--local` for a child guide whose inline paths and commands are local; use `--cwd` when they refer to another directory. Markdown links are always relative to the guide. Warnings require judgment; use `--warnings-as-errors` only for an explicitly strict check.
|
|
|
|
Report changed files, relevant evidence, checks performed, and any remaining uncertainty. Passing the helper does not prove command execution, instruction loading, or improved agent performance.
|