Skip to main content
Comparison8 min read·Updated July 27, 2026
🧩

Slash Commands vs Agent Skills: What Changed in 2026

B

A. Frans

Published July 27, 2026

Agent SkillsClaude CodeSlash CommandsDeveloper ToolsAutomation

Custom slash commands and Agent Skills are the same feature now. Claude Code's documentation states it plainly: a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy, and both work the same way.

Your existing commands folder keeps working. Nothing breaks. But if you're still writing new automation as command files, you're opting out of four capabilities for no reason, and one of them changes what you can build.

Here's what merged, what didn't, and when converting is worth the ten minutes.

The comparison

.claude/commands/name.md.claude/skills/name/SKILL.md
Creates /nameYesYes
Claude can invoke it automaticallyNoYes, unless you disable it
Supporting files alongside itNoYes, whole directory
Frontmatter controlsLimitedFull set, listed below
Runs in its own subagentNoYes, with context: fork
Pre-approve tools for the turnNoYes, with allowed-tools
Precedence when names collideLosesWins
That last row is worth reading twice. If you have both a command and a skill named deploy, the skill takes precedence. Silently. This is the one migration hazard in the whole change, and it bites teams who converted half their commands and left the originals in place.

What you gain

Claude can decide to use it

A command file only runs when you type the slash. A skill's description gets loaded into context at session start, so Claude knows the skill exists and can pull it in when the work matches.

That flips the model from "I remember there's a command for this" to "the agent already knew." For anything procedural that you'd want applied consistently, like a code review checklist or a commit convention, that's the whole value.

If you don't want it, one line of frontmatter turns it off:

disable-model-invocation: true

Use that for anything with side effects. Claude Code's own docs give the examples: /commit, /deploy, /send-slack-message. You don't want the model deciding your branch looks ready to ship.

Worth knowing: setting that flag also keeps the description out of context entirely. The full skill loads only when you invoke it. So a directory full of manual-only skills costs you almost nothing in tokens, which is not true of a CLAUDE.md that has grown into a procedure.

A directory instead of a single file

Command files are one markdown file. Skills are a folder, which means the skill can ship with the script it tells Claude to run, a reference document, a template, a schema.

Claude Code substitutes ${CLAUDE_SKILL_DIR} in both the skill body and its Bash permission rules, so a skill can invoke a bundled script without prompting you every time. That substitution inside allowed-tools needs Claude Code v2.1.129 or later. On earlier versions the rule stays a literal string and never matches, so you get the permission prompt anyway and spend an afternoon wondering why.

Tool permissions scoped to the turn

The allowed-tools frontmatter grants specific tools without per-use approval, for the turn that invokes the skill:

allowed-tools: Bash(git add ) Bash(git commit ) Bash(git status *)

The grant clears when you send your next message. It doesn't restrict anything, it only pre-approves. If you want the opposite, disallowed-tools removes tools from the pool while the skill is active, which is the right tool for autonomous loops that should never ask a question.

One security note that deserves more attention than it gets: for skills checked into a project's .claude/skills/, allowed-tools takes effect after you accept the workspace trust dialog. A skill in a repository you clone can grant itself broad tool access. Review project skills before trusting a repo, the same way you'd review a package.json script.

Running in a subagent

This is the capability with no command-file equivalent at all. Add context: fork and the skill runs in an isolated subagent, with the skill content as its prompt. It doesn't see your conversation history.

By default the fork runs in the background and its result arrives when it finishes, so you keep working. Set background: false to wait for the result in the same turn. Before v2.1.218, forked skills always blocked the turn.

The agent field picks which subagent type runs it: Explore, Plan, general-purpose, or any custom agent in .claude/agents/. Note that Explore and Plan skip CLAUDE.md and git status to stay small, so a forked skill using Explore sees only the SKILL.md content and the agent's system prompt.

One trap the docs call out directly: context: fork only makes sense for skills with explicit instructions. A skill that's a set of guidelines with no task hands the subagent context but nothing to do, and it returns with nothing useful.

Where skills live and which one wins

