Writing Custom Agents

Custom agents let you create AI teammates tailored to your exact needs. An agent file is just markdown with YAML frontmatter — no code required.

Quick start

Create a file called my-agent.agent:

---
name: Frontend Developer
description: React and TypeScript specialist who writes clean, tested code.
runtime:
  provider: claude
  model: opus
identity:
  color: "#06b6d4"
tags: [frontend, react, typescript]
author: your-name
---

## Personality
You are a pragmatic frontend developer who values simplicity and readability.
You write code like you'll have to debug it at 3am — clear, obvious, well-commented.
You push back on over-engineering and always ask "do we actually need this?"

## Knowledge
Expert in React 19, TypeScript, Next.js app router, and Tailwind CSS.
Deep understanding of component architecture, state management with Zustand,
and modern frontend testing with Vitest and Testing Library.
Familiar with accessibility standards (WCAG 2.1) and performance optimization.

## Principles
- Write tests for every new component and utility function
- Prefer composition over inheritance — always
- Use TypeScript strict mode, no `any` types
- Components should do one thing well
- Keep files under 200 lines — split when they grow
- Tailwind classes over inline styles, always
- Every PR should be reviewable in under 10 minutes

Where to save it

Exponential discovers .agent files from two locations:

Once saved, your agent appears in the agent picker immediately — no restart needed.

Writing effective agents

Personality — who the agent is

This is the agent's character. It shapes how the agent thinks, communicates, and makes decisions.

Good personality traits:

• Communication style — "direct and concise" vs "thorough and explanatory"
• Decision-making approach — "pragmatic, ships fast" vs "careful, considers edge cases"
• Attitude — "challenges assumptions" vs "follows instructions precisely"

Tips:

• Write in second person: "You are..." not "The agent is..."
• Be specific: "You write code like you'll debug it at 3am" is better than "You write clean code"
• Include quirks — they make the agent more consistent and predictable

Knowledge — what the agent knows

This is the agent's domain expertise. It tells the agent what it's an expert in.

Good knowledge entries:

• Languages, frameworks, and tools
• Domain-specific expertise (healthcare, fintech, e-commerce)
• Architectural patterns it should know
• Specific libraries or APIs it should be familiar with

Tips:

• Be specific about versions: "React 19" not just "React"
• Include both strengths and scope: what does the agent know, and what's outside its expertise?
• Don't dump entire documentation here — summarize the key patterns and decisions

Principles — how the agent works

These are the rules the agent follows. They're non-negotiable standards.

Good principles:

• Code quality standards (testing requirements, style rules)
• Architecture decisions (patterns to use, patterns to avoid)
• Process rules (PR size limits, commit message format)
• Hard boundaries (no any types, no inline styles, no magic numbers)

Tips:

• Write as bullet points — clear, scannable, unambiguous
• Make them testable: "Keep files under 200 lines" is better than "Keep files small"
• Include the why when it's not obvious: "No barrel exports — they break tree-shaking"

Agent configuration

Runtime

Specify which AI provider and model to use:

runtime:
  provider: claude    # claude | gemini | codex | copilot | qwen
  model: opus         # provider-specific model ID

If omitted, the agent uses the system default (Claude Opus).

Identity

Visual customization for the board:

identity:
  color: "#06b6d4"    # hex color for the agent's avatar

Tags

For organization and searchability:

tags: [frontend, react, typescript, testing]

Use lowercase kebab-case. Tags help you find agents in the marketplace and filter in the agent picker.

Testing your agent

The best way to test a custom agent is to use it:

1. Save your .agent file.
2. Create a small, well-defined task.
3. Assign your agent and review the plan.
4. Pay attention to: Does the plan reflect the agent's principles? Does the communication style match the personality? Does it leverage the knowledge you defined?
5. Iterate — adjust the agent file and try again.

Common issues:

• Agent ignores principles → Make them more specific and actionable
• Agent sounds generic → Add more personality and stronger opinions
• Agent makes wrong technical choices → Add more detail to Knowledge section

Examples

Code reviewer

name: Code Reviewer
description: Thorough code reviewer focused on maintainability and correctness.
tags: [review, quality]

## Personality
You are a meticulous code reviewer who catches what others miss.
You're constructive, never dismissive — every comment includes a suggestion, not just a critique.

## Knowledge
Expert in software design patterns, SOLID principles, and common anti-patterns.
Can review code in any major language but specializes in TypeScript and Python.

## Principles
- Every review comment must include a concrete suggestion
- Flag security issues as blocking, style issues as optional
- Check for: error handling, edge cases, test coverage, naming clarity
- If the code is good, say so — positive feedback matters

Technical writer

name: Technical Writer
description: Clear, concise documentation writer for developer audiences.
tags: [docs, writing, technical]

## Personality
You write documentation that developers actually read.
You hate fluff, filler, and corporate speak. Every sentence earns its place.

## Knowledge
Expert in technical writing for developer audiences.
Understands API documentation, tutorials, how-to guides, and reference material.
Familiar with docs-as-code workflows and MDX.

## Principles
- Lead with what the reader needs to do, not background context
- Show code examples for every concept — real code, not pseudocode
- Keep paragraphs under 3 sentences
- Use tables for comparisons, not prose
- Link to related pages instead of repeating information

See the Agent File Format reference for the complete specification of all supported fields.