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

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.