Invocation Control

When Claude should not decide

By default, both you and Claude can invoke any skill. You type /deploy and the deploy procedure runs. Claude reads a message about your code looking ready and decides to run /deploy on its own.

The second behavior is a problem for skills with side effects. You do not want Claude autonomously deciding to push to production because your implementation looks complete. Some skills must only run when a human explicitly asks for them.

Two frontmatter fields give you precise control over who can invoke a skill and when.

disable-model-invocation: user-triggered only

Adding disable-model-invocation: true to a skill's frontmatter does two things: it prevents Claude from invoking the skill automatically, and it removes the skill's description from Claude's context entirely. Claude does not know the skill exists until you type /skill-name.

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
allowed-tools: Bash(git push *) Bash(npm run build *) Bash(npm test *)
---

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

Use disable-model-invocation: true for any skill with external side effects: deploy, commit, release, send-slack-message, create-pr. These are actions where the human must be the one who decides to proceed.

user-invocable: false — Claude-only background knowledge

The opposite case: a skill that contains reference information Claude should use automatically, but that does not make sense as a slash command. A legacy-system-context skill that explains how an old API works should load when Claude is working with legacy code — but /legacy-system-context is not a meaningful action for a human to type.

---
name: legacy-system-context
description: Context about the legacy payment API. Use when working with code in /src/legacy/ or any file that imports from legacy-payments.
user-invocable: false
---

The legacy payment API (pre-2023) uses a SOAP-based interface at /src/legacy/.
Key quirks:
- All amounts are in cents, not dollars
- The session token expires after 15 minutes
- Error codes are in the response body, not HTTP status

With user-invocable: false, the skill description stays in Claude's context so it knows when to load it, but the skill does not appear in the / autocomplete menu.

The three-state invocation table

Overriding visibility from settings

Sometimes you want to change a skill's visibility without editing its SKILL.md — especially for skills checked into a shared repository that you do not own. The skillOverrides setting in .claude/settings.local.json (or your user settings) controls this:

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

The four states control what Claude and the / menu see:

The easiest way to set these without editing JSON is the /skills menu in Claude Code: highlight a skill, press Space to cycle through states, press Enter to save to settings.local.json.

The description budget

Claude Code loads all skill descriptions into context so Claude knows what is available. The budget scales at approximately 1% of the model's context window. If you have many skills, some descriptions may be shortened or dropped — the skills you invoke least frequently are pruned first.

Run /doctor to see how many descriptions are being shortened or dropped. To free budget, set low-priority entries to "name-only" in skillOverrides so they list without a description. Each skill's combined description and when_to_use text is capped at 1,536 characters regardless of budget — put the most important trigger information first.