Building Your First Agent
This is the fastest path from zero to a working custom agent. By the end you'll have a .agent file on disk that shows up in Exponential's agent picker and is ready to take a task.
For deeper reference on every field and section, see Writing Custom Agents and the Agent File Format reference.
Step 1 — Open the Create Agent flow
From the Agents page in the sidebar, click Create Agent (top-right).
You'll see a two-tab header:
- Create — the AI wizard. Describe the agent in plain language and the system drafts the full file for you.
- Configure — the manual form. Fill in name, personality, knowledge, principles, and capabilities yourself.
If this is your first agent, start in Create. The wizard is meant for exactly this — going from a one-sentence idea to a ready draft in two or three back-and-forth messages.
Step 2 — Describe the teammate you need
In the Create tab, type what you want the agent to be good at. Treat it like you're explaining a new hire to a recruiter — what problems will they solve, what tools do they know, how should they communicate?
A good first prompt is one sentence:
"A senior React/TypeScript engineer who values simplicity, writes tests for new components, and pushes back on over-engineering."
The wizard replies with a draft and shows it in the live preview on the right. Keep iterating until the preview looks right:
- Wrong tone? "Be more direct, less hedging."
- Missing knowledge area? "Also add accessibility (WCAG 2.1) and Tailwind."
- Too many principles? "Trim to the top 5."
When you're happy, click Apply to drop the draft into the form so you can save it.
Step 3 — Review the form (optional but recommended)
Switching to Configure shows the same draft as an editable form. This is the moment to glance over:
- Name and description — these are what your future self sees in the picker.
- Personality / Knowledge / Principles — the three markdown sections that become the agent's system prompt.
- Provider & model — Claude / Sonnet is a sensible default.
- Capabilities — pick any you want pre-attached. Most agents don't need this; capabilities resolve per-task automatically. See Capabilities.
You can switch back to the wizard at any point and ask for more changes.
Step 4 — Save
Click Save. Exponential writes a .agent file to:
| Location | Scope |
|---|---|
~/.claude/agents/your-agent.agent | Available in all spaces |
your-project/.claude/agents/your-agent.agent | Available only in that project's space |
You'll see it appear in the Agents grid immediately — no restart, no re-index.
Step 5 — Take it for a spin
Create a new task that matches your agent's strengths (use the React engineer example above on a UI task) and assign your new agent to it. Watch how the plan reflects the personality and principles you wrote.
If the plan feels off-character, that's signal — open the agent, tighten the Principles section, and try again. Iteration is the whole game.
Where to go next
- Writing Custom Agents — the full reference for every field and section
- Agent File Format — the complete
.agentspecification - Building Your First Capability — give your agent a reusable skill
- Working as Team Lead — patterns for orchestrating multiple agents