[DOCS] Clarify distinction between `user-invocable` and `disable-model-invocation` in Skills documentation

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://code.claude.com/docs/en/skills#control-skill-visibility - https://code.claude.com/docs/en/slash-commands#skill-tool - https://code.claude.com/docs/en/skills#available-metadata-fields

Section/Topic

The metadata field descriptions for SKILL.md and the visibility control logic for Agent Skills.

Current Documentation

On the Skills page, the metadata table for user-invocable says:

"Controls whether the Skill appears in the slash command menu. Does not affect the Skill tool or automatic discovery. Defaults to true."

The Control Skill visibility section on the same page notes:

"To block programmatic invocation via the Skill tool, use disable-model-invocation: true instead."

The Slash Commands page under the Skill tool section says:

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

What's Wrong or Missing?

While the information is technically present, the logic is split across different pages and sections, making it easy to miss for a developer looking for a "security" or "privacy" toggle for a skill.

A developer might intuitively assume that setting user-invocable: false effectively "hides" the tool from usage entirely. However, if the model can still "see" it via the Skill tool or automatic discovery, the skill remains active in the context. This creates a potential "shadow tool" scenario where a user doesn't see a command in their / menu, but Claude may still execute the underlying logic autonomously.

Suggested Improvement

Add a clear Warning or Note block within the "Available metadata fields" table on the Skills page.

Suggested Text for the metadata table:

user-invocable: (Boolean) Controls whether the Skill appears in the user's / slash command menu. Note: This is a UI setting only; it does not prevent Claude from triggering the skill autonomously. To prevent the model from using the skill, you must set disable-model-invocation: true.

Additionally, in the "Control Skill visibility" section, the comparison table should be updated to explicitly state "Active in Context" for both settings to avoid any ambiguity regarding the model's awareness of the skill.

Impact

High - Prevents users from using a feature

Additional Context

• In many other CLI or SDK environments, "invocable" often implies the ability for any actor to call the function. Separating "user-invocable" and "model-invocation" is a unique paradigm in Claude Code that requires a more heavy-handed warning to ensure developers don't inadvertently expose sensitive internal skills to the model's autonomous decision-making.
• Related documentation for context: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview