OM Create Agents MD by @openmercato · Skillet

OM Create Agents MD by @openmercato · Skillet

AGENTS.md

Agentic setup — follow references/agentic-setup.md: optional config load, repo-local override contract, untrusted-content boundary, and the knowledge-source slot. Shared communication rules: references/rules.md. This skill uses: config validation.commands and the optional keys agentsMd.template and knowledge.sources; no tracker operations.
Resolve the target and the mode. Validate the target path (inside the repo, ^[A-Za-z0-9._/-]+$). Decide the scope: root (the repo root) or scoped (a package, app, or module directory). Pick the mode — --mode wins:
- no AGENTS.md at the target → create;
- a file whose structure does not match the template (missing required headings, legacy rule headings, descriptive tone) → rewrite;
- a file that matches the structure but whose facts may have drifted → refresh. When a sibling CLAUDE.md or equivalent exists, read it and ask whether it should import the new file, be merged into it, or stay separate.
Resolve the template. First match wins: --template → config agentsMd.template → the conventional file .ai/agents-md-template.md → the built-in default in references/default-template.md. Resolution order, what a repo template may declare, and how its rules layer over the built-in defaults: references/template-contract.md. Say which template you use.
Read the code for the target scope. Gather facts, not impressions — full checklist in references/codebase-discovery.md: the manifest and its real scripts (the scoped validation commands), the directory layout, the entry points and public surfaces, the conventions the existing code actually follows, the generated files, the tests, and the related AGENTS.md files (parent, siblings, knowledge sources). Every rule you will write must trace to something you read here.
Draft. Fill the template from the facts, following the writing rules in references/writing-rules.md (prescriptive tone, one force per boundary section, "When to use" tables, numbered checklists, constraint-framed data models, contract-only code snippets, sizing). Per mode:
- create — build from the facts; where a boundary item cannot be inferred, leave a TODO(team): marker instead of inventing a rule.
- rewrite / refresh — follow references/rewrite-and-refresh.md: reclassify content into the template's sections without losing any rule; in refresh, fix only drifted facts and list every removal for the user. Cross-reference instead of duplicating: a topic already owned by another AGENTS.md (or a knowledge source) gets a one-line pointer, not a copy.
Ask what only the team knows. Show the counts per boundary section and ask the few questions the code cannot answer — typically the Ask First decisions (who approves what), hard Never lines, and any TODO(team): left in step 4. Keep it to the questions that change the file; fold the answers in.
Verify. Run the checklist in references/verification.md: required headings present once and in order, per-section minimums for the file size, every path exists, every validation command resolves to a real script or target, tone and table rules hold, no content lost (rewrite/refresh). Fix and re-check; never hand over a file that fails it.
Show and write. Present the full file (create) or the diff (rewrite/refresh) and write it only after the user confirms. On --dry-run, stop after showing it.
Route it (scoped files). For a package/module file, propose the root AGENTS.md Task Router row that points to it — task keywords an agent would search for, Read first path, key rules — and add it only when the user agrees and the root file stays within its size target. Root file with no Task Router → offer to add one in the shape described in references/default-template.md.
Hand over with references/report-templates.md: what was written for which scope, verification result, questions still open, and the next useful action (commit, or write the next package file). Stop there.