Feature: Capability profiles — selectively load agents, skills, and commands per session

Problem

Claude Code loads all agents (.claude/agents/*.md), skills, and commands (.claude/commands/**/*.md) unconditionally at session start. There is no mechanism to control which capabilities are active for a given session.

In projects with many capabilities (20+ agents, 30+ skills), most sessions only use 2-4. The unused capability descriptions:

1. Consume context tokens — ~4-6k tokens of agent/skill descriptions loaded every session regardless of task
2. Dilute attention — the model considers irrelevant agents when routing tool calls, increasing the chance of suboptimal routing (e.g., spawning an agent when a direct tool call would suffice)
3. Clutter /context output — harder for developers to audit what's active

Proposed Solution

Option A: Profile-based selection (preferred)

Allow defining named profiles in settings.json or settings.local.json:

{
  "profiles": {
    "be-testing": {
      "agents": ["backend-integration-tester", "pst-pr-manager", "code-reviewer"],
      "commands": ["server/*"]
    },
    "ui-development": {
      "agents": ["ui-feature-developer", "frontend-developer"],
      "commands": ["client/*"]
    },
    "full": {
      "agents": ["*"],
      "commands": ["*"]
    }
  },
  "defaultProfile": "full"
}

CLI usage:

claude --profile be-testing

Option B: Direct CLI filtering

claude --agents backend-integration-tester,pst-pr-manager
claude --disable-agents "ui-*,sonar*"
claude --commands "server/*"

Option C: Agent/skill metadata (least invasive)

Add optional profile or tags frontmatter to agent/skill .md files:

---
name: "Backend Integration Tester"
profiles: ["be-testing", "full"]
tags: ["backend", "testing"]
---

Then filter at session start:

claude --profile be-testing  # Only loads agents/skills tagged with this profile

Current Workaround

We maintain a shell script that swaps symlinks in .claude/agents/ and .claude/commands/ to different profile directories. This works but:

• Requires symlink support (Windows needs Developer Mode or admin)
• Profile directories contain file copies that can drift from canonical versions
• No integration with --continue (switching mid-session requires restarting)

Context

• Project: ~20 custom agents, ~30 skills/commands, multiple MCP plugins
• Model: Claude Opus 4.6 with 1M context
• The token cost (~6k) is modest relative to 1M, but attention dilution during tool-selection reasoning is the primary concern
• Sessions are typically role-focused (BE testing, UI development, PR management) and rarely need all capabilities simultaneously

Expected Behavior

• claude (no flags) loads the default profile or all capabilities (backward compatible)
• claude --profile <name> loads only the specified profile's capabilities
• /context reflects only the active profile's capabilities
• --continue preserves the profile from the initial session
• Mid-session profile switching would be ideal but not required for v1