Guides

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.

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:

LocationScope
~/.claude/agents/your-agent.agentAvailable in all spaces
your-project/.claude/agents/your-agent.agentAvailable 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

On this page