[Feature] Agent-scoped skill loading: only load skills declared by the active agent

Problem

When launching Claude Code with a specific agent (claude --agent sre), all skills from the plugin are loaded into context, even those unrelated to the agent's purpose. There's no way for an agent to declare which skills it needs.

This matters because:

• Context budget is limited (~16K chars / 2% of context window for skill descriptions). Loading irrelevant skills wastes this budget.
• Auto-invocation noise: Claude may consider skills that are irrelevant to the agent's domain.
• Plugin authors building multi-domain plugins (SRE + backend + frontend) can't scope skills per agent.

Current workarounds (and why they're insufficient)

| Workaround | Limitation |
|------------|-----------|
| disable-model-invocation: true | Skill description still loads into context budget |
| paths globs in frontmatter | Only controls auto-invocation, not loading; doesn't work for non-file-specific skills |
| Permission rules (allow: ["Skill(x)"]) | Controls execution, not loading — descriptions still consume context budget |
| Separate plugins per domain | Forces maintainers to manage N repos instead of one cohesive plugin |

Proposed solution

Allow agents to declare which skills they need via a skills field in their frontmatter. When launching with --agent, only those skills' descriptions are loaded into context.

Agent declares its skills

# agents/sre/AGENT.md
---
name: sre
description: "SRE agent for incident response and infrastructure tasks"
skills: ["sre-runbook", "kubernetes", "incident-response"]
---

You are an SRE agent...

# agents/backend-developer/AGENT.md
---
name: backend-developer
description: "Backend development agent"
skills: ["api-scaffold", "db-migration", "code-review"]
---

You are a backend development agent...

Behavior

• claude --agent sre → only loads descriptions for sre-runbook, kubernetes, incident-response
• claude --agent backend-developer → only loads descriptions for api-scaffold, db-migration, code-review
• claude (no agent) → current behavior, loads all skill descriptions

Alternative: skill tags

If a skills array feels too rigid, agents could declare tags instead:

# agents/sre/AGENT.md
---
name: sre
skill-tags: ["sre", "infra"]
---

# skills/sre-runbook/SKILL.md
---
name: sre-runbook
tags: ["sre"]
---

Skills matching any of the agent's skill-tags would be loaded.

Use case

We maintain a multi-domain engineering plugin with agents and skills for SRE, backend, and frontend. When an SRE launches claude --agent sre, they don't need backend scaffolding skills consuming context budget. Today there's no way to scope this — all skills load regardless of which agent is active.

🤖 Generated with Claude Code