Sub-agent Catalog

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.

The default registry and definitions live in the open-source autohandai/awesome-sub-agents repository.

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

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

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

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.

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:

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 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.

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