Custom commands, agents & rules

Three things the agent uses are committed alongside your code in .oxagen/:

• Slash commands — parameterized prompt templates you invoke as /name. Canonical TOML.
• Agents — reusable personas with their own instructions, model, and capability allowlist. Canonical TOML.
• Rules — guardrails the agent is told about and is mechanically blocked from violating. Markdown.

Commands and agents are TOML only. Markdown with frontmatter is not a supported authoring format for them — a .md file in .oxagen/agents/ or .oxagen/commands/ is ignored. If you already have Claude Code, Codex, or Cursor artifacts, convert them with oxagen import artifacts rather than hand-porting.

Commit .oxagen/ and your whole team inherits them.

Custom slash commands

A slash command is a TOML artifact whose prompt field is a prompt template. Invoking /name arg1 arg2 in the REPL expands the template with those arguments and runs it as a turn.

Scaffold one

oxagen command new review        # writes .oxagen/commands/review.toml
oxagen command list              # every command, built-in and custom
oxagen command show review       # print a command's template
oxagen command run review src/app.ts   # expand + run headless (no REPL)

command new refuses to overwrite an existing file. The name must be a kebab-case slug — lowercase letters, digits, and single hyphens.

File format

schema_version = 1
kind = "command"
name = "review"
description = "Review a file for bugs and style"
argument_hint = "<file> [focus]"
prompt = """
Review the file $1 for correctness and clarity.
Focus especially on: $2

Full args for reference: $ARGUMENTS
"""
model = "powerful"

Unknown keys are rejected rather than ignored, so a typo fails loudly instead of silently doing nothing. An artifact that fails to parse is skipped without hiding its valid siblings.

Argument templating

The prompt is expanded at invocation time:

Invoking /review src/app.ts security against the example above expands to:

Review the file src/app.ts for correctness and clarity.
Focus especially on: security

Full args for reference: src/app.ts security

($1 → src/app.ts, $2 → security, $ARGUMENTS → src/app.ts security.)

Custom agents

An agent bundles instructions, a model, a capability allowlist, and loadable skills under a name you can dispatch:

oxagen agent new reviewer        # writes .oxagen/agents/reviewer.toml
oxagen agent list
oxagen agent show reviewer
oxagen --agent reviewer "review the changes on this branch for security issues"

schema_version = 1
kind = "agent"
name = "reviewer"
description = "Security-focused code reviewer"
model = "powerful"
developer_instructions = """
You are a meticulous security reviewer. For any diff you are shown, look for
injection, auth bypass, secret exposure, and unsafe deserialization. Cite exact
file:line locations. Do not comment on style.
"""
tools = ["read_file", "list_dir", "glob", "grep"]
skills = ["debugging"]
unresolved_tools = []

Dispatch it one-shot with oxagen --agent <name> "<prompt>", or reference it from a fleet plan.

Rules

Rules are constraints the agent is told about and hard-blocked from breaking — "never force-push", "never touch production config". Unlike a memory or a prompt instruction, a rule is checked mechanically before a tool call runs.

Rules are Markdown, not TOML — they are guardrail prose plus matchers, not executable artifacts, and were deliberately left out of the TOML cutover.

oxagen rules new no-force-push                       # writes .oxagen/rules/no-force-push.md
oxagen rules list
oxagen rules show no-force-push
oxagen rules check bash "git push --force origin main"   # dry-run against the guards

rules check lets you confirm a guard fires before you rely on it. The tool argument is one of bash | edit | write | read; the subject is the command (for bash) or a path (for edit/write/read).

Rules can also be mined and promoted from recurring lessons the agent has recorded:

oxagen rules candidates          # recurring lessons ripe to become enforced rules
oxagen rules promote <id> --yes  # write the candidate to .oxagen/rules/<id>.md

rules promote never writes without --yes.

Where definitions are discovered

Discovery differs by kind, because commands and agents were cut over to TOML and rules were not.

Commands and agents — TOML only, two locations, project wins:

Skills are directory bundles, so they load from <root>/skills/<name>/skill.toml in the same two locations.

Rules — Markdown, three locations:

Later locations win, so a project definition shadows a same-named user one.

Importing existing artifacts

If you already author agents, skills, or commands for Claude Code, Codex, or Cursor, convert them into Oxagen TOML in place:

oxagen import artifacts --dry-run    # see exactly what would happen
oxagen import artifacts              # convert; conflicts skip by default

Your source files are never modified or deleted, imported artifacts become independent Oxagen-owned TOML with no symlink back to the source, and every run writes a receipt recording provenance, capability mappings, losses, and outcomes.

See Importing agent artifacts for scanned locations, conflict decisions, capability mapping, and receipt format.

Related

• In-REPL slash commands — the built-in /name commands your custom ones sit alongside.
• CLI configuration — the settings.json and .oxagen/ layout.
• The agent engine — how a custom command's prompt flows through the pipeline.