Agent Skills

What this is

AI coding agents (Claude Code, Cursor, and the like) will happily run python train.py for you — as a bare command, with no lineage captured. roar init agents installs a small amount of guidance that teaches an agent to reach for roar run instead, and to avoid the handful of things that make a lineage fail to reproduce.

It writes plain Markdown, not a plugin or a hook. Nothing about roar's behavior changes; the guidance just puts the right instructions where agents already look for them.

roar init agents            # install both targets (below)

What it installs

Two targets, either or both:

roar init agents --skill      # only the user-global Claude skill
roar init agents --project    # only this project's AGENTS.md

The AGENTS.md content is written inside managed markers:

<!-- roar:begin (managed by `roar init agents` — edits inside this block will be overwritten) -->
<!-- roar version: 0.3.7 -->
## roar (provenance tracker)
...
<!-- roar:end -->

Everything outside the markers is yours and is left untouched. Everything inside is owned by roar and is replaced on the next roar init agents. The skill file is treated as fully managed — pass --force to overwrite it if you've hand-edited it.

What the guidance says

The installed text is short and practical. It tells the agent to:

• Prefer roar run <cmd> over a bare command, and not to modify your code to do so — capture is transparent.
• Keep a clean git tree, because roar run refuses to execute with uncommitted or untracked files (there is no --dirty bypass).
• Avoid staging real inputs or wanted outputs under /tmp, which is filtered by default (see Filtering).
• Watch for unsourced inputs — the most common reason a lineage doesn't reproduce elsewhere — and inspect lineage with roar show, roar dag, and roar log.
• Treat roar --help as the source of truth for current command behavior.

Keeping it current

The managed blocks are stamped with the roar version that wrote them. That makes staleness detectable, which matters in CI or a pre-commit hook:

roar init agents --check      # exit nonzero if the installed guidance is missing or out of date
roar init agents --dry-run    # print what would change, write nothing

Use --check to fail a build when someone upgrades roar but forgets to refresh the guidance; use --dry-run to preview a diff before committing it.

This is guidance, not enforcement. roar init agents makes the right thing more likely by putting instructions in front of the agent — it does not force any command to run under roar. If you need a hard guarantee that a script only runs when traced, add from roar import require at the top of the script, which aborts execution when it isn't launched under roar run.