Write an agent file
Four examples, from the smallest file a host accepts to one that uses connections. The full rules are in the spec.
The smallest file
A file name, a name, a harness and instructions. Everything else takes the host's defaults. Save it as release-notes.md; the handle is release-notes.
---
name: Release notes writer
harness: claude
---
Read the merged pull requests since the last tag and write release notes
grouped by Features, Fixes and Other. Link each pull request.Choosing the coding agent and model
harness picks the CLI and model must be an id that CLI takes. The host checks both against the models it lists for that harness, and records the exact CLI release when you save.
---
name: Flaky test fixer
description: Finds why a test is flaky and opens a fix.
harness: codex
model: gpt-5.5
effort: high
---
Run the named test 20 times. If it fails, find the cause, fix it,
and run it 20 more times before you open a pull request.Using connections
Connect Linear, Slack or an MCP server in the host first, then name it. Whoever runs the agent runs it with their own connected accounts, so the file carries no secret and is safe to commit.
---
name: Incident summarizer
description: Summarizes an incident from Linear and Slack.
harness: claude
connections: [linear, slack]
capabilities: { browser: true }
---
Read the Linear issue you are given and the Slack thread it links.
Write a timeline, the cause and the follow-ups as one comment on the issue.What a host refuses
A host refuses the whole file and names each problem, rather than running something different from what the file says.
---
name: Reviewer
harness: claude
modle: claude-opus-5-5 # refused: unknown key "modle"
connections:
- https://mcp.example.com # refused: a connection is a name, not a URL
result: { type: object } # refused in 0.2: proposed for 0.3
---Changing an agent
Edit the file and apply it again. The file is the whole state: removing a key resets it to its default. Applying an unchanged file does nothing. Renaming the file or changing harness makes a new agent, so a host refuses it on the old handle.