Agent Bundle specification

An Agent Bundle is a portable .zip package that defines an agent. It has one entry point, AGENTS.md, and an optional .agent/ directory that holds everything the agent loads at runtime. That is the whole standard.

Directory layout

AGENTS.md

Every bundle must contain an AGENTS.md at its root. It is the entry point: YAML frontmatter carries the agent's metadata and the Markdown body becomes the agent's system prompt. A bundle without it is rejected on upload.

---
name: support-triage
version: 1.0.0
description: Triage and route incoming support tickets
author: Your Name
---

# Agent Instructions

You are a support triage agent. Classify each ticket by severity
and route it to the right team using the tools available to you.

.agent/skills/<name>/SKILL.md

A skill is a directory under .agent/skills/ containing a SKILL.md. The directory name is the skill name. Skills load on demand through the built-in skill tool, so the agent only pulls a skill's full text into context when a task matches it.

---
name: triage
description: Triage incoming support tickets by severity and route them
---

# Support Ticket Triage

Classify each ticket P0-P3, tag the affected component, and
escalate P0/P1 to on-call immediately.

• Frontmatter requires name and description. name is lowercase alphanumeric with hyphens and should match the directory name.
• The description is shown to the model in the skill directory so it can decide when to load the skill.
• Companion files (references, examples, scripts) can live alongside SKILL.md in the skill directory; they are staged to the workspace and read with the workspace file tools.

.agent/agents/<name>/AGENT.md

A sub-agent is a directory under .agent/agents/ containing an AGENT.md. The directory name is the sub-agent name. The parent spawns it with the built-in task tool. The Markdown body is the sub-agent's system prompt.

---
description: Look up a customer's billing status and recent invoices
tools:
  - workspace_read_file
  - stripe_get_customer
model: gemini-2.5-flash
---

You are a billing lookup specialist. Given a customer id, return
their current plan, balance, and the last three invoices.

• description (required) tells the parent model when to delegate to this sub-agent.
• tools (optional) is an allowlist; omit it to inherit every tool the parent has.
• model (optional) overrides the model; omit it to inherit the parent's.

Packaging rules

• The archive must contain AGENTS.md at the root; everything else is optional.
• Skills and sub-agents live under .agent/skills/ and .agent/agents/.
• Directory and skill names are lowercase alphanumeric with single hyphens: no leading, trailing, or consecutive hyphens.
• Paths use forward slashes and stay inside the bundle: no absolute paths, no .. segments, no backslashes.
• Any file type may be bundled as a companion; only .md files are parsed as skills or sub-agents.

Skills and sub-agents are only loaded from the .agent/ directory. Files placed in root-level skills/ or agents/ directories are ignored.