claude-code - 💡(How to fix) Fix Docs: skill discovery across nested git repos via parent-walk and `additionalDirectories` doesn't match documented behaviour

Summary

The skills page documents two mechanisms for picking up .claude/skills/ outside the current working directory, but in a sibling-repo / cloned-in-workspace layout neither produces the documented effect. Raising both a doc-clarity gap and a possible feature parity gap between the --add-dir CLI flag and the settings-file permissions.additionalDirectories.

Documented behaviour

Automatic discovery from parent and nested directories Project skills load from .claude/skills/ in your starting directory and in every parent directory up to the repository root, so starting Claude in a subdirectory still picks up skills defined at the root.

Skills from additional directories The --add-dir flag grants file access rather than configuration discovery, but skills are an exception: .claude/skills/ within an added directory is loaded automatically.

Layout that triggers it

A monorepo-of-cloned-in-repos pattern (common when an umbrella project's bootstrap script clones in external repos as gitignored siblings):

parent/                  ← has its own .git/, .claude/skills/ (N skills)
├── childA/              ← its own .git/ (separate repo), .claude/settings.json
├── childB/              ← its own .git/ (separate repo)
└── childC/              ← its own .git/ (separate repo)

Each child has:

// childA/.claude/settings.json
{ "permissions": { "additionalDirectories": ["../"] } }

Opening Claude Code at parent/childA/:

• Parent walk: the "every parent directory up to the repository root" walk stops at childA/ because that's the first .git/ it hits going up. parent/.claude/skills/ is never discovered.
• additionalDirectories skill exception: permissions.additionalDirectories: ["../"] is set, but parent/.claude/skills/ is also not loaded.

Result: 0 of the parent's .claude/skills/ are available. Confirmed on 2.1.150 on Windows 11 / PowerShell 7.

Questions for the docs

1. "Repository root" definition. When sibling git repos are nested inside an outer git repo, is the documented parent walk meant to stop at the innermost .git/ (current behaviour) or continue across the boundary? The phrase "up to the repository root" doesn't say whose root, and the cloned-in / bootstrapped-monorepo pattern is common enough that the doc should resolve it explicitly.

2. --add-dir flag vs permissions.additionalDirectories setting. The "skills are an exception" prose is written only against the --add-dir flag. Is the exception meant to apply equivalently to permissions.additionalDirectories in settings, or is it CLI-flag-only? If both, this looks like a bug. If flag-only, the docs should say so and recommend a pattern for the cloned-in-workspaces layout.

Why this matters

The cloned-in-workspaces pattern (one umbrella repo + N external sub-repos bootstrapped under it) is a common way to organise multi-service projects and is encouraged by the additionalDirectories description itself ("documentation, shared utilities, or other project-adjacent directories"). Without skill discovery across that boundary, project-shared skills have to be duplicated into every workspace, or the user has to remember to open CC at the parent root for cross-system work.

Minimal repro

mkdir parent && cd parent && git init
mkdir -p .claude/skills/parent-skill
cat > .claude/skills/parent-skill/SKILL.md <<'INNER'
---
description: A parent-shared skill that should be reachable from child workspaces.
---
hello from parent
INNER

mkdir child && cd child && git init
mkdir -p .claude
cat > .claude/settings.json <<'INNER'
{ "permissions": { "additionalDirectories": ["../"] } }
INNER

claude            # open here, ask "What skills are available?"
# Expected per docs: parent-skill listed
# Actual: parent-skill not listed

Additionally: claude --add-dir ../ from child/ should — per the doc's skill exception — produce the same result as the settings-file form; testing both clarifies whether the asymmetry is real.

Suggested doc fix

Whichever side of the question is the intended behaviour:

• Clarify "repository root" with one extra sentence covering the nested-git-repo case.
• Either confirm the skill-exception applies to permissions.additionalDirectories (and treat the current behaviour as a bug to fix in code) or explicitly carve it out as flag-only and recommend the pattern (e.g. open CC at the parent root, symlink the parent skills dir, or pass --add-dir in the launcher).