Feature request: frontmatter flag to hide subagents from the @ agent picker

Resolved 💬 3 comments Opened Apr 20, 2026 by threnjen Closed May 28, 2026

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:

  1. Excludes the agent from the @ typeahead picker and any agent selection UI
  2. Still allows the agent to be invoked via Agent(subagent_type="<name>") in orchestrators
  3. 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.

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