oxo-flow agent-docs#
Scaffold agent-facing docs into a project so an AI agent can operate it
safely: an editable AGENTS.md entry file, a one-line CLAUDE.md import,
and the full canonical SKILL.md operating manual.
Usage#
Works in any project directory — new or existing. oxo-flow init --agent
runs the same scaffold while creating a project.
Options#
| Option | Short | Default | Description |
|---|---|---|---|
--dir |
-d |
. |
Target directory |
--force |
— | off | Overwrite existing agent docs (user edits are lost) |
--verbose |
-v |
— | Enable verbose (debug-level) logging |
--quiet |
— | — | Suppress informational output (per-file scaffold lines are omitted; errors and warnings are unaffected) |
Generated files#
| File | Purpose |
|---|---|
AGENTS.md |
The entry point an agent reads first. Contains the non-negotiable data-safety summary, a relative link to SKILL.md, and an editable "Project notes" section. This file belongs to the project owner — it is never overwritten without --force. |
CLAUDE.md |
One line: @AGENTS.md. Claude Code imports the entry file, so user edits to AGENTS.md flow through automatically. |
SKILL.md |
The full AI Agent Skill operating manual, embedded in the CLI binary and written verbatim — seven-stage analysis loop, static gates, execution, monitoring, QC, delivery, and the binding data-safety contract. |
AGENTS.md is the open convention read by most agent tools (Codex, Cursor,
Jules, Claude Code); other tools can be pointed at it or at SKILL.md
directly.
Examples#
Add agent docs to an existing project#
Refresh after an oxo-flow upgrade#
The generated files carry the version that wrote them; after upgrading
oxo-flow, refresh the skeleton (this overwrites your AGENTS.md edits —
copy them out first, or keep project specifics in the "Project notes"
section and merge them back):
Create a new project with agent docs#
How agents use the files#
AGENTS.mdgives the entry context: safety rules inline, project notes, and the pointer toSKILL.md.SKILL.mdis the canonical manual: read it in full once per task, follow its links on demand.- The data-safety contract (inputs read-only, snapshot-before-mutate,
scratch confined to
.oxo-flow/agent/, operation journal) binds every command the agent runs — see Agent Safety & Workspace Discipline.
Notes#
SKILL.mdis embedded at build time from the docs canonical (docs/guide/src/SKILL.md);make skill-drift(amake cigate) fails when the two diverge.make sync-skillrefreshes the embedded copy.- Existing files are kept unless
--forceis passed;oxo-flow init --agentnever overwrites agent docs, even with--force.