[DOCS] Settings reference missing `skillOverrides` setting and its `off` / `user-invocable-only` / `name-only` modes

[coygeek]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

settings.json available settings reference for skill visibility and invocation control

Current Documentation

No documentation currently exists for the skillOverrides setting in the settings reference.

The current docs only describe per-skill frontmatter controls:

By default, Claude can invoke any skill that doesn't have disable-model-invocation: true set.

Hide individual skills by adding disable-model-invocation: true to their frontmatter. This removes the skill from Claude's context entirely.

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

The user-invocable field only controls menu visibility, not Skill tool access. Use disable-model-invocation: true to block programmatic invocation.

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

What's Wrong or Missing?

Claude Code v2.1.129 added working skillOverrides behavior with three modes:

A. The setting itself is undocumented

There is no skillOverrides entry in the settings.json reference, so users cannot discover that this setting exists or where it belongs.

B. The supported values and their effects are undocumented

The docs do not explain that:

• off hides a skill from both the model and the / menu
• user-invocable-only hides a skill from the model but keeps it user-invocable
• name-only collapses the description

C. The relationship to existing skill frontmatter is undocumented

The skills page documents disable-model-invocation: true and user-invocable: false, but it does not explain when a user should use skillOverrides instead of changing each skill's frontmatter.

Suggested Improvement

Add a skillOverrides entry to the settings reference with a concrete JSON example and value semantics.

Suggested addition:

{
"skillOverrides": {
"deploy": "user-invocable-only",
"legacy-system-context": "off",
"big-reference": "name-only"
}
}

Document each mode explicitly:

• off: hide the skill from the model and from /
• user-invocable-only: hide the skill from the model but keep it available via /
• name-only: keep the skill visible but collapse its description

Also add one short cross-reference from the skills page explaining that global settings can override discovery/visibility without editing each skill's SKILL.md.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Page	Context
https://code.claude.com/docs/en/settings	Missing skillOverrides setting from the settings.json reference
https://code.claude.com/docs/en/skills	Documents per-skill frontmatter controls, but not the settings-level override behavior

Total scope: 2 pages affected

Observed against changelog entry for v2.1.129.

[coygeek]

Issue #56494 Verification

Title: [DOCS] Settings reference missing skillOverrides setting and its off / user-invocable-only / name-only modes
Issue Date: 2026-05-06
Verification Date: 2026-05-09
Status: RESOLVED

---

Issue Summary

This issue reports that the documentation did not describe the skillOverrides setting in the settings reference, did not explain the supported override modes and their effects, and did not explain when settings-level overrides should be used instead of per-skill frontmatter.

---

Verification Results

Claim 1: The settings reference is missing a skillOverrides entry

Status: RESOLVED

At https://code.claude.com/docs/en/settings, line 225, the settings reference now includes a skillOverrides row: Per-skill visibility overrides keyed by skill name. Value is "on", "name-only", "user-invocable-only", or "off". Lets you hide or collapse a skill without editing its SKILL.md. The same row also includes an example value: {"legacy-context": "name-only", "deploy": "off"}.

Verdict: The missing settings-reference entry has been added.

---

Claim 2: The docs do not explain the supported skillOverrides values and their effects

Status: RESOLVED

At https://code.claude.com/docs/en/skills, lines 506-515, the current docs state that skillOverrides controls skill visibility from settings and include a table for all four states: "on", "name-only", "user-invocable-only", and "off", along with whether each state is listed to Claude and shown in the / menu. At the same page, lines 517-525, the docs add a JSON example under "skillOverrides".

Verdict: The current docs explicitly document the available modes and their behavior.

---

Claim 3: The docs do not explain the relationship between skillOverrides and skill frontmatter

Status: RESOLVED

At https://code.claude.com/docs/en/skills, lines 498-501, the page still documents the frontmatter controls disable-model-invocation: true and user-invocable. Immediately after that, lines 504-506 explain the settings-level alternative: The skillOverrides setting controls skill visibility from your settings instead of the skill's own frontmatter. Use it for skills whose SKILL.md you don't want to edit, such as ones checked into a shared project repo or provided by an MCP server.

Verdict: The current skills documentation now explains when settings-level overrides are appropriate instead of editing per-skill frontmatter.

---

Current State

Claim	Status
Settings reference missing skillOverrides	RESOLVED
Override modes and effects undocumented	RESOLVED
Relationship to frontmatter undocumented	RESOLVED

---

Suggested Fix

N/A - issue has been resolved.

---

References

• URL: https://code.claude.com/docs/en/settings

• Lines 225-225: The settings reference includes skillOverrides, lists the supported values, describes its purpose, and shows an example value.

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

• Lines 498-506: The page explains the frontmatter controls and then states that skillOverrides controls visibility from settings instead of the skill's own frontmatter.

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

• Lines 506-525: The page documents all four skillOverrides states and includes a JSON example.

---

Conclusion & Recommendation

Primary Concern: The issue reported that users could not find or understand the skillOverrides setting and its interaction with skill visibility controls.

Resolution Status: RESOLVED

Recommendation: CLOSE

The current docs now cover the missing settings entry, the supported override modes, and the settings-versus-frontmatter distinction that the issue reported as missing. The reported documentation gap is no longer present in the current mirror.

---

[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.