Agents

An agent is a specialized role in your AI team: a named expert with a clear responsibility, a description that tells the runtime when to delegate to it, and a prompt that defines how it works. Agents do the work; they contain no orchestration logic — that belongs to workflows.

On-disk layout

text

kits/<kit>/agents/<name>/
├── agent.yaml     machine-readable metadata (validated by Zod)
└── prompt.md      the agent's system prompt

<name> is kebab-case and is the agent's identity everywhere: in listings, in workflow step references, and in the generated runtime file name.

agent.yaml reference

yaml

name: backend-architect # required, kebab-case (^[a-z][a-z0-9-]*$)
description: Designs backend architecture and APIs # required, <= 500 chars
version: 1 # required, positive integer
tags: # optional, defaults to []
  - backend
  - architecture
capabilities: # required, agent-only
  - api
  - database
skills: # optional, skills this agent may apply, defaults to []
  - postgres

Rules (enforced at load time — violations name the file, the artifact, and the problem):

Field	Rule
`name`	Required; lowercase letters, digits, hyphens; starts with a letter.
`description`	Required; 1–500 characters. Quality check wants > 20 chars.
`version`	Required; positive integer. Bump it when the prompt changes meaningfully.
`tags`	Optional array of kebab-case labels.
`capabilities`	Required on agents, rejected on other artifact kinds.
`skills`	Optional array; each must resolve to an installed skill.

Objects are strict: an unknown key (for example descripton) is a validation error, so typos never reach a runtime.

prompt.md structure

The body is free Markdown, but kit quality requires these sections:

text

## Role
## Responsibilities
## Inputs
## Outputs
## Constraints
## Review behavior

agentkrew validate additionally enforces a minimum body size (500 chars — stubs fail) and warns/errors on prompt size (warn > 8 KiB, error > 16 KiB). The shared section list lives in packages/core/src/quality/contracts.ts.

Every generated agent also carries a pointer to AGENTKREW.md, so the agent reads the project's conventions from one source instead of duplicating them.

How delegation works

Agents contain a description tuned for routing — the runtime reads it and delegates matching work automatically, or you can name the agent explicitly:

Runtime	Where it lives	How it is invoked
Claude Code	`.claude/agents/<name>.md`	Automatic via the Task tool, or `@tech-lead`
Codex	`.codex/agents/<name>.toml`	Spawned by description, or via a `cmd-` plan
OpenCode	`.opencode/agents/<name>.md`	`mode: subagent`; automatic or `@mention`

Workflows embed the deterministic step plan — including parallel groups — as "spawn one agent per step" instructions, so the whole team runs inside one session. See workflows.

Inspecting agents

bash

agentkrew list agents --installed        # agents in your project
agentkrew info tech-lead --installed     # one agent in detail
agentkrew info tech-lead --installed --json  # machine-readable

Without --installed, list and info read the source kits that ship with a source checkout of AgentKrew (contributor workflow). info shows name, description, version, tags, capabilities, and skills.

Shipped agents

Engineer Kit (15): five shown; the kit ships ten more.

Agent	Responsibility
`tech-lead`	Plans and coordinates engineering work across specialists
`backend-architect`	Designs backend architecture and APIs
`frontend-specialist`	Builds accessible frontend UI with React composition and Next.js App Router
`code-reviewer`	Reviews correctness, maintainability, and test coverage
`test-automator`	Designs and implements automated test coverage

The other ten cover data, security, debugging, releases, TypeScript, API contracts, accessibility, performance, DevOps, and documentation. agentkrew list agents prints the full roster with each responsibility.

Marketing Kit (7): growth-strategist, brand-voice, seo-specialist, and 4 more (content, competitive analysis, market research, copy).

Lists are kits' current state; agentkrew list agents is the live source of truth.

Creating a custom agent

Two supported paths:

Source checkout (contributor): add kits/<kit>/agents/<name>/{agent.yaml,prompt.md} and run agentkrew validate --kit <kit>.
Installed project: drop a runtime-native file such as .claude/agents/<name>.md. agentkrew update only rewrites files the renderer produced, so yours coexists and survives updates; check the installation with agentkrew validate --installed.

The full walkthrough — including how updates treat each location — is in customization.