Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix Feature request: frontmatter flag to hide subagents from the @ agent picker

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…

Fix Action

Fix / Workaround

The current workaround — adding [SUBAGENT ONLY] to the description — is purely cosmetic. The user-invocable: false field is silently ignored.

Code Example

---
name: feature-implementer
description: "[SUBAGENT ONLY] Implements features from approved plans."
tools: Skill, Read, Edit, Write, Grep, Glob, Bash
hidden: true
---
RAW_BUFFERClick to expand / collapse

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.

extent analysis

TL;DR

Add a hidden: true field to the subagent definitions to exclude them from the @ typeahead picker while still allowing invocation via Agent(subagent_type="<name>").

Guidance

  • Add a hidden: true field to the frontmatter of subagent definitions to prevent them from appearing in the @ typeahead picker.
  • Verify that the subagent is still invocable via Agent(subagent_type="<name>") in orchestrators.
  • Test that direct mention via @agent-<name> still works when the user explicitly types the full name.
  • Consider updating the documentation to reflect the new hidden field and its usage.

Example

---
name: feature-implementer
description: "Implements features from approved plans."
tools: Skill, Read, Edit, Write, Grep, Glob, Bash
hidden: true
---

Notes

The hidden field should be added to the subagent definitions in ~/.claude/agents/ or .claude/agents/ to take effect.

Recommendation

Apply the workaround by adding the hidden: true field to subagent definitions, as this provides a clear and effective solution to the problem of cluttered typeahead pickers.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#prompt template#agent execution#callback error#memory management#API rate limit

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix Feature request: frontmatter flag to hide subagents from the @ agent picker