How Do I Delete or Disable an Agent Skill?

Why There's No Universal Off Switch for Agent Skills

Here's the thing about agent skills: they aren't apps you install, so there's no Settings menu with an uninstall button. A skill is just a folder containing a SKILL.md file — YAML frontmatter plus Markdown instructions — which means "deleting" it is really a file operation, and "disabling" it depends entirely on which agent platform you happen to be using.

That architecture explains why removal looks so different from tool to tool. On the Claude Skills API, custom skills have an explicit delete operation, and deleting a skill also removes all of its versions; Anthropic's pre-built skills have no documented delete or disable mechanism at all. Everywhere else, you delete the folder itself, and skills can live in several places at once — project directories like .claude/skills/ or .agents/skills/, and personal ones like ~/.copilot/skills/ — so a skill you removed in one location may still be sitting in another, as the VS Code agent skills documentation makes clear.

Disabling is messier still, because the flags aren't portable:

• Claude Code and Copilot read frontmatter flags such as `disable-model-invocation: true` and `user-invocable: false` to block auto-loading or hide a skill from the slash menu.
• OpenAI Codex ignores frontmatter entirely for this purpose and uses `agents/openai.yaml` with `policy.allow_implicit_invocation: false` instead.
• Gemini CLI parses only `name` and `description` and silently discards every other frontmatter field, so a skill you disabled can quietly become model-invocable again.

That last point is the one that should worry anyone managing agents at work. A skill you believe is switched off can still fire on a different agent, and there's no warning when it does. Skills can even disable themselves by accident: install too many and the agent silently truncates skill descriptions, dropping the least-invoked ones first until they stop triggering altogether. With community libraries now running to thousands of entries, "which skills is this agent actually seeing?" becomes a genuine governance question — and it's exactly the gap SkillzBench is building to close, with a free verified skills directory and a free MCP connector that gives each agent its own loadout, so the agent only sees the skills you chose.

Delete vs. Disable: Two Mechanisms, Three Platforms

There is no universal "off switch" for agent skills — how you remove or silence one depends entirely on where it lives and which platform is loading it. The good news: because skills are just folders containing a SKILL.md file rather than executable code, the mechanics are simpler than they first appear.

Deleting is a file operation. Skills live in well-known directories, so removing the folder removes the skill. According to the VS Code agent skills documentation, you should check both project locations (.claude/skills/, .github/skills/, .agents/skills/) and personal ones (~/.claude/skills/, ~/.copilot/skills/, ~/.agents/skills/) — a same-named skill can linger in more than one place. On the Claude Skills API, deletion is explicit but unforgiving: as the official skills guide notes, deleting a skill "also removes all of its versions," and only custom skills can be deleted — Anthropic's pre-built skills like pptx and xlsx have no documented removal mechanism.

Disabling is done with frontmatter flags. Two flags do most of the work:

• disable-model-invocation: true — stops the agent from auto-loading the skill; it stays available only via an explicit `/skill-name` invocation, which practitioners recommend for dangerous operations or interactive workflows.
• user-invocable: false — hides a skill from the slash-command menu while still allowing automatic loading (supported in VS Code Copilot since the January 2026 GA release).
• On the Claude API, "disabling" is implicit: skills load only when listed in the `container.skills` parameter, so simply omit one to keep it out.

The portability caveat matters more than most guides admit. As one spec-aware technical analysis explains, disable-model-invocation is not part of the agentskills.io spec: Gemini CLI parses only name and description, silently discarding the flag, so a skill you "disabled" can auto-run again. OpenAI Codex replaces the flag entirely with an agents/openai.yaml file using policy.allow_implicit_invocation: false — explicit $skill invocation still works either way.

So when does disabling beat deleting? When you might want the skill back, or when a skill handles risky operations that should require explicit user control. Deleting wins when a skill is dead weight: Claude Code's /doctor command reports unused skills against their context cost, and over-installing can silently truncate skill listings — Claude Code caps the listing at 1% of the context window with entries limited to 1,536 characters — causing least-invoked skills to stop triggering on their own.

Because per-skill flags are this fragile across platforms, the most reliable control is curating what each agent sees in the first place. That is the approach SkillzBench is building: a free directory of verified, security-scanned skills plus a free MCP connector with per-agent loadouts, where an agent only ever sees the skills you explicitly choose.

Skills That Go Quiet: Context Pressure and Silent Disablement

There's a third way a skill disappears — and it doesn't involve deleting anything. Install enough skills, and the ones you invoke least can quietly stop triggering, leaving you wondering why your agent "forgot" something it handled perfectly last month.

