[DOCS] `--add-dir` docs missing automatic `.claude/skills/` loading behavior (v2.1.32)

[coygeek]

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/skills

Section/Topic

Skill discovery behavior when additional directories are added via --add-dir.

Current Documentation

The docs currently say skills are discovered from normal locations and nested subdirectories under the working tree:

"When you work with files in subdirectories, Claude Code automatically discovers skills from nested .claude/skills/ directories..."

And memory docs currently frame --add-dir behavior around CLAUDE.md files only:

"The --add-dir flag gives Claude access to additional directories outside your main working directory. By default, CLAUDE.md files from these directories are not loaded."

No page explains whether skills inside added directories are loaded automatically.

What's Wrong or Missing?

Claude Code changelog v2.1.32 says:

Skills defined in .claude/skills/ within additional directories (--add-dir) are now loaded automatically.

Current docs do not describe this behavior, and nearby wording can imply added directories only affect file access and optional CLAUDE.md loading. This makes the new capability hard to discover and can lead users to think skills in added directories are unsupported.

Suggested Improvement

Update docs to explicitly document this new behavior:

1. Add --add-dir skill-loading details to skills docs (with precedence and scope).
2. Add a note in cli-reference under --add-dir describing automatic .claude/skills/ discovery in added directories.
3. Clarify in memory docs that CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD controls memory-file loading, while skills in added directories now auto-load independently.
4. Include one concrete example command and folder layout.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Page	Line(s)	Context
https://code.claude.com/docs/en/skills	88-91	Documents nested skill discovery but not --add-dir skill discovery
https://code.claude.com/docs/en/cli-reference	29	--add-dir row mentions directory access only
https://code.claude.com/docs/en/memory	67-75	--add-dir described only in relation to CLAUDE.md memory loading
https://code.claude.com/docs/en/permissions	197-201	Additional directories discussed as permission scope only
https://code.claude.com/docs/en/settings	763	Env var description focuses on CLAUDE.md loading

Total scope: 5 pages affected

Source: Claude Code changelog v2.1.32

Skills defined in .claude/skills/ within additional directories (--add-dir) are now loaded automatically.

[coygeek]

Issue #23404 Verification

Title: [DOCS] --add-dir docs missing automatic .claude/skills/ loading behavior (v2.1.32)
Issue Date: 2026-02-05
Verification Date: 2026-02-07
Status: PARTIALLY RESOLVED

---

Issue Summary

This issue reports missing documentation for automatic skill loading from .claude/skills/ directories inside paths added via --add-dir, plus related cross-page clarity across CLI/memory/settings/permissions docs.

---

Verification Results

Claim 1: Skills docs do not mention .claude/skills/ auto-loading from --add-dir

Status: RESOLVED

Evidence in docs/code.claude.com/docs/en/skills.md:

• Line 110: #### Skills from additional directories
• Line 112: "Skills defined in .claude/skills/ within directories added via --add-dir are loaded automatically..."

Verdict: The core missing behavior is now documented on the skills page.

---

Claim 2: Docs ambiguity between memory-file loading and skills loading in added directories

Status: RESOLVED

Evidence in docs/code.claude.com/docs/en/skills.md:

• Line 115: Explicit note that CLAUDE.md loading is separate and controlled by CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD.

Verdict: The skills page now distinguishes skills auto-loading from memory-file loading behavior.

---

Claim 3: Related pages should also reflect the new behavior (cli-reference, memory, etc.)

Status: UNRESOLVED

Evidence:

• docs/code.claude.com/docs/en/cli-reference.md:29 still describes --add-dir as directory access only.
• docs/code.claude.com/docs/en/memory.md:127 still focuses specifically on CLAUDE.md loading from added directories.

Verdict: The primary page was fixed, but cross-page propagation remains incomplete.

---

Current State

Claim	Status
Skills page documents --add-dir skill auto-loading	RESOLVED
Skills page clarifies separation from CLAUDE.md loading	RESOLVED
CLI/memory cross-page coverage of the same behavior	UNRESOLVED

---

Suggested Fix

Add one-line cross-reference updates to the related pages:

• cli-reference --add-dir row: mention skill auto-discovery in added directories.
• memory additional directories section: include short note that this setting affects memory-file loading only, not skill auto-loading.

---

References

• URL: https://code.claude.com/en/skills

• Lines 110-116 in mirror: New Skills from additional directories section and CLAUDE.md distinction

• URL: https://code.claude.com/en/cli-reference

• Line 29 in mirror: --add-dir row lacks explicit skill auto-load language

• URL: https://code.claude.com/en/memory

• Lines 127-129 in mirror: additional-directory section still memory-focused

---

Conclusion & Recommendation

Primary Concern: Users could not discover that skills in --add-dir directories load automatically.

Resolution Status: UNRESOLVED

Recommendation: KEEP OPEN

The core skills page gap is fixed, but the issue requested broader cross-page clarity that is still incomplete.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.