Claude Code commands vs skills
Claude Code has merged custom slash commands into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy, and they work the same way. Your old command files keep working. For anything new, the Claude Code docs say to write a skill, since it works the same way as a command and adds more on top.
What does a skill add over a command?
Three things differ. A skill is a folder, so it can hold scripts and reference files next to SKILL.md. Its frontmatter sets who runs it. And Claude can load a skill on its own when your task matches the description, without you typing the slash.
| Command file | Skill | |
|---|---|---|
| Where it lives | .claude/commands/name.md | .claude/skills/name/SKILL.md |
| Makes /name | Yes | Yes |
| Can hold extra files | No | Yes |
| Claude can run it on its own | No | Yes, unless you turn that off |
How do I turn a command into a skill?
Make a folder inside .claude/skills/ with the command's name, then move the old file into that folder and rename it SKILL.md.
.claude/commands/deploy.md becomes .claude/skills/deploy/SKILL.md
Then add a description at the top, because Claude reads that line to decide when the skill fits a task you give it. For a personal skill that works in every project, use ~/.claude/skills/ instead.
Can I stop Claude from running a skill by itself?
You can. Set disable-model-invocation: true in the frontmatter, and the skill only runs when you type its slash command. That suits a deploy step. To go the other way, user-invocable: false hides the skill from you and leaves it for Claude to use.
Do skills take arguments like commands did?
They do. Type the arguments after the slash command. Inside SKILL.md, $ARGUMENTS stands for everything you typed after the command name, and $0 stands for the first argument on its own.
What about built-in commands?
Built-in commands such as /help and /compact are part of Claude Code itself. A few, like /debug and /code-review, are bundled skills. The Claude Code commands reference lists them all.
FAQ
Will my old .claude/commands files stop working?
They will not. The docs say existing command files keep working.
Should I keep long notes in CLAUDE.md or in a skill?
Move a procedure to a skill. Claude Code loads CLAUDE.md in every session, but a skill's body loads only when it is used, so long notes cost almost nothing until then.