Sub-agents

Sub-agents are custom AI configurations you create in braid. Each sub-agent has a system prompt, optional model override, and a set of linked skills — giving you a reusable, installable persona for your AI coding tools.

When to use sub-agents

Use sub-agents when you need a specialized AI persona:

A “code reviewer” sub-agent with strict linting skills and a review-focused prompt
A “migration assistant” sub-agent scoped to a specific project with database skills linked
A “junior onboarding” sub-agent with simplified guidance and beginner-friendly skills

How sub-agents work

Create a sub-agent in braid.cloud with a name, system prompt, and linked skills
Run braid agents install --id <agent-id> to write it to your local coding tools
The sub-agent’s prompt and skills are installed as native files

Sub-agent properties

Property	Description
name	Display name for the sub-agent
prompt	System prompt that defines the sub-agent’s behavior
mode	`primary`, `subagent`, or `all` — controls how the sub-agent operates
model	Optional LLM model override
skills	Linked skills the sub-agent can reference
scope	`global` (all projects) or `project` (single project)

Installing sub-agents

Once created in braid.cloud, install a sub-agent to your local coding tools:

braid agents install --id <agent-id> --agents claude-code,cursor

Install globally (applies to all projects):

braid agents install --id <agent-id> --global

Managing sub-agents via CLI

The CLI also supports listing and managing sub-agents:

braid agents list              # List all sub-agents
braid agents get --id <id>     # View a sub-agent
braid agents remove --id <id>  # Delete a sub-agent

Sub-agents vs target tools

braid uses “agents” in two different ways depending on context:

braid sub-agents (this page) — custom AI configurations you create and install
Target tools — the AI coding tools braid writes files to (Cursor, Claude Code, Windsurf, etc.)

When you run braid install --agents claude-code,cursor, the --agents flag refers to target tools. When you run braid agents install, you’re installing a braid sub-agent configuration.