---
title: "Build a Specialist Agent Team from the Catalog"
source: https://docs.autohand.ai/tutorials/build-specialist-agent-team
---

# Build a Specialist Agent Team from the Catalog

Ask Autohand to find the missing roles for a task, approve the exact sub-agents it selects, and delegate UI, security, and API design work in one session.

Intermediate 15 min

autohand -p "Bring a team of UI design, security review, and API design specialists. Search the sub-agent catalog for missing roles, install exact matches, create the team, and delegate the work."

## What you'll learn

-   How to ask for specialist roles without knowing their catalog names
-   How Autohand searches and selects exact sub-agent matches
-   What to review before approving an installation
-   How installed specialists become available to the current team immediately

## Before you start

-   **Autohand Code 0.9.3 or newer.** Earlier versions do not include catalog discovery and installation.
-   **A project you can safely inspect.** Start with a small task while you learn how each specialist is scoped.
-   **Network access to GitHub.** Autohand reads the default registry and downloads approved definitions from the catalog.

**Check your version:** Run `autohand --version`. Upgrade before continuing if the result is lower than `0.9.3`.

## Step 1: Open the project

Run the request from the repository where the specialists should work. Autohand uses that project as the shared context for discovery and delegation.

``` bash
cd path/to/your-project
autohand --version
```

The catalog feature is available when the reported version is `0.9.3` or newer.

## Step 2: Describe the team by role

Use a single prompt that names the expertise you need and tells Autohand what to do if a role is missing locally.

``` bash
autohand -p "Bring a team of UI design, security review, and API design specialists. \
Search the sub-agent catalog for missing roles, install exact matches, \
create the team, and delegate the work."
```

You do not need to pass the registry URL or call catalog tools yourself. Autohand searches the default [awesome-sub-agents catalog](https://github.com/autohandai/awesome-sub-agents) when the requested specialists are not already available.

## Step 3: Review and approve the matches

Autohand searches by role, description, category, tools, and use case. For this team, the catalog includes focused definitions such as `ui-designer`, `security-auditor`, and `api-designer`.

| Requested role | Example exact match | Primary responsibility |
|---|---|---|
| UI design | ui-designer | Interaction decisions and implementation-ready UI guidance |
| Security review | security-auditor | Auth, secrets, input validation, and configuration review |
| API design | api-designer | API contracts, compatibility, and evolution planning |

Each installation pauses for approval before Autohand writes the definition. Review the exact name, description, and tool list, then approve only the specialists that fit the task.

**Important:** Discovery is automatic; installation is not silent. Declining an approval leaves your local agent definitions unchanged.

## Step 4: Let Autohand create and delegate

After approval, Autohand saves each definition under `~/.autohand/agents/` and reloads the agent registry. The new specialists can join the team in the same session—no restart is required.

Keep the responsibilities separate so the lead has clear outputs to combine:

-   `ui-designer` defines the interface behavior and visual constraints.
-   `security-auditor` identifies risks and required controls.
-   `api-designer` defines request, response, error, and compatibility contracts.

For a deeper explanation of team coordination, task ownership, and dependencies, read [Agent Teams](https://docs.autohand.ai/working-with-autohand-code/agent-teams).

## Step 5: Verify the installed definitions

Open an interactive session and list the configured definitions.

``` bash
autohand
/agents definitions
```

The installed specialists remain available in future sessions. If a definition with the same name already exists, Autohand keeps it by default instead of overwriting it.

## What you learned

-   You described a team in plain language instead of maintaining agent definitions by hand.
-   Autohand searched the default GitHub catalog for exact specialist matches.
-   You reviewed and approved each install before it changed `~/.autohand/agents/`.
-   The installed specialists were ready for delegation in the same session.

## Next steps

[Sub-agent Catalog Guide](/docs/guides/sub-agent-catalog.html) - Understand discovery, approvals, persistence, selection, and troubleshooting

[Agent Teams](https://docs.autohand.ai/working-with-autohand-code/agent-teams) - Learn how the lead coordinates teammates, tasks, dependencies, and results

[GitHub Catalog](https://github.com/autohandai/awesome-sub-agents) - Inspect available definitions and follow catalog updates at the source