LevelPathApplies to
Personal~/.claude/skills/name/SKILL.mdAll your projects
Project.claude/skills/name/SKILL.mdThat project
Enterprise sits above both. Precedence runs enterprise, then personal, then project. A skill at any of these levels overrides a bundled one with the same name, so a code-review skill in your project replaces the built-in /code-review. Plugin skills are namespaced as plugin-name:skill-name and can't collide with anything.

Skills also load from nested .claude/skills/ directories below your working directory, discovered when Claude reads or edits a file down there. In a monorepo, a package can carry its own skills that only surface when you're working in it. When a nested skill's name clashes, both stay available and the nested one gets a path-prefixed name like /apps/web:deploy.

Edits are picked up live. Adding, changing or removing a skill under a watched directory takes effect in the current session. Creating a top-level skills directory that didn't exist when the session started needs a restart, because there was nothing to watch.

The one that catches everyone

Skills stack. You can type several slash commands in a row and Claude Code expands the first plus up to five more.

Expansion stops at the first token that isn't an inline user-invocable skill. A skill that forks into a subagent ends the run there, and so does one whose arguments might themselves start with a slash. Everything after that token becomes argument text for every skill that did expand.

In practice: stacking two or three quick procedural skills works fine. Putting /code-review in the middle of a stack does not do what you expect.

When to convert, and when not to

Convert if the command needs supporting files, if you want Claude to reach for it on its own, if it should run isolated in a subagent, or if it needs pre-approved tools to avoid a permission prompt every single time.

Don't convert a working three-line command file that you invoke by hand and that needs nothing else. There's no penalty for leaving it. The merge was designed so you don't have to migrate.

If you do convert, delete the old command file. Don't leave both.

The conversion itself:

  • mkdir -p .claude/skills/deploy
  • git mv .claude/commands/deploy.md .claude/skills/deploy/SKILL.md

Then add frontmatter with a name and a description. The description is what Claude reads to decide whether the skill is relevant, so write it for that job rather than as a title. A vague description is the most common reason a skill never triggers, which we covered in why your skill isn't triggering.

Two things that don't transfer

Cowork sessions and cloud sessions, including scheduled routines, don't read ~/.claude/skills/ from your machine. They load the skills enabled for your claude.ai account, synced at session start. Cloud sessions additionally load project skills committed to the cloned repository.

So a personal skill that works locally will come back as "not found" when a routine tries to invoke it. Either enable it on your account, or commit it to the repository's .claude/skills/.

The second one: as of v2.1.196, disable-model-invocation: true also stops a skill from running when a scheduled task fires with that skill as its prompt. That's correct behavior, and it's also a good way to break your own automation if you set the flag without thinking about where the skill gets called from.

Where this fits

Skills follow the agentskills.io open standard, so the same SKILL.md works across multiple AI tools. Claude Code extends it with invocation control, subagent execution and dynamic context injection, which are the features this article is mostly about.

If you're deciding between a skill, an MCP server and a plugin, that's a different question with a different answer, and our breakdown of the three covers it. For distributing what you build, see sharing skills with your team and how plugin marketplaces work. If you're starting from scratch, our build guide walks through the structure, and Skill Creator from Anthropic scaffolds one for you.

FAQ

Do I have to migrate my .claude/commands/ files? No. They keep working and create the same slash commands. Migrate individual ones when you want a capability that only skills have.

What happens if I have both a command and a skill with the same name? The skill wins. This is silent, so remove the command file when you convert rather than leaving it as a backup.

Can a skill run without me typing anything? Yes. Descriptions load into context and Claude invokes a skill when the work matches, unless you set disable-model-invocation: true.

Does a skill's content stay in context after it runs? Yes. The rendered SKILL.md enters the conversation as a single message and stays there for the session, and Claude Code doesn't re-read the file on later turns. Write guidance that should apply throughout a task as standing instructions, not as one-time steps. Permissions behave differently: an allowed-tools grant clears on your next message.

Are the built-in commands skills too? Some are reachable through the Skill tool, including /init, /review and /security-review. Others like /compact are not.

Is there a token cost to having a lot of skills installed? Descriptions load at session start, so yes, a small one per skill. Skills with disable-model-invocation: true don't load their description at all, so manual-only skills are close to free until you invoke them.

Share this article

📬

Get More AI Tool Guides

New comparisons and guides every week. Join thousands of professionals staying ahead of the AI curve.