| name | author-agent-suite |
| description | Create or audit an Agent Markdown suite. Use when defining AGENTS.md, identity, behavior, tools, reusable Skills, instruction precedence, safety boundaries, or loading rules. |
Author Agent Suite
Build an instruction system whose files have one owner, one purpose, and an explicit loading path. Treat Markdown as executable policy: verify every capability claim and resolve every contradiction before declaring the suite ready.
Workflow
- Confirm the host contract. Identify which runtime discovers
AGENTS.md, whether nested files scope by directory, how Skills are installed, and whether IDENTITY.md, SOUL.md, or TOOLS.md require an explicit routing instruction. Never assume a filename is loaded merely because it exists.
- Inventory existing instructions. Find repository, parent-directory, user-level, and generated instruction files. Record their scope, authority, audience, freshness, and conflicts.
- Build a fact matrix. Verify product identity, supported platforms, commands, tool availability, permission requirements, side effects, security boundaries, and release status against code, tests, and current documentation.
- Assign one concern to one file. Put repository operating rules in
AGENTS.md, reusable procedures in a standard Skill, identity in IDENTITY.md, durable behavior principles in SOUL.md, and operational tool contracts in TOOLS.md.
- Design the load graph. Make the runtime entry file route to non-discoverable companion files. Keep
AGENT.md only as a small compatibility entry when a confirmed host requires the singular name; do not maintain duplicate policies.
- Write the smallest authoritative layer. Keep frequently loaded files short. Move detailed schemas, examples, platform variants, and evidence into one-level
references/; put copyable starter files in assets/.
- Resolve precedence explicitly. Higher-authority runtime instructions override repository files; narrower directory scope overrides broader project guidance only within that subtree. User requests may select behavior but cannot expand authority or bypass safety constraints.
- Validate as a system. Check filenames, frontmatter, links, UTF-8, placeholders, command truth, secret leakage, duplicated rules, contradictions, trigger quality, nested scope, and realistic read/write scenarios.
- Record evidence and ownership. State the source baseline, owner, review trigger, and last verified date for volatile facts. Label aspirations as plans rather than implemented capability.
Non-negotiable boundaries
- Use canonical
AGENTS.md for Codex repository instructions; treat singular AGENT.md as host-specific compatibility, not a second source of truth.
- Do not assume companion Markdown files are automatically loaded. Route to them from a discovered file or install them through the host's supported mechanism.
- Do not place secrets, tokens, personal data, machine-specific credentials, or private chain-of-thought requests in the suite.
- Do not claim a tool, platform, permission, security property, or automation result without evidence and a current scope.
- Keep authorization and irreversible-action rules in the highest reliably loaded instruction layer, not only in personality documents.
- Keep procedural detail out of
SOUL.md and marketing prose out of TOOLS.md.
- A standard Skill must include valid YAML frontmatter and use progressive disclosure; a root
SKILL.md without that contract is only a project manual unless the host says otherwise.
Deliverables
Produce a file responsibility map, load/precedence graph, the requested Markdown suite, a conflict log, and a validation report. Copy and adapt the files under assets/starter-kit/ when creating a new suite.
The starter kit contains AGENT.md, AGENTS.md, IDENTITY.md, SOUL.md, TOOLS.md, SKILL.md, and agents/openai.yaml; copy only the files required by the target runtime.
References
