---
title: "Sub-agent Catalog"
source: https://docs.autohand.ai/guides/sub-agent-catalog
---

# Sub-agent Catalog

Find specialist agent definitions from Autohand's default catalog, approve what gets installed, and use the new roles for delegation or Agent Teams without restarting the CLI.

**Availability:** Catalog discovery and installation require Autohand Code `0.9.3` or newer. Run `autohand --version` to check.

## How the catalog works

Autohand includes model-facing tools that search a registry of specialist sub-agents and install an exact result when you approve it. You describe the role in your prompt; Autohand handles the catalog workflow.

| Stage | What Autohand does | What you control |
|---|---|---|
| Discover | Searches names, descriptions, categories, tools, models, and use cases | The role and constraints in your prompt |
| Select | Chooses an exact catalog result | Whether the proposed definition fits the task |
| Install | Downloads the Markdown definition | Approval before anything is written |
| Use | Reloads definitions for immediate delegation | Task boundaries, team composition, and final review |

The default registry and definitions live in the open-source [autohandai/awesome-sub-agents repository](https://github.com/autohandai/awesome-sub-agents).

## Request specialists in plain language

Tell Autohand which expertise the task needs and what it should do when that expertise is not installed. The prompt can ask for a team, parallel delegation, or a single specialist.

### Prepare specialists for a workflow

``` bash
autohand -p "Find UI design, security review, and API design specialists. \
Search the sub-agent catalog for missing roles, show the exact matches and tools, \
and request approval before installing them. Then propose whether each task should \
use direct delegation, parallel delegation, or a compatible task-based team."
```

### Delegate parallel reviews

``` bash
autohand -p "Review this feature in parallel for accessibility, security, \
and API compatibility. Find and install missing specialist sub-agents \
from the default catalog, then return one consolidated report."
```

### Use one specialist

``` bash
autohand -p "Find a specialist for PostgreSQL performance analysis, \
install the exact catalog match after I approve it, and delegate \
the query-plan review."
```

The catalog tools are part of the agent runtime. They are not shell commands, so you do not type `find_sub_agents` or `install_sub_agent` directly.

## Review each installation

Searching is read-only. Installing a definition always requests approval because it writes a persistent file to your user agent directory.

Before approving, check:

-   **Name and description.** Prefer a narrow role that matches the work you want delegated.
-   **Tool access.** Review-only specialists should not need write tools. Implementation specialists usually do.
-   **Model override.** A catalog definition may select a model for that role.
-   **Task boundary.** Decide which files and outputs the specialist owns before delegation starts.

**Security:** Agent definitions influence model behavior and tool access. Inspect unfamiliar definitions in the [GitHub catalog](https://github.com/autohandai/awesome-sub-agents) before installing them in a sensitive environment.

## Installation and persistence

Approved definitions are saved as Markdown files under `~/.autohand/agents/`. Autohand reloads the registry after installation, so the new sub-agent is available to direct delegation, parallel delegation, and team creation in the current session.

-   **Persistent:** Installed definitions are available in future projects and sessions.
-   **No silent replacement:** Existing definitions are not overwritten by default.
-   **Immediate:** You do not need to restart Autohand before assigning work.
-   **Inspectable:** The installed file is plain Markdown and can be reviewed locally.

List configured definitions from an interactive session:

``` bash
autohand
/agents definitions
```

## Use catalog agents in a team

A lead can add installed specialists as teammates and coordinate them through a shared task graph. Current team tasks do not select a named role: the first idle teammate claims the first unblocked task. Use a team only when every available task fits every idle teammate that might receive it, or stage homogeneous teams by phase.

When an exact specialist must receive exact work, use `delegate_task` or `delegate_parallel`. Read [Agent Teams and Task Graphs](/docs/guides/teams-and-swarms/agent-teams.html) for creation, assignment behavior, shared-workspace safety, task dependencies, status, messages, and shutdown.

For a runnable example, follow [Build a Specialist Agent Team from the Catalog](/docs/tutorials/build-specialist-agent-team.html).

## Choose agents that fit the work

-   **Start with the outcome.** Ask for “API compatibility review” instead of a general “backend expert.”
-   **Separate design from implementation.** Use read-focused agents for plans and reviews, then delegate changes to write-capable agents.
-   **Avoid overlapping ownership.** Two write-capable agents should not edit the same files at the same time.
-   **Keep the team small.** Add a role only when it has a distinct output or decision boundary.
-   **Verify the combined result.** The lead should run the project's checks and review cross-agent assumptions before completion.

## Troubleshooting

### Autohand does not search the catalog

Check that you are running Autohand Code `0.9.3` or newer. Make the prompt explicit: ask Autohand to search the default sub-agent catalog for missing roles.

### No exact match is found

Try a narrower role, technology, or use case. For example, replace “database expert” with “PostgreSQL query performance reviewer.” Autohand can search descriptions, categories, tools, and agent names.

### The definition already exists

Autohand preserves the installed definition by default. Review the local file under `~/.autohand/agents/` before asking to replace it.

### Search or download fails

Confirm that the machine can reach GitHub and the raw GitHub content domain. Agents already installed locally remain available even when the catalog cannot be reached.

## Next steps

[Build a Specialist Team](/docs/tutorials/build-specialist-agent-team.html) - Follow the catalog workflow from prompt to delegation

[Agent Teams and Tasks](/docs/guides/teams-and-swarms/agent-teams.html) - Coordinate compatible teammates through dependencies and shared task state

[GitHub Catalog](https://github.com/autohandai/awesome-sub-agents) - Inspect and contribute specialist agent definitions