Feature request: frontmatter flag to hide subagents from the @ agent picker
Problem
When building a multi-agent pipeline, orchestrator agents delegate to subagents via:
Agent(subagent_type="feature-implementer", ...)
These subagent definitions must live in ~/.claude/agents/ or .claude/agents/ to be callable via subagent_type. However, they then appear in the @ typeahead picker alongside user-invocable agents, cluttering the picker and confusing users who shouldn't call them directly.
The current workaround — adding [SUBAGENT ONLY] to the description — is purely cosmetic. The user-invocable: false field is silently ignored.
Requested change
Add a supported frontmatter field — e.g. hidden: true or subagent_only: true — that:
- Excludes the agent from the
@typeahead picker and any agent selection UI - Still allows the agent to be invoked via
Agent(subagent_type="<name>")in orchestrators - Still allows
@agent-<name>direct mention if the user explicitly types the full name
Example
---
name: feature-implementer
description: "[SUBAGENT ONLY] Implements features from approved plans."
tools: Skill, Read, Edit, Write, Grep, Glob, Bash
hidden: true
---
Impact
Users building agent pipelines (CI/CD automation, multi-step workflows, audit pipelines) routinely have 10–15 subagents that are internal implementation details. Without this flag, the picker becomes unusable at scale — showing 20+ agents when only 10 are user-invocable.
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