[DOCS] disable-model-invocation and AGENT frontmatter skills, interaction

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/sub-agents#preload-skills-into-subagents

Section/Topic

Agent & Skills

Current Documentation

The docs currently say:

Use the skills field to inject skill content into a subagent’s context at startup. This gives the subagent domain knowledge without requiring it to discover and load skills during execution.

[...example...]

The full content of each skill is injected into the subagent’s context, not just made available for invocation. Subagents don’t inherit skills from the parent conversation; you must list them explicitly.

Emphasis on The full content of each skill is injected

Combined with the documentation and naming of disable-model-invocation

What's Wrong or Missing?

This lead me to believe that a skill could be configured as disable-model-invocation: true to stop agents from having access to the "description" and execution of a Skill, but still be able to load the skills in agents of my choosing.

For now I am assuming this is a documentation issue, but maybe its a bug or maybe this could be another flag (to allow such a skill to exists).

This raises another question as to what does a skill with both disable-model-invocation: true and user-invocable: false mean? Is this "a disabled skill"? or should this be allowed and loadable in special agents with frontmatter skills?

Suggested Improvement

In Skill docs:
be explicit that disable-model-invocation: true doesn't only disable invocation but also disables the loading of said skill in the context of agents.

In Agent docs:
be explicit that skills will NOT load any skill with disable-model-invocation: true

Impact

Medium - Makes feature difficult to understand

Additional Context

To debug/test the above I've ran some experiments mainly with this setup:

_toggle the true, to false_ and see the agent pick up pirate speak

---
name: secret-speak
description: talk in a special secret way
disable-model-invocation: true
---

Only talk like a pirate, use popular phrases like "Yarr", "Shiver me timbers", be funny.

---
name: secret-greeter
description: A friendly greeter agent that follows all loaded skill instructions precisely.
skills:
  - secret-speak
---

You are a friendly greeter. Follow ALL loaded skill instructions exactly. Greet the user when asked.