[DOCS] 03-skills: skill precedence order inverted and skillOverrides documented as a non-existent feature

Type of Issue

• Incorrect content
• Outdated content

Location

• File: 03-skills/README.md
• Sections: "Skill Types & Locations" (line 96) and "Controlling Skill Override Behavior (skillOverrides)" (lines 671-690)
• Mirrors: vi/03-skills/README.md:95, ja/03-skills/README.md:99, uk/03-skills/README.md:99, CHANGELOG.md:46-48

Issue Description

Two related errors, both introduced by b9a973b (#155, "accuracy pass against v2.1.220").

1. Skill precedence order is inverted (line 96)

Current content:

When skills share the same name across levels, higher-priority locations win: enterprise > project > personal. Project skills override personal ones by default; the skillOverrides setting (v2.1.129+) tunes that behavior

The current skills docs say the opposite, with a worked example:

Across levels, enterprise overrides personal, and personal overrides project. For example, with a deploy skill in both ~/.claude/skills/ and your project's .claude/skills/, /deploy runs the personal one.

Correct order: enterprise > personal > project.

This is a regression, not drift. Before #155 the line read enterprise > personal > project — the docs-correct value. #155 found a genuine internal contradiction in the file and resolved it in the wrong direction, keeping the fabricated claim and discarding the accurate one. CHANGELOG.md:46-48 records the change as intentional.

2. skillOverrides is documented as a feature that does not exist (lines 671-690)

The README describes skillOverrides as a bare string that tunes project-vs-personal override precedence, with this behavior table:

None of that is real. Per the docs and confirmed against the v2.1.235 binary, skillOverrides is an object keyed by skill name whose values are visibility states:

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

It controls whether a skill is advertised, not which copy wins a name collision. Plugin skills are unaffected by it.

Suggested Improvement

1. Revert line 96 to enterprise > personal > project and drop the skillOverrides cross-reference from that sentence.
2. Rewrite the skillOverrides section as a visibility control: correct object shape, the four-state visibility table above, and a note that plugin skills are managed via /plugin instead. Retitle it (e.g. "Controlling Skill Visibility") so it no longer advertises override tuning.
3. Mirror both fixes to vi/, ja/, and uk/.
4. Add a CHANGELOG.md entry recording the correction and superseding the #155 note at lines 46-48.

Why This Matters

Precedence is load-bearing: a reader who follows the current README will put a skill in .claude/skills/ expecting it to beat their personal copy, and get the personal one instead. The skillOverrides section is worse — it tells readers to write a config value with the wrong shape for a purpose the setting does not serve.

It also has downstream reach. #169 was filed against .claude/skills/lesson-quiz/references/question-bank.md on the strength of this README, and PR #170 would have propagated the error into the quiz bank (which was correct all along). PR #170 is being closed for that reason.

Finally, the regression survived the v2.1.233 (#168) and v2.1.235 (#174) sync passes without being caught — worth a look at whether the docs-sync check compares prose claims against the source docs, or only checks links and structure.

Related Documentation

• https://code.claude.com/docs/en/skills
• Related Guide: 03-skills/README.md#skill-types--locations
• Regression source: b9a973b (#155)
• Blocked PR: #170 · Misfiled issue: #169