## Description Skills defined in `.claude/skills/` within additional directories are **not loaded** when configured via `permissions.additionalDirectories` in settings, but **are loaded** when using the `--add-dir` CLI flag. The [settings documentation](https://code.claude.com/docs/en/settings) states that `permissions.additionalDirectories` is functionally equivalent to `--add-dir`, and the [skills documentation](https://code.claude.com/docs/en/skills#skills-from-additional-directories) says:

Reproduced on macOS (Darwin 25.3.0), today (2026-04-16). **Setup** - `~/.claude/settings.json` → `"permissions": {"additionalDirectories": ["/abs/path/to/workspace-repo"]}` - 22 skills at ` /.claude/skills/ /SKILL.md`, valid hyphenated frontmatter (`name`, `description`, `disable-model-invocation`, `user-invocable`, `allowed-tools`) per [skills.md frontmatter reference](https://code.claude.com/docs/en/skills#frontmatter-reference) - `~/.claude/skills/` deleted (backup retain

[BUG] permissions.additionalDirectories does not load skills from added directories (--add-dir CLI flag does)

Status Fixed / completed

Reported on v2.1.63

Maintainer reply None cached

Workaround ✓ Mentioned in thread ↓

Activity 6 comments · opened Mar 2, 2026 · closed Aug 19, 2026

Description

Skills defined in .claude/skills/ within additional directories are not loaded when configured via permissions.additionalDirectories in settings, but are loaded when using the --add-dir CLI flag.

The settings documentation states that permissions.additionalDirectories is functionally equivalent to --add-dir, and the skills documentation says:

Skills defined in .claude/skills/ within directories added via --add-dir are loaded automatically

Steps to Reproduce

Setup

Additional directory structure:

.local_skill/
  .claude/
    skills/
      my-skill/
        SKILL.md   # valid frontmatter + content

Case 1: settings file (FAILS)

.claude/settings.local.json:

{
  "permissions": {
    "additionalDirectories": ["../.local_skill"]
  }
}

Launch: claude

The directory IS recognized as an additional working directory (shown in environment info)
Skills are NOT listed in the system message skill list
/my-skill returns "Unknown skill"

Case 2: CLI flag (WORKS)

Launch: claude --add-dir ../.local_skill

Skills ARE listed in the system message skill list
/my-skill works correctly

Expected Behavior

Both methods should load skills identically, as documented.

Environment

Claude Code version: 2.1.63
OS: macOS (Darwin 23.6.0)

View original on GitHub ↗

5 Comments

github-actions[bot] · 6 months ago

Found 1 possible duplicate issue:

https://github.com/anthropics/claude-code/issues/22583

This issue will be automatically closed as a duplicate in 3 days.

If your issue is a duplicate, please close it and 👍 the existing issue instead
To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

ccn-takabe-kyohei · 6 months ago

This is not a duplicate. #22583 is about CLAUDE.md not loading, while this issue is about skills not loading from additionalDirectories.

They likely share a root cause — permissions.additionalDirectories in settings is not treated equivalently to the --add-dir CLI flag — but the affected functionality is different:

| Issue | What doesn't load |
|-------|-------------------|
| #22583 | CLAUDE.md |
| #30064 (this) | .claude/skills/ |

Both work correctly with --add-dir CLI flag, both fail with permissions.additionalDirectories in settings.

flibustier7seas · 5 months ago

The same problem on windows: https://github.com/anthropics/claude-code/issues/33962

paal-computas · 5 months ago

Is there any progress on this bug?

KiTheAiGuy · 4 months ago

Reproduced on macOS (Darwin 25.3.0), today (2026-04-16).

Setup

~/.claude/settings.json → "permissions": {"additionalDirectories": ["/abs/path/to/workspace-repo"]}
22 skills at <workspace-repo>/.claude/skills/<name>/SKILL.md, valid hyphenated frontmatter (name, description, disable-model-invocation, user-invocable, allowed-tools) per skills.md frontmatter reference
~/.claude/skills/ deleted (backup retained)
Full Claude Code restart (fresh process)

Result: Zero custom skills surfaced in the / menu or in the session's initial available-skills list. Only bundled skills (/simplify, /loop, etc.) appear.

Workaround: Restored ~/.claude/skills/ — all 22 skills load fine via the personal-scope path.

Confirming this is identical symptom to the Windows repro in #43267 (auto-closed as duplicate of this issue). Rolled back the vendor-native approach and will revisit once this ships a fix.

Showing cached comments. Read the full discussion on GitHub ↗