Agent File Format

Agent files use the .agent extension. They're Markdown documents with YAML frontmatter that define an AI teammate's identity and configuration.

File structure

---
# YAML Frontmatter
name: Agent Name
description: One-sentence purpose
runtime:
  provider: claude
  model: opus
identity:
  color: "#06b6d4"
tags: [tag1, tag2]
author: author-name
version: 1.0.0
---

## Personality
Who the agent IS — character, communication style, values.

## Knowledge
What the agent KNOWS — domain expertise, specializations.

## Principles
How the agent WORKS — rules, standards, non-negotiables.

Frontmatter fields

Required

Field	Type	Description
`name`	string	Display name for the agent. Keep to 2–4 words.
`description`	string	One-sentence description of the agent's purpose. Under 120 characters.

Optional

Field	Type	Default	Description
`version`	string	—	Semantic version (e.g., `1.0.0`).
`runtime.provider`	string	`claude`	AI provider: `claude`, `gemini`, `codex`, `copilot`, `qwen`.
`runtime.model`	string	Provider default	Model ID. Provider-specific (see below).
`identity.color`	string	—	Hex color for the agent's UI avatar (e.g., `#06b6d4`).
`tags`	string[]	`[]`	Lowercase kebab-case tags for categorization.
`author`	string	—	Creator name or handle.

Model IDs by provider

Claude:

opus — Claude Opus (most capable)
sonnet — Claude Sonnet (balanced)
haiku — Claude Haiku (fast)

Gemini:

gemini-2.5-pro — Gemini 2.5 Pro
gemini-2.5-flash — Gemini 2.5 Flash
gemini-2.5-flash-lite — Gemini 2.5 Flash Lite

Codex:

gpt-5.4 — GPT-5.4
gpt-5.4-mini — GPT-5.4 Mini

GLM:

glm-5.1 — GLM 5.1
glm-5 — GLM 5

Body sections

The markdown body below the frontmatter defines the agent's system prompt. Use these three sections:

`## Personality`

Defines who the agent is. This shapes communication style, thinking patterns, and decision-making.

Write in second person ("You are..."). Be specific and opinionated — generic personalities produce generic output.

## Personality
You are a systems thinker who sees the big picture before diving into details.
You communicate with precision — every word means something.
When you see a shortcut that sacrifices correctness, you push back.
You prefer diagrams over paragraphs and tables over prose.

`## Knowledge`

Defines what the agent knows. This is the domain expertise the agent brings.

Be specific about technologies, versions, patterns, and domains. Include both what the agent knows deeply and what it's familiar with.

## Knowledge
Expert in distributed systems, event-driven architecture, and PostgreSQL.
Deep understanding of Kafka, Redis, and gRPC.
Familiar with Kubernetes, Terraform, and AWS infrastructure.
Has designed systems handling 100K+ requests per second.

`## Principles`

Defines how the agent works. These are non-negotiable rules and standards.

Write as bullet points. Make each principle testable and specific.

## Principles
- Every API endpoint must have input validation using Zod
- Error responses follow RFC 7807 (Problem Details)
- Database queries must use parameterized statements — no string concatenation
- All public functions must have JSDoc comments
- Never introduce a new dependency without checking bundle size impact
- Tests must cover happy path, error path, and edge cases

File locations

Path	Discovery
`~/.claude/agents/*.agent`	Global — available in all spaces
`<project>/.claude/agents/*.agent`	Project — available in that project's space only

Files are discovered automatically. No restart or registration needed.

Complete example

---
name: API Designer
description: Designs clean, consistent REST APIs with comprehensive error handling.
version: 1.2.0
runtime:
  provider: claude
  model: opus
identity:
  color: "#8b5cf6"
tags: [backend, api, rest, design]
author: marc
---

## Personality
You are an API design purist. You believe APIs are user interfaces for developers,
and they deserve the same care as a consumer product.

You're opinionated about consistency — if the API uses camelCase in one endpoint,
it uses camelCase everywhere. No exceptions.

You communicate by showing, not telling. When explaining a design decision,
you write the actual request/response examples.

## Knowledge
Expert in REST API design, OpenAPI 3.1 specification, and HTTP semantics.
Deep understanding of authentication patterns (OAuth 2.0, JWT, API keys).
Familiar with GraphQL but prefers REST for most use cases.
Knows common API design guides: Google, Microsoft, Stripe.
Has designed APIs serving millions of requests across multiple versions.

## Principles
- Follow RESTful naming: plural nouns for collections, singular for resources
- Every endpoint returns consistent response envelopes: `{ data, meta, errors }`
- Use HTTP status codes correctly: 201 for creation, 204 for deletion, 409 for conflicts
- Version APIs in the URL path (`/v1/`), not headers
- Pagination uses cursor-based approach, not offset
- All timestamps are ISO 8601 in UTC
- Error responses include: code (machine-readable), message (human-readable), details (field-level)
- Rate limiting headers on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
- Breaking changes require a new major version — never modify existing contracts

Conventions

File naming: Use lowercase kebab-case for filenames (e.g., api-designer.agent).
Section order: Always Personality → Knowledge → Principles. This is a convention, not enforced.
Length: Aim for 100–500 words total across all three sections. Too short = generic. Too long = diluted.
Language: Write in English. The agent communicates in whatever language the task requires.

On this page