AgentLangv0.2 draft

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.

KeyPurposeAllowed valuesDefault
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-
descriptionWhat the agent does and when to pick it. Read by people and by other agents choosing among agents.up to 500 charactersempty
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-
modelThe 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 harnessthe host's default for the harness
effortReasoning effort.low, medium, high, xhigh, max, auto, or null, within the levels the model liststhe host's default
skillsAgent 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 limitnone
connectionsAccounts 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 tokennone
capabilitiesSurfaces the host gives the agent beyond its shell.{ browser: bool, computer: bool }both false
bodyThe 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 limitempty

3. Rules

  1. The file is the whole state. Applying a file sets every key. Removing a key resets it to its default.
  2. 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.
  3. No secrets. Connections are names. A file that contains a URL with credentials, a header or a token is refused.
  4. An unchanged apply is a no-op. Applying the same file twice creates one revision, not two.
  5. 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.
  6. Handle and harness are fixed. A file that changes either is refused with a message to use a new file name.
  7. The file round-trips. A host that stores an agent can return it as this file, and applying that file is a no-op.
  8. 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.

Keyclaudecodexopencode
name, descriptionsubagent frontmatteragent TOMLagent file (name from file name)
modelmodelmodelmodel (provider/model)
efforteffortmodel_reasoning_effort, if the model lists the levelmodel variant, if one matches
skillsfetched into .claude/skills/fetched into the skills pathfetched into .opencode/skills/
connectionsMCP config with an env-var reference[mcp_servers] with bearer_token_env_varmcp with a header from env
capabilitiesrefused unless the target provides browser or computer as an MCP serverrefused likewiserefused likewise
body--append-system-prompt in a launch script (a subagent file would replace the system prompt)developer_instructionsrefused: an agent prompt replaces the base prompt

6. Left out on purpose

FieldWhy 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 allowlistTool 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 allowlistBelongs 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, tokensSecrets never live in the file. Connect the server in the host, then name it.
Hooks, permission modesHarness-specific, and hooks run with full privileges next to the agent's credentials.
temperature and sampling optionsCoding agent CLIs do not take them.
Semantic versionRevisions 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.

KeyPurpose
resultA JSON Schema the agent's final answer must satisfy before the run reports done.
pluginsplugin@marketplace entries from marketplaces the host allows, pinned to a commit and sha256 at save. No version ranges.
max_turnsStop after this many agent turns.
budgetStop at this cost, enforced by the host rather than the CLI.

Sources

Statements about other tools were checked against their documentation in October 2026.

9. Changes