The cause is a context budget problem. Every installed skill advertises itself to the agent with a name and description, and that listing eats into a fixed slice of the context window. According to a spec-aware analysis of the SKILL.md format, Claude Code sizes this listing at just 1% of the context window (tunable via skillListingBudgetFraction), capping each entry at 1,536 characters, while OpenAI Codex allows a maximum of 2% of the context window or 8,000 characters when the window size is unknown. Those budgets sound generous until you realize a directory with thousands of community entries exists — and your agent can only advertise a fraction of what you've installed.

When the budget runs out, the system doesn't error or warn. It silently truncates descriptions, dropping the least-invoked skills first. The skill's folder is still on disk, its SKILL.md is intact, and nothing was deleted — but the agent never sees its listing, so it can never invoke it. This is de facto disablement, and it's why "my skill stopped working" is usually a diagnosis question, not a deletion question.

If a skill has gone quiet, check the usual suspects before adding more:

• Too many installed skills competing for the same 1–2% listing budget, pushing yours out of the advertised set.
• A description that got truncated below the point where the agent can match it to your request.
• A skill that was never actually invoked much, making it the first casualty of budget pressure.
• Leftover copies of the same skill in multiple locations — project folders like `.claude/skills/` and personal folders like `~/.claude/skills/` can both hold entries.

Claude Code ships a diagnostic purpose-built for this. The /doctor command reports unused skills, MCP servers, and plugins compared with their context cost, which makes it easy to spot skills that are quietly consuming budget without earning their keep. Microsoft's Agent Framework docs quantify the per-skill overhead: the "advertise" stage costs roughly 100 tokens per skill, so every extra install is a small, permanent tax on every conversation.

The deeper lesson is that controlling skills through per-skill flags and local file surgery is fragile — platforms disagree on which flags they honor, and budget pressure can disable skills without any flag at all. Curating the skill set at the source is the more reliable model. That's the approach SkillzBench is building: a free, verified directory of agent skills plus a free MCP connector with per-agent loadouts, where you toggle exactly which skills each agent sees — so nothing goes quiet behind your back. Join the waitlist to be first in line when it launches.

The More Reliable Fix: Control What Each Agent Sees

Per-skill flags were never designed to be a security boundary — and the platforms quietly agree, each implementing their own version of "off." The deeper you dig, the more obvious it becomes that the durable fix isn't toggling individual skills after the fact. It's curating what each agent can see in the first place.

The problem is structural. The disable-model-invocation flag that Claude users rely on isn't part of the agentskills.io spec at all — spec-aware analysis shows Gemini CLI parses only name and description and silently discards everything else, while Codex requires an entirely separate mechanism (agents/openai.yaml with policy.allow_implicit_invocation: false). A skill you believe is disabled on one agent may auto-run on another.

The stakes are higher than convenience. Anthropic's own guidance recommends restricting auto-invocation for "dangerous operations, configuration commands, or interactive workflows," according to a detailed practitioner deep dive. If the disable flag can be silently ignored, that recommendation is unenforceable at the file level.

There's a quieter failure mode, too. Over-installing skills creates context pressure: Claude Code caps the skill listing at 1% of the context window with entries capped at 1,536 characters, and least-invoked skills get truncated first — meaning a skill can effectively disable itself without you ever knowing. Meanwhile, the Claude API takes the opposite approach entirely: skills are active only when explicitly listed in container.skills, so omission is the disable mechanism.

That last model — explicit inclusion rather than after-the-fact exclusion — is the one that actually scales. Instead of chasing per-skill flags across every platform, you control the source:

• Decide exactly which skills each agent loads, before it loads anything
• Verify skills once (security scan, license check, version pinning) rather than trusting every agent to handle them safely
• Change a loadout in one place instead of editing frontmatter in five different tools
• Keep risky skills out of auto-invocation paths entirely, not just flagged off

This is the approach SkillzBench is being built around. It's a free, independent directory of agent skills — every version pinned to a commit SHA, security-scanned, license-checked, and benchmarked in a sandbox — paired with a free MCP connector that gives each agent its own loadout. You toggle which skills and tools an agent gets, and the agent simply never sees the rest. No silent flags, no cross-platform surprises.

Everything on SkillzBench will be free: the directory, the MCP connector, the benchmarks, and the alerts. The platform is pre-launch, but the waitlist is open now.

Join the waitlist at skillzbench.com to be first in line when verified, benchmarked skills with per-agent loadouts go live. Skills, proven.