[FEATURE] Let a project skill take precedence over a personal skill of the same name (configurable skill precedence)

Preflight Checklist

• [x] I have searched existing issues and this hasn't been requested yet (closest: #20309, closed as documented behaviour and inviting this request; #22208, auto-closed as its duplicate)
• [x] This is a single feature request

Problem Statement

When a skill exists at both the personal level (~/.claude/skills/<name>/) and the project level (<repo>/.claude/skills/<name>/), the personal one always wins. This is the documented rule ("enterprise overrides personal, and personal overrides project", https://code.claude.com/docs/en/skills, Resolve skills that share a name), and #20309 was closed on 2026-08-19 as documented behaviour with the note that a configurable or project-first order "is best filed as a feature request". #22208 had asked for exactly that but was auto-closed as a duplicate of #20309 before the bug was closed, so the request itself was never evaluated. This is that request.

The fixed personal-over-project order breaks the common case of a team repo carrying its own workflow skills. A project's commit skill encodes the repo's commit conventions, gates and prefixes; a developer's personal commit skill encodes their defaults for every other repo. Inside the project the repo's version is the one that should run, and every contributor should get the same one, yet today it is silently shadowed by whatever the developer happens to keep at home. The project cannot fix this from its side: skillOverrides is keyed by skill name and hides the name (the docs say invoking a hidden skill by full name still returns the skillOverrides error), so it cannot express "hide the personal copy, keep the project copy". Renaming is not a fix either: the project skill's name is the convention the whole team and its CLAUDE.md refer to, and the personal skill's name is what the same developer uses everywhere else.

The rest of Claude Code already resolves local-over-global: agents in .claude/agents/ override a user agent of the same name (/agents shows the user one as "overridden by projectSettings"), project settings.json overrides user settings, and CLAUDE.md layers stack in the same direction. Skills are the one surface where the global copy wins.

Proposed Solution

A setting that decides the order, with the current behaviour as the default so nothing changes for anyone who does not opt in:

{
  "skillPrecedence": "personal-first" | "project-first"
}

• "personal-first" (default): today's order, enterprise > personal > project.
• "project-first": enterprise > project > personal, i.e. a project skill shadows a personal skill of the same name while the cwd is inside that project; outside it the personal skill runs as before.

Honoured in the project's .claude/settings.json (so the repo can declare it for every contributor) and in ~/.claude/settings.json (so a developer can choose it for all their projects). The enterprise level stays on top in both modes, so managed policy is unaffected. The /skills menu and the skill list Claude sees would show the winning copy under the name and tag the shadowed one, exactly as they do today, just with the roles swapped. Subagents follow the same resolution as the main agent.

Alternative Solutions

• A per-scope form of skillOverrides, e.g. "skillOverrides": { "commit": { "personal": "off" } }, so a project could hide the personal copy of a specific name without touching the project copy. Narrower, but it would close this gap without a new top-level setting.
• What we do today: the personal skill's first mandatory step is cat <repo-root>/.claude/skills/<name>/SKILL.md, and if that file exists the personal skill instructs Claude to follow the project file wholesale and ignore its own text. It works, but it costs one extra tool call per invocation, relies on the model honouring a prose redirect, has to be maintained in every personal skill that might collide, and only helps a developer who knows to add it; a teammate without the redirect silently runs their own copy.
• Distinct names per project (aerotech-commit). Defeats the point: the project's CLAUDE.md, docs and habits refer to the plain name, and a developer who works in several repos then needs a different name for the same action in each.

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

A two-person team keeps its repo's workflow skills in <repo>/.claude/skills/: commit (repo-specific staged-diff gate, [module] prefixes, release-note duty), merge, squash, and a self skill that governs how the repo's own CLAUDE.md and decision log are edited. The same developer keeps generic commit, merge, squash and self skills in ~/.claude/skills/ for every other project. Inside the repo, /commit and the model's own Skill(commit) calls run the personal version and skip the repo's gates unless the personal copy carries the cat redirect described above. With "skillPrecedence": "project-first" in the repo's .claude/settings.json, every contributor gets the repo's skill inside the repo and their own skill everywhere else, with no redirect and no renaming.

Additional Context

• #20309 (closed 2026-08-19, "documented behaviour"; the closing comment invites this feature request), #22208 (the same request, auto-closed as a duplicate of #20309 on 2026-02-04), #10061 (the subagent variant, closed for inactivity).
• Observed on the current release (skills listed with user / project tags, /name runs the personal one), matching the maintainer's 2.1.235 check in #20309.
• The docs' rationale for personal-over-project is that a personal workflow should not be silently shadowed; with a default of "personal-first" that stays true for everyone who does not opt in, and a repo that opts in is making the shadowing explicit and visible in its committed settings.