Claude skills vs slash commands

01 / Comparison

Side by side

Five dimensions, from the Claude Code documentation and the Agent Skills specification.

02 / Skills

When the skill directory earns its keep

Three cases where the folder beats the single file.

1. 01

   The instructions need company

   The specification puts scripts, references, and assets beside SKILL.md and loads them progressively: metadata at startup, the body on activation, resources only when required. A command file has nowhere to put any of it.

2. 02

   It has to leave Claude Code

   Claude Code documents its skills as following the Agent Skills open standard. Outside it only six fields are accepted, and an extra one such as argument-hint fails packaging.

3. 03

   You want the documented path

   The commands reference no longer describes a commands folder. To add your own commands it points at the skills page.

03 / Slash commands

When a command file is still the right shape

Three cases where the flat file is the honest answer.

1. 01

   It exists and it works

   The documentation says existing files in .claude/commands/ keep working and take the same frontmatter minus two fields. Nothing we found sets a migration deadline.

2. 02

   The prompt is the whole artifact

   A short procedure with no script, reference file, or template gains nothing from a directory. The file name is the command.

3. 03

   You did not write it

   Much of the slash menu is not yours to shape: built-in commands, bundled skills, and MCP prompts discovered from connected servers.

04 / Together

The same slash, two files

Not a setup you configure. Both files register the same command, and a documented precedence rule settles it.

.claude/
  commands/
    deploy.md
  skills/
    deploy/
      SKILL.md
      checklist.md

# commands/deploy.md
---
description: Ship the current branch to staging
argument-hint: [environment]
---

Run the staging deploy for $ARGUMENTS and report the release URL.

# skills/deploy/SKILL.md
---
name: deploy
description: How this team ships to staging. Use when someone asks to deploy or release.
disable-model-invocation: true
---

Follow checklist.md, then run the staging deploy for $ARGUMENTS.

# Both files answer to /deploy. The skill wins the name.

If the question underneath is where a file has to sit before it becomes a command, how to install Claude skills in Claude Code walks the personal, project, plugin, and managed paths and how to confirm one actually loaded.

05 / Questions

Frequently asked questions

What is the difference between Claude skills and slash commands?

A slash command is the invocation: what you type to run something. A skill is the unit that runs: a directory with SKILL.md inside. Claude Code documents custom commands as merged into skills, so a file in .claude/commands/ and a skill directory both create the same command and read the same frontmatter fields.

Are Claude Code custom commands deprecated?

The documentation does not use that word. It says existing files in .claude/commands/ keep working and support the same frontmatter except name and paths, which a command file ignores. It recommends skills for the extra features, such as supporting files. No page we checked gives a removal date.

Should I use .claude/commands or .claude/skills?

Use a skill directory for anything that needs scripts, reference files, or templates beside the instructions, and for anything you want to reuse outside Claude Code. Keep a command file when the prompt is the entire artifact and it already works, since the docs set no deadline for converting it.

Can Claude invoke a slash command on its own?

Yes, for the ones loaded from files. A skill description sits in context so Claude can load it when your request matches, and setting disable-model-invocation to true limits it to manual use. Command files read the same field, so the folder you choose does not change this behavior.

Do Claude Code slash commands work in claude.ai or the API?

The slash menu is a Claude Code interface. Custom skills do run on claude.ai and the Claude API, but the documentation says they do not sync across surfaces, and outside Claude Code only the six specification fields are accepted, so an argument-hint field fails packaging.

Sources

Editorial method: every claim about how skills and slash commands behave comes from the first-party documentation below, checked on the date at the top of this page. Where the documentation says nothing, this page says so instead of filling the gap. Product behavior changes, so check the linked pages before you rely on a detail.

• Claude Code: extend Claude with skills

  The statement that custom commands have been merged into skills and that both files create the same command, the frontmatter a command file supports and the two fields it ignores, the command-name table including the file-name and plugin-namespace rules, the conflict list in which a skill beats a same-named command file, the invocation matrix for disable-model-invocation and user-invocable, the argument substitutions and their zero-based indexing, and the six fields accepted outside Claude Code. The /docs/en/slash-commands path serves this same page.

• Claude Code: commands reference

  The framing that most entries are built-in commands whose behavior is coded into the CLI, the Skill and Workflow markers for bundled entries such as /code-review, the note that a command is only recognized at the start of a message, the pointer that says to add your own commands see skills, and the absence of any commands-folder documentation on the page.

• Claude Code: Model Context Protocol

  The /mcp__servername__promptname format for prompts exposed by MCP servers, their dynamic discovery from connected servers, arguments passed space-separated after the command name, and the normalization of server and prompt names.

• Agent Skills specification

  The skill directory with SKILL.md as the required entrypoint, the optional scripts, references, and assets directories, the required name and description fields plus four optional ones, progressive disclosure with metadata loaded at startup and the body on activation, and the absence of any command, invocation, or arguments field in the format.

• Anthropic: Agent Skills overview

  The surfaces custom Skills run on, the statement that custom Skills do not sync across surfaces, and the per-surface sharing model that describes Claude Code skills as filesystem-based and separate from claude.ai and the API.