Agent Definition Creator

Agent Definition Creator

Create Margin agent definitions by collecting the missing runtime facts first, selecting the nearest existing definition pattern second, and only then writing definition.toml, schema.json, hooks, and example configs.

Preflight Checklist

Do not start writing files until these questions are answered from docs, --help output, installed CLI behavior, or user input:

• Agent name, binary name, and install source
• Version strategy: latest, exact version, semver range, or non-npm install
• Auth model: single API key, local OAuth file, keychain entry, provider-qualified auth, or no auth
• Direct config surface: the exact values the hooks need in config.input
• Launch command: binary, args, env vars, working directory, and non-interactive flags
• Structured output source: PTY-only, stdout JSONL, event stream, or session files on disk
• Snapshot capability: whether the agent can resume or provide a lightweight snapshot command
• Unified-mode mapping: whether shared model, reasoning_level, and mcp.servers[] can be translated cleanly
• Skills and instruction-file behavior: skill home dir, AGENTS.md, CLAUDE.md, or some other filename
• Toolchain/runtime needs for hooks and install: Node, Python, or other prerequisites
• Semantic validation constraints beyond JSON Schema: provider/model coupling, enums, mutually dependent fields

If any item is unknown, investigate it before writing hooks. Most definition failures come from guessing auth, launch flags, or trajectory sources.

Definition Components

Every definition lives under:

configs/agent-definitions/<agent>/
├── definition.toml
├── schema.json
└── hooks/
    ├── install-check.*
    ├── install-run.*
    ├── run-prepare.*
    ├── translate-unified.*      # optional
    ├── validate-config.*        # optional
    ├── snapshot-prepare.*       # optional
    └── trajectory-collect.*     # optional

Required pieces:

• definition.toml: declare auth, schema, hook paths, toolchains, and optional features
• schema.json: validate the direct-mode [input] shape
• hooks/install-check.*: report whether the agent is already installed
• hooks/install-run.*: install the agent and return install metadata
• hooks/run-prepare.*: write any runtime config files and return the launch exec spec

Optional pieces:

• hooks/translate-unified.*: map shared unified config into direct input
• hooks/validate-config.*: enforce semantic rules that JSON Schema cannot express
• hooks/snapshot-prepare.*: enable POST /v1/run/snapshot
• hooks/trajectory-collect.*: convert the agent's native logs or session data into ATIF

Common optional manifest sections:

• [toolchains.node]: declare managed Node/npm for JS hooks or npm-installed CLIs
• [auth.local_credentials]: support local OAuth or credential file discovery
• [auth.provider_selection] and [[auth.providers]]: support provider-qualified auth selection
• [skills]: tell agent-server where to materialize packaged skills inside run home
• [agents_md]: tell agent-server which instruction filename to write into the project root
• [config.unified]: advertise unified-mode translation and allowed values

Reference Files To Read

Read these repo files before creating or updating a definition:

• docs/cli/add-support-for-a-new-agent/01-overview.md
• agent-server/docs/design.md
• agent-server/docs/unified-config.md
• agent-server/docs/agent-config/*.md
• agent-server/docs/plugins/commands-*.md
• configs/agent-definitions/*/definition.toml
• configs/example-agent-configs/*/config.toml

Workflow

1. Choose the nearest template

Do not start from a blank definition if a repo-owned definition already matches the agent's shape.

• Use the Codex pattern for single-provider agents with a config file and resumable session files
• Use the Claude Code pattern for single-provider agents with JSON settings and snapshot support
• Use the Gemini CLI pattern for agents that emit a structured stdout event stream but do not support snapshots
• Use the Opencode pattern for provider-qualified models plus config-file validation
• Use the Pi pattern for provider-qualified models where reasoning maps directly to a native runtime flag

2. Scaffold the directories

Run:

margin init agent-definition --definition ./configs/agent-definitions/<agent>
margin init agent-config --agent-config ./configs/example-agent-configs/<agent>-default --definition ./configs/agent-definitions/<agent>

If unified mode will be supported, also plan to add configs/example-agent-configs/<agent>-unified.

3. Design direct mode first

Design schema.json around the exact fields the hooks need, not around the shared unified format.

Prefer:

• explicit scalar or enum fields when the agent already has stable CLI flags
• string fields like settings_json, config_jsonc, or config_toml only when the agent truly consumes a raw config file
• a dedicated provider field when auth or model resolution depends on provider selection

Keep the direct input minimal. Every field should be used by install, run, snapshot, or validation hooks.

4. Write definition.toml

Declare:

• kind, name, description
• auth mode
• config schema path
• hook paths
• toolchains if needed
• optional skills, instruction filename, unified mode, snapshot, and trajectory support

Rules:

• declare [toolchains.node] whenever hooks are JS or install uses npm
• only declare [snapshot] if the agent can actually support snapshot collection
• only declare [config.unified] if translation is real, not aspirational
• use [auth.provider_selection] when required env depends on provider