AgentLang specification
Version 0.2 draft, October 2026. An agent is one Markdown file: YAML frontmatter for its settings, the body for its instructions. A host is the service or tool that stores and runs agent files.
1. The file
One agent per file, UTF-8, named <handle>.md. The frontmatter is a YAML mapping between two --- lines at the top of the file; everything after it is the body. Hosts choose the directory they read, for example agents/*.md in a repository.
---
name: PR reviewer
description: Reviews a pull request and posts one verdict comment.
harness: claude
model: claude-opus-5-5
effort: high
skills:
- https://github.com/anthropics/skills/tree/main/skills/webapp-testing
connections: [linear]
capabilities: { browser: true }
---
You review pull requests for correctness, security and tests.
Post exactly one comment that starts with APPROVE or BLOCK.2. Keys
These are all the keys. A host checks every value at save and again when a run starts.
| Key | Purpose | Allowed values | Default |
|---|---|---|---|
| file name (required) | The agent's handle: its stable address. Fixed for life; a new file name is a new agent. | <handle>.md; lowercase, ^[a-z0-9][a-z0-9._-]{0,63}$ | - |
name (required) | What people see. Free to rename. | 1 to 80 characters | - |
description | What the agent does and when to pick it. Read by people and by other agents choosing among agents. | up to 500 characters | empty |
harness (required) | Which coding agent runs it. Fixed for the handle: a different harness is a different agent. | claude (Claude Code), codex (Codex CLI), opencode; a host lists the ones it supports | - |
model | The exact model id as that harness's CLI takes it: bare for Claude Code and Codex, provider/model for OpenCode. | an id the host lists for the harness | the host's default for the harness |
effort | Reasoning effort. | low, medium, high, xhigh, max, auto, or null, within the levels the model lists | the host's default |
skills | Agent Skills folders. The host fetches each once at save and pins it to a commit or sha256. | https URLs: a GitHub tree, a SKILL.md, or a .zip; the host sets a count and size limit | none |
connections | Accounts and MCP servers the agent may use, by the name they have in the host. Resolved to the account of whoever runs the agent. | names; never a URL, header or token | none |
capabilities | Surfaces the host gives the agent beyond its shell. | { browser: bool, computer: bool } | both false |
| body | The instructions, added to the harness's own system prompt. The repository's AGENTS.md or CLAUDE.md still applies. | Markdown, UTF-8, no NUL byte; the host sets a size limit | empty |
3. Rules
- The file is the whole state. Applying a file sets every key. Removing a key resets it to its default.
- Unknown keys are refused. A host rejects a file with a key it does not know, naming the key. A typo never changes what runs.
- No secrets. Connections are names. A file that contains a URL with credentials, a header or a token is refused.
- An unchanged apply is a no-op. Applying the same file twice creates one revision, not two.
- The host holds the lock. Each apply that changes the agent creates an immutable revision recording what it resolved to: model id, CLI release, skill commits or digests. The host returns the revision id (for example as an ETag) so a client can refuse a stale apply.
- Handle and harness are fixed. A file that changes either is refused with a message to use a new file name.
- The file round-trips. A host that stores an agent can return it as this file, and applying that file is a no-op.
- YAML is a restricted subset. No duplicate keys, anchors, aliases or tags. Strings that look like other types are read as written only when quoted.
4. The lock
The file says what the agent is; the host records what it resolved to. On every apply that changes the agent, the host stores an immutable revision with the model id, the harness CLI release, each skill's commit or digest, and the connection names. A run names an agent, or an agent and a revision, and the host runs exactly that, checking the CLI binary's version before it starts.
The file therefore names no CLI release. A team that wants a committed record keeps the revision id beside the file, the way Anthropic's ant apply commits claude-lock.json.
5. Export
A host may export an agent to its own harness's native configuration, so the same agent can run in that CLI elsewhere. Export targets the declared harness only; it never translates a claude agent into Codex or the reverse. It changes nothing cosmetic silently and refuses, in a report listing each key, anything whose meaning would change: instructions, model, effort, tool scope, connection sign-in, skills. It never writes a secret; connections become references to environment variables.
| Key | claude | codex | opencode |
|---|---|---|---|
name, description | subagent frontmatter | agent TOML | agent file (name from file name) |
model | model | model | model (provider/model) |
effort | effort | model_reasoning_effort, if the model lists the level | model variant, if one matches |
skills | fetched into .claude/skills/ | fetched into the skills path | fetched into .opencode/skills/ |
connections | MCP config with an env-var reference | [mcp_servers] with bearer_token_env_var | mcp with a header from env |
capabilities | refused unless the target provides browser or computer as an MCP server | refused likewise | refused likewise |
| body | --append-system-prompt in a launch script (a subagent file would replace the system prompt) | developer_instructions | refused: an agent prompt replaces the base prompt |
6. Left out on purpose
| Field | Why it is not in the file |
|---|---|
CLI release (harness_version) | The revision records it. A file that names a release ages with it; the host's lock already makes runs reproducible. |
| Tool allowlist | Tool names differ per harness and only Claude Code takes a per-tool list. A host-neutral scope may come later as part of capabilities. |
| Network allowlist | Belongs to the host's sandbox, not the agent. |
Triggers (on:) | When an agent runs is a separate resource. An agent is what runs. |
| Inline MCP servers, headers, tokens | Secrets never live in the file. Connect the server in the host, then name it. |
| Hooks, permission modes | Harness-specific, and hooks run with full privileges next to the agent's credentials. |
temperature and sampling options | Coding agent CLIs do not take them. |
Semantic version | Revisions are the version. A file in git already has history. |
7. Proposed for 0.3
Not part of 0.2. A host must refuse these keys until they are, per rule 2.
| Key | Purpose |
|---|---|
result | A JSON Schema the agent's final answer must satisfy before the run reports done. |
plugins | plugin@marketplace entries from marketplaces the host allows, pinned to a commit and sha256 at save. No version ranges. |
max_turns | Stop after this many agent turns. |
budget | Stop at this cost, enforced by the host rather than the CLI. |
Sources
Statements about other tools were checked against their documentation in October 2026.
- Claude Code subagents (frontmatter, including effort)
- Claude Code CLI reference (--append-system-prompt)
- Anthropic ant apply (agent files, claude-lock.json)
- Codex configuration reference (model_reasoning_effort, mcp_servers, developer_instructions)
- Codex subagents (custom agent files)
- OpenCode agents (Markdown agent files)
- OpenCode skills (.opencode/skills)
- OpenCode MCP servers ({env:} in headers)
- Agent Skills specification
- Model Context Protocol specification
- Agent Plugins specification
9. Changes
- 0.2 draft, October 2026. Replaces 0.1 entirely. One Markdown file per agent with a host-held lock and same-harness export.
- 0.1, January 2026, withdrawn. A YAML language (
agent.yaml,prompt.yaml) with a compiler, a lockfile, signed containers, encrypted prompts and adapters for agent frameworks. The compiler, installer and containers were never released.