[FEATURE] Scoped skill discovery: allow per-subagent .claude/agents/<name>/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

Today, skills under .claude/skills are discovered globally. In projects that use multiple role-based subagents (e.g., architect.md, qa.md), this creates main-agent tool pollution:

Namespace clutter: the main agent is exposed to specialized tools it never uses, which can degrade tool-selection accuracy.

Maintenance overhead: avoiding this requires manually maintaining allowlists in frontmatter and/or using disabling flags, which becomes brittle as the project grows.

Proposed Solution

Add optional, isolated skill loading based on subagent-local directories. If a subagent definition exists at .claude/agents/<name>.md, Claude should additionally look for .claude/agents/<name>/skills/ and load those skills only into that subagent’s runtime context.

Example

.claude/
  agents/
    pm/
      skills/
        write-prd/
          SKILL.md

Expected Behavior

• Scoped visibility: skills under .claude/agents/<name>/skills/ are not discovered globally and are hidden from the main agent and other subagents.
• Automatic loading: when <name> subagent is invoked, its local skills are loaded without manual frontmatter configuration.
• Compatibility: subagents still inherit global skills from .claude/skills.
• Conflict rule (suggested): if a skill exists in both global and local scope with the same identifier, local should override global for that subagent.
• Graceful fallback: if the local skills directory doesn’t exist, ignore it (no error).

Goal
Improve encapsulation: keep the main agent as a clean orchestrator, while each subagent owns its internal specialized “machinery” privately.

Alternative Solutions

_No response_

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

_No response_

Additional Context

_No response_