BLOG

disable-model-invocation: stop Claude Code from running a skill on its own

4 min read • October 2026
On this page
  1. The short answer
  2. Three ways a skill can be invoked
  3. When to use it
  4. It also frees up the skill listing
  5. Setting it without editing SKILL.md
  6. Older versions behaved differently
  7. In other agents
  8. Is the skill still being used?
  9. Sources

Some skills should never run because Claude decided it was a good moment. A deploy, a commit, a message to your team. For those, Claude Code has one frontmatter field: disable-model-invocation.

The short answer

Add disable-model-invocation: true to the skill's frontmatter. After that, only you can run the skill, by typing /skill-name. Claude cannot invoke it on its own.

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

The skill keeps working as a slash command. It just stops being something Claude can pick by itself.

Three ways a skill can be invoked

Two fields control who can start a skill. Together with the default, that gives three modes:

Frontmatter You can run it Claude can run it Description in Claude's context
(default) Yes Yes Yes, every session
disable-model-invocation: true Yes No No
user-invocable: false No Yes Yes, every session

user-invocable: false is the opposite case: background knowledge that Claude should use when relevant, but that makes no sense as a command you would type. The two fields solve different problems, so it is rare to need both.

When to use it

Use it for any skill where the timing matters more than the content:

  • Side effects outside your machine. Deploys, releases, publishing, sending email or Slack messages.
  • Changes you want to review first. Commits, migrations, bulk file rewrites.
  • Workflows you start on purpose. A weekly report, a release checklist, a long research pass you only want when you ask.

If Claude tries to invoke such a skill anyway, Claude Code blocks the call. In our test on Claude Code 2.1.278, Claude found the matching skill, did not run it, did not copy its steps by hand, and told us to type the slash command ourselves.

It also frees up the skill listing

At the start of every session, Claude sees a listing of installed skills: names and descriptions. That listing has a limited budget, and each description is capped at 1,536 characters (see skill description limits).

A skill with disable-model-invocation: true is left out of that listing. Claude does not need its description, because Claude will never choose it. The skill loads only when you run it. With many skills installed, moving the manual ones out leaves more room for the descriptions of the skills Claude is supposed to pick on its own.

Setting it without editing SKILL.md

You do not have to touch the skill file. Claude Code reads a skillOverrides key in your settings:

{
  "skillOverrides": {
    "deploy": "user-invocable-only"
  }
}

"user-invocable-only" works like disable-model-invocation: true. You can also set it from the /skills menu: highlight a skill, press Space to cycle its state, then Esc to save. This is useful for skills that come from a plugin or a shared repository, where your edits to SKILL.md would be overwritten on the next update.

For a hard block, a permission rule also works. Add Skill(deploy *) to your deny rules and Claude cannot use the skill at all.

Older versions behaved differently

Two bug reports show up in search results for this flag. In one, the flag hid the skill entirely, so even /skill-name did not work. In the other, from version 2.1.71, the skill's description still loaded into context. Both were closed as duplicates.

On Claude Code 2.1.278 we saw neither: the description was absent from the listing, Claude could not invoke the skill, and /skill-name ran it as expected. If you see either problem, check your version with claude --version and update.

In other agents

disable-model-invocation is a Claude Code field. It is not part of the Agent Skills specification, which defines only name, description, license, compatibility, metadata and allowed-tools. If you share a skill folder with another agent, check that agent's documentation: one that does not know the field may simply ignore it and treat the skill as one it can pick on its own.

Is the skill still being used?

A skill you only run by hand is easy to forget. SkillKeeper counts every run of every skill, both the ones Claude picks and the ones you start with /skill-name, so you can see whether a manual-only skill still earns its place. If it does not, you can pause it from the menu bar without deleting it.

If a skill you expected Claude to use never fires, disable-model-invocation is one of the first things to check. The rest is in why a Claude Code skill never triggers.

Sources

About SkillKeeper
← All posts