[FEATURE] Add a setting to opt out of recursive skill/agent inheritance from parent directories

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

Problem

Claude Code discovers skills and subagents by walking up from CWD through every parent .claude/skills/ and .claude/agents/ directory, plus the user-scope ~/.claude/. There is currently no setting to disable or scope this inheritance per project.

This becomes a problem when a project lives inside a larger parent tree — for example a workspace folder, a knowledge base, or a monorepo — that contains many skills and agents relevant to the parent context but not to the child project. In such setups:

• The child project inherits dozens of unrelated skill and agent descriptions, even though only a handful (or none) are relevant.
• Skill and agent descriptions are injected into the system prompt for routing, so they consume tokens and enlarge the action menu the model has to consider.
• The user is forced to choose between filesystem reorganization (often impractical due to sync tools, shared workspaces, or required directory layouts) and accepting the bloat.

Even though skill bodies are lazy-loaded, the descriptions are always loaded eagerly. With dozens of inherited entries this can:

1. Waste tokens, especially noticeable on smaller models or in long sessions.
2. Increase the chance of mis-routing to an irrelevant skill or agent.
3. Make it harder for the model to focus on the project's actual scope.

Current workarounds and why they are insufficient

| Workaround | Limitation |
|---|---|
| permissions.deny: ["Skill(*)"] in project settings | Blocks invocation but does not prevent the descriptions from being loaded into the system prompt. |
| Move the project out of the parent tree | Often not possible — the parent tree may be a synced folder, an enforced workspace layout, or a monorepo with required structure. |
| Symlink or rename tricks to hide parent .claude/skills/ conditionally | Fragile, breaks the parent's own context, and easy to forget to undo. |
| Shorten skill description frontmatter | Reduces token cost marginally but does not address the underlying inheritance behavior. |

Why this matters

Hierarchical discovery of skills, agents, and memory is one of the strengths of Claude Code — it makes capabilities composable across user and project scopes. But the model implicitly assumes parent directories are always relevant context, which breaks down for nested or co-located projects with their own identity. Being able to declare "this project is its own scope" without filesystem gymnastics would meaningfully improve the experience for anyone running multiple Claude Code projects under a shared parent directory.

Related

• Memory files (CLAUDE.md) follow the same recursive discovery pattern and would benefit from a parallel memoryInheritance setting, though that is a separate concern.
• This is not the same as enableAllProjectMcpServers, which controls MCP servers rather than skills, agents, or memory.

Proposed Solution

Add a setting to .claude/settings.json and .claude/settings.local.json that controls how skills and agents are inherited:

{
  "skillsInheritance": "project-only",
  "agentsInheritance": "project-only"
}

Possible values:

| Value | Behavior |
|---|---|
| "all" (default — current behavior) | Load from CWD, all parent directories, and user scope |
| "project-only" | Load only from .claude/skills (or .claude/agents) in CWD and its nested subdirectories |
| "project-and-user" | Load from CWD plus user scope, skipping intermediate parents |
| "project-and-parents" | Current behavior minus user scope |

Alternative: explicit allowlist/denylist

If a coarse inheritance flag is undesirable, an alternative is per-project filtering by name or glob:

{
  "skills": {
    "exclude": ["pattern-*", "another-pattern-*"]
  },
  "agents": {
    "exclude": ["agent-name-1", "agent-name-2"]
  }
}

This is more flexible but more verbose. A single inheritance flag covers the common case in one line; an exclude list covers the long tail.

Alternative Solutions

| Workaround | Limitation |
|---|---|
| permissions.deny: ["Skill(*)"] in project settings | Blocks invocation but does not prevent the descriptions from being loaded into the system prompt. |
| Move the project out of the parent tree | Often not possible — the parent tree may be a synced folder, an enforced workspace layout, or a monorepo with required structure. |
| Symlink or rename tricks to hide parent .claude/skills/ conditionally | Fragile, breaks the parent's own context, and easy to forget to undo. |
| Shorten skill description frontmatter | Reduces token cost marginally but does not address the underlying inheritance behavior. |

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

Scenario: Focused child project inside a larger knowledge base

A user maintains a large personal knowledge base at ~/workspace/ containing notes, documentation, and ~50 skills plus ~20 subagents configured under
~/workspace/.claude/ for general-purpose tasks (research, note-taking, calendar, email, analytics, etc.).

Inside that workspace, they start a new focused sub-project at ~/workspace/publisher/ — an autonomous content publishing system with its own purpose, its
own CLAUDE.md, and a small set of dedicated skills and agents under ~/workspace/publisher/.claude/ (roughly 4 agents and 5 skills, all publishing-related).

Step-by-step:

1. User runs claude from ~/workspace/publisher/.
2. Claude Code walks up the directory tree and discovers .claude/skills/ and .claude/agents/ in both the publisher project and the parent workspace.
3. All 50+ workspace skills and 20+ workspace agents are loaded into the system prompt alongside the 5 publisher-specific skills and 4 publisher-specific

agents.

1. The user checks /context and sees ~4k tokens consumed by skill and agent descriptions that are completely irrelevant to publishing work — calendar

skills, email skills, research skills, analytics agents, etc.

1. The user tries to work around this:

• Cannot move publisher/ out of workspace/ because the workspace is a synced folder and the sub-project needs to stay inside it for sync to work.
• Adding permissions.deny: ["Skill(*)"] in publisher/.claude/settings.json prevents invocation but leaves all the descriptions in the system prompt.
• Symlink tricks are fragile and break the parent workspace's own Claude Code sessions.

1. The user accepts the bloat because there is no other option.

What this feature would enable:

The user adds one line to ~/workspace/publisher/.claude/settings.json:

{
"skillsInheritance": "project-only",
"agentsInheritance": "project-only"
}

Now when they run claude from publisher/, only the publisher's own 5 skills and 4 agents are loaded. The workspace's general-purpose tooling stays available
when working from ~/workspace/ itself, but is cleanly scoped out of the focused sub-project. No filesystem gymnastics, no symlinks, no lost sync.

Additional Context

_No response_