Agents
An agent is a reusable, pre-configured AI persona for Claude Code. Each agent pairs a custom system prompt with a model, a per-tool permission set, and an optional cap on how many steps it may take. Define an agent once in your workspace and Claude Code can use it as a specialized helper or as the lead persona for a session.
SuperClawd Pipelines can run an agent like this autonomously on your board — assign a ticket and Claude plans it, works in an isolated git worktree, and opens a PR for your review. Learn more.
What an Agent Is
Where a skill is a bundle of instructions that gets layered onto your existing session, an agent is a self-contained configuration that defines a whole persona. An agent bundles together:
- A system prompt — the instructions injected as a system message when the agent runs (markdown, up to 50,000 characters).
- A model — the vendor and model the agent runs on.
- A tool permission set — for each built-in tool, whether the agent may use it, is blocked from it, or must ask first.
- A mode — whether the agent runs as a subagent (spawned to handle a delegated task) or a primary agent (drives a session directly).
- An optional step cap — a ceiling on the number of steps the agent may take in a single run.
Agents live in your workspace alongside skills. You manage them from the Agents page, where each agent shows its mode, model, and status.
Anatomy of an Agent
Every agent is described by the same set of fields. These are validated when you create, edit, or import an agent:
| Field | Description | Constraints |
|---|---|---|
| Name | A short identifier for the agent | Kebab-case, up to 30 characters (e.g. code-reviewer) |
| Description | What the agent does, shown in the agents list | Optional, up to 250 characters |
| Vendor | The model provider | anthropic |
| Model | The specific model the agent runs on | Chosen from the vendor's available models |
| Prompt | The system prompt that defines the agent's behavior | Markdown, up to 50,000 characters |
| Mode | How the agent participates in a session | subagent or primary |
| Tools | Per-tool permissions | Each tool set to allow, deny, or ask |
| Steps | Maximum steps per run | 1–1,000, or unlimited |
Creating an Agent
- Navigate to Agents in your workspace
- Click New Agent
- Configure the agent's identity and model:
- Name — a kebab-case identifier
- Mode — Subagent or Primary
- Description — what the agent does
- Vendor and Model — the model the agent runs on
- Click Create — you're taken straight to the prompt editor to write the agent's system prompt
Identity and model are configured in the metadata dialog; the prompt is authored on its own page (see Writing the Prompt). Tool permissions and the step cap are set separately (see Tool Permissions).
Subagent vs Primary
The mode determines how an agent takes part in a Claude Code session.
- Subagent — a specialist that is spawned to handle a delegated task. Subagents are launched by another agent (via the Task tool) to do focused work and report back, keeping their own context separate from the main conversation.
- Primary — an agent that drives a session directly as the lead persona, rather than being delegated to.
You can filter the agents list by mode, and switch an agent's mode at any time by editing its metadata.
The Task tool is what lets an agent spawn subagents. Because that is a powerful capability, Task is denied by default on new agents — turn it on deliberately for agents that should orchestrate others.
Writing the Prompt
The system prompt is the heart of an agent. It's written in markdown on the agent's own editor page and is injected as a system message when the agent is used:
- Open an agent
- Write the agent's instructions in the markdown editor
- Click Save Changes
The prompt is capped at 50,000 characters. Use it to define the agent's role, its standards, the steps it should follow, and any constraints it must respect.
"You are a focused code reviewer. Read the diff, flag correctness bugs and security issues first, then style. Be concise and cite file paths and line numbers. Do not modify files."
Tool Permissions
Each agent has fine-grained control over the built-in Claude Code tools. For every tool you choose one of three permissions:
- Allow — the agent may use the tool freely
- Deny — the agent is blocked from the tool
- Ask — the agent must request approval before each use
| Tool | What it does |
|---|---|
| Read | Read files from the filesystem |
| Glob | Search for files using glob patterns |
| Grep | Search file contents with regex |
| Edit | Edit existing files |
| Write | Create new files |
| Bash | Execute shell commands |
| WebFetch | Fetch content from URLs |
| Task | Spawn subagents for complex tasks |
New agents start with read-only discovery tools (Read, Glob, Grep) allowed and the higher-impact tools tuned conservatively — Task in particular is denied by default so that spawning subagents stays an explicit opt-in. Edit a tool permission set at any time from an agent's Edit Permissions action.
Step Cap
The step cap bounds how many steps an agent may take in a single run. You can set a specific limit between 1 and 1,000 steps, or mark the agent as unlimited. A step cap is a useful guardrail for autonomous agents, keeping a long-running task from looping indefinitely.
Using Agents in Claude Code
Agents defined in your workspace become available to Claude Code through SuperClawd. A primary agent can drive a session as its lead persona, while subagents are spawned on demand to handle delegated, focused tasks and report back. When an agent is used, its system prompt is injected and its tool permissions and step cap are enforced for that run.
What Claude Code actually loads is an agent's stable release, not its live draft. An agent that has never been released only runs for members in Experimental Mode — see Versioning & Releases below.
Enabling/Disabling Agents
You can toggle agents on and off:
- Go to the Agents page
- Find the agent you want to toggle
- Toggle it enabled or disabled
- Disabled agents are not made available to Claude Code
Filtering Agents
Use filters to find specific agents:
- Search — find agents by name
- Mode — filter by subagent or primary
- Status — show only enabled or disabled agents
Versioning & Releases
Agents support the same versioning model as skills. You edit a live draft, then promote a release to publish a stable version that Claude Code serves. Until you promote the first release, an agent is treated as a draft and runs only for members in experimental mode.
- Each release is an immutable snapshot of the agent's prompt, tools, and configuration.
- You can restore an earlier release, or roll back to a previous version.
- Flag an agent experimental to have its live draft load in the CLI's Experimental Mode while you iterate, without affecting the stable release everyone else gets.
See Versions & Releases for the full release model and Experimental Mode for how drafts are served.
Sharing & Importing
Agents can be shared between workspaces and exported as portable files:
- Share links — generate an unlisted, revocable link so another workspace can import a released version of your agent. See Sharing & Imports.
- JSON export/import — download an agent as JSON (its identity, prompt, model, tools, mode, and step cap) and import it into another workspace. Imported names that collide are renamed automatically.
- Community Agents — browse and install agents shared by the community. See Community Agents.
Best Practices
- Give each agent a single, well-defined job and a clear name
- Grant only the tools the agent needs — prefer deny or ask over allow for write, bash, and task
- Set a step cap on autonomous agents to bound runaway loops
- Iterate on a draft in experimental mode, then promote a release once it's solid
- Write the system prompt to be specific and actionable, with explicit constraints