[FEATURE] Allow skills to be hidden from the main agent (subagent-exclusive skills)

[Roeia1]

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Subagents can already specify which skills to auto-load using the skills: field in their frontmatter:

---
name: db-admin
description: Database administration tasks
tools: Bash, Read
skills: database-migration, postgres-ops  # Skills to auto-load for this subagent
---

However, there's no way to hide a skill from the main agent. All skills in ~/.claude/skills/ and .claude/skills/ have their metadata (name and description) loaded into the main agent's system prompt at startup, regardless of whether they're intended only for subagents.

The problem:

• Main agent's context gets polluted with skills it shouldn't use
• Main agent may attempt tasks that should be delegated to specialized subagents
• Can't create truly exclusive subagent capabilities
• Extra token overhead from irrelevant skill metadata in main agent's prompt

Current workaround: Embed the knowledge directly in the subagent's .md file instead of creating a skill. This works but loses the benefits of skills (progressive disclosure, reusability across multiple subagents, composability, separate maintenance).

Proposed Solution

Add an optional field to SKILL.md frontmatter that hides the skill from the main agent:

---
name: database-migration
description: Database migration procedures for PostgreSQL
main-agent: false  # Hide from main agent, only subagents can discover this skill
---

Or alternatively, an allowlist approach:

---
name: database-migration
description: Database migration procedures for PostgreSQL
agents: db-admin, data-engineer  # Only these agents can see this skill (main agent excluded)
---

Behavior:

• If field is omitted → skill visible to all agents including main (backward compatible)
• If main-agent: false → skill metadata not loaded into main agent's context, only available to subagents that reference it via their skills: field
• If agents: allowlist specified → only those agents see the skill

Alternative Solutions

Workaround 1: Embed knowledge directly in the subagent's .md file

Instead of creating a skill, put all the instructions directly in the subagent's system prompt:

---
name: db-admin
description: Database administration tasks
tools: Bash, Read
---

# Database Admin Agent

## Database Migration Procedures
[All the specialized knowledge here - only this subagent sees it]

This works but loses the benefits of the skills system:

• No progressive disclosure (everything loads into context immediately)
• Can't reuse the same knowledge across multiple subagents
• Can't use skill scripts or reference files
• Harder to maintain separately from agent logic

Workaround 2: Use a very specific description to discourage main agent usage

---
name: database-migration
description: "ONLY for db-admin subagent. Do NOT use directly - always delegate to db-admin subagent."
---

This is unreliable - the main agent may still attempt to use the skill despite the description.

Workaround 3: Add delegation instructions to CLAUDE.md

## Task Delegation Rules
- Database migrations → always delegate to db-admin subagent
- Never use the database-migration skill directly

This adds overhead to CLAUDE.md and relies on the main agent following instructions rather than enforcing isolation at the system level.

Priority

Critical - Blocking my work

Feature Category

Configuration and settings

Use Case Example

No response

Additional Context

The subagent skills: field already allows subagents to opt-in to specific skills. This feature request is for the inverse - allowing skills to opt-out of the main agent. Together, these would enable full control over skill visibility across the agent hierarchy.

[github-actions[bot]]

Found 2 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/6915
2. https://github.com/anthropics/claude-code/issues/4380

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[Roeia1]

Found 2 possible duplicate issues:

1. Allow MCP tools to be available only to subagent #6915
2. Feature: Per-agent MCP tool filtering to improve agent focus and accuracy #4380

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

This is not a duplicate of the linked issues.

• #6915 and #4380 are about MCP tools filtering
• This issue is about Skills scoping

These are different systems in Claude Code:

• MCP tools = external tools exposed via Model Context Protocol servers
• Skills = SKILL.md files with instructions, scripts, and resources that Claude loads dynamically

The feature request here is to add a frontmatter field to SKILL.md (like main-agent: false or agents: [list]) to control which agents can discover the skill. This is unrelated to MCP tool filtering.

That said, this issue is conceptually similar to #6587 (Selective MCP Access Control for SubAgents) - both address the same underlying need for agent-scoped capabilities, just for different systems (Skills vs MCP). Implementing a consistent solution across both would be ideal.

[kitaekatt]

I currently have 87 of 113 skills visible in my system prompt and no agency over which skills are and are not visible. This would solve this problem.