[FEATURE] `skillsDirectories` array in `settings.json`

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

Right now, skills are scoped to a single project. For organizations that want to standardize Claude workflows across multiple repos and teams, there's no clean native way to share a common skill library without resorting to symlinks or duplicating skill files everywhere.

Our team wants to maintain a shared claude-skills git repo that multiple engineering teams contribute to. Each project would reference it via skillsDirectories, and contributions would flow through normal PR review. This makes Claude skills a first-class, version-controlled team asset rather than something duplicated repo-by-repo.

Proposed Solution

Add a skillsDirectories config option to settings.json that works the same way as permissions.additionalDirectories, but specifically for Claude skills. This would allow teams to point Claude Code at one or more external directories containing shared skills, enabling cross-team or cross-company skill libraries managed via a shared git repo.

A shared, versioned skills directory would allow:

• A central git repo to serve as the source of truth for company-wide skills
• Teams to contribute skills back to the shared library via PRs
• Consistent Claude behavior across all projects in an organization
• Easy updates, pull the skills repo and all projects get the latest

Proposed API

// .claude/settings.json
{
  "skillsDirectories": [
    "/path/to/shared-company-skills",
    "/path/to/team-specific-skills"
  ]
}

Alternative Solutions

Symlinks work but are brittle, not portable across machines, and invisible to git. Making them a poor substitute for a native solution.

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

Right now, each team has their own repo and their own .claude/skills/ folder. Team A figured out a great skill for writing test cases in their stack. Team B independently wrote something similar. Team C doesn't have one at all.
With skillsDirectories:
The company creates a shared repo called company-claude-skills on their internal GitHub. The folder structure looks like:
company-claude-skills/
testing/
write-unit-tests.md
generate-mocks.md
code-review/
pr-summary.md
security-check.md
documentation/
write-jsdoc.md
update-readme.md
Each project's settings.json just points to it:
json{
"skillsDirectories": [
"/shared/company-claude-skills",
"/shared/platform-team-skills"
]
}
Now when any developer on any team runs Claude Code, they get the full company skill library automatically. When Team A improves their test-writing skill, they open a PR to the shared repo, Team B and C get the improvement on their next git pull.
The workflow becomes:

Junior dev notices Claude could handle a repetitive task better → writes a skill → opens PR
Tech lead reviews it → merges → whole company benefits
Skills evolve like code, with history, attribution, and review

It's essentially turning Claude skills into a shared internal tool that compounds in value over time, rather than siloed per-project configs.

Additional Context

Proposed API

// .claude/settings.json
{
  "skillsDirectories": [
    "/path/to/shared-company-skills",
    "/path/to/team-specific-skills"
  ]
}

This mirrors the existing `permissions.additionalDirectories` pattern, so the implementation path should be well-understood. Skills in external directories could follow the same resolution order as local skills, with local skills taking precedence to allow per-project overrides.

The `permissions.additionalDirectories` pattern already establishes a precedent for extending Claude Code's reach beyond the current project directory. `skillsDirectories` would be the same concept applied to skill discovery, no new architecture needed, just a parallel extension.