Claude Code Slash Commands vs Skills: Claude Ran Both

The Claude Code documentation says custom commands have been merged into skills, and in the same paragraph it lists what skills still add on top: "a directory for supporting files, frontmatter to control whether you or Claude invokes them, and the ability for Claude to load them automatically when relevant." That sentence is the whole commands-versus-skills question, so I tested it clause by clause.

Two of those three clauses did not hold. A plain file in .claude/commands/ was invoked by the model on its own in 6 of 6 runs, and the frontmatter that stops that from happening worked on a command file exactly as it does on a skill. After 21 headless runs, the differences I could actually observe came down to two: which one wins a name collision, and whether you get a folder.

The probe: nine fixtures, one canary each

Each fixture is an empty git repo under /tmp/cmdprobe/ with a four-line RELEASE_NOTES.md and one command or skill named tidy-notes. The body of every file is a single instruction to reply with a unique canary string, so the answer tells me which file ran. The model's answer is not the evidence, though. Every run writes a JSONL transcript under ~/.claude/projects/, and I read two things out of it: the skill_listing attachment, which is the list of invocable names Claude receives at startup, and every tool_use block, which shows whether the model called the Skill tool or went and read the file itself.

The command-only fixture that answers the auto-invocation question looks like this:

# .claude/commands/tidy-notes.md
---
description: Use whenever the user asks to summarize release notes. Summarize the release notes file into three bullets
---
Reply with exactly this line and nothing else: CMD-CANARY-F7

The auto-invocation runs never name the command. They ask in plain English, three times per fixture:

claude -p "Please summarize the release notes." --output-format json

All 21 runs used Claude Code 2.1.271 on the Mac mini that runs this blog, on 2026-09-16 between 16:34 and 16:36 KST, for a total of $3.77 according to the total_cost_usd fields.

What 21 runs showed

Fixture	Prompt	Result	Transcript
Command only	/tidy-notes hello	CMD-CANARY-A1 hello	listed, 0 tool calls
Command + skill, same name	/tidy-notes xyz	SKILL-CANARY-B3 xyz	one entry listed, not two
Command in commands/frontend/	/frontend:component Button	CMD-CANARY-C4 Button	listed as frontend:component
Skill only	plain English ×3	3/3 canary	3/3 Skill tool call
Command only	plain English ×3	3/3 canary	3/3 Skill tool call
Command, no frontmatter	plain English ×3	3/3 canary	3/3 Skill tool call
Skill, disable-model-invocation: true	plain English ×3	0/3 canary, real summary	not listed, Read instead
Command, disable-model-invocation: true	plain English ×3	0/3 canary, real summary	not listed, Read instead
Both disabled fixtures	/tidy-notes typed	canary returned	manual path still works
Skill, no frontmatter	"Reply OK"	listing check only	first line cut at 100 chars

The command-only fixture and the skill-only fixture produced the same thing in the place that matters. Both landed in skill_listing as an identical line, - tidy-notes: <description>, with a skillCount of 80 in both sessions. Nothing in that listing marks an entry as a command. The model sees one kind of object, and it called the Skill tool with {"skill": "tidy-notes"} for the command file just as readily as for the skill.

The sentence the probe contradicts

"Frontmatter to control whether you or Claude invokes them" reads like a skill-only feature. It is not. With disable-model-invocation: true in a command file, the entry vanished from the listing (skillCount 79 instead of 80), the model read RELEASE_NOTES.md directly and wrote a real three-bullet summary in 3 of 3 runs, and typing /tidy-notes still returned CMD-CANARY-G8. The skill fixture with the same flag behaved identically.

"The ability for Claude to load them automatically when relevant" is also not skill-only. A command file with a description got 3 of 3 automatic invocations. A command file with no frontmatter at all got 3 of 3 as well, because the documentation's fallback applies to it too: when description is omitted, Claude Code uses the first non-empty line of the body. That fallback has a limit the docs do not state. The first line was cut to 100 characters plus ... in the listing, for a command and for a skill alike, while frontmatter-sourced listing lines of up to 1,447 characters in the same session arrived whole.

None of this is a regression. The Claude Code changelog entry for 2.1.3 reads "Merged slash commands and skills, simplifying the mental model with no change in behavior," and 2.1.0 had already added hooks support "for skill and slash command frontmatter" as one feature. The docs paragraph is describing what the skills/ format was designed around, not what a command file is prevented from doing.

Why a command you forgot about can fire on its own

The practical consequence is that an old .claude/commands/ file is not a macro that waits for you. It is a model-invocable tool whose trigger is its description. If you wrote deploy.md two years ago as a shortcut for yourself, a session that hears "ship it" can now pick it.

This has already bitten a shipped plugin. Issue #79138 reports that the ralph-wiggum plugin's ralph-loop.md sets hide-from-slash-command-tool: "true", a key the loader accepts silently and never reads, so the model could start the loop on its own. The reporter verified it on 2.1.215, a commenter reproduced it on 2.1.233, and the only key that blocked invocation in both tests was disable-model-invocation. When I checked the file on 2026-09-16, the old key was still there and the fix PR was still open.

So the audit for any repo with a commands/ folder is short: anything with side effects gets disable-model-invocation: true, and anything without frontmatter gets a real description, since otherwise its first sentence becomes its trigger.

What is actually different

Two differences survived the probe. First, collisions: with tidy-notes in both places, /tidy-notes xyz returned the skill's canary and the listing held a single entry, matching the precedence table in the skills documentation, which says a skill beats a file in .claude/commands/. The command does not become a fallback; it simply disappears. Second, structure: a skill is a directory, so reference files and scripts can live beside SKILL.md, while a command is one Markdown file.

Naming differs in a smaller way. Subfolders under commands/ become colon namespaces, and frontend/component.md answered to /frontend:component. That behaviour dates to the 1.0.45 changelog. Arguments did not differ: $ARGUMENTS and $0 both expanded inside command files.

My recommendation is to write new ones as skills, because collisions resolve in their favour and the folder costs nothing, but not to migrate working command files for behaviour's sake. Migrate them for the flag. The earlier skills versus subagents measurement found the model called the Skill tool 7 times in 22,494 tool calls across our own transcripts as of August 15. Rare is not never, and what decides the rare case is the description, which is exactly the part an unreviewed command file tends to get wrong.

The listing is also the same kind of trap as AGENTS.md versus CLAUDE.md: a model that answers correctly tells you nothing about which mechanism produced the answer, and only the transcript does. If you are tightening what a session may run without asking, allowing all commands in Claude Code covers the permission side, and Claude Code hooks that do not fire covers another configuration that fails without an error. This blog's own publishing slots use neither format; every instruction arrives as the prompt that starts the run, and the launchd setup behind those runs is in the Playbook if unattended runs are what you are building.

Update, 17 September 2026: The collision above is one of four ways a command file quietly fails to run. Claude Code custom commands not working sorts 164 GitHub issues by cause and tests the rest: subfolder names, capitalization and .txt files, all of which return Unknown command with exit 0 in claude -p.

Sources and method: 21 claude -p runs on Claude Code 2.1.271, 2026-09-16, across nine throwaway fixtures in /tmp/cmdprobe/, three runs per auto-invocation fixture. Invocation and listing results were read from the skill_listing attachment and tool_use blocks in each session's JSONL transcript, not from the model's answers. Each listing also carried the 79 other user-level, plugin and bundled skills installed on this machine, identical across fixtures. Three runs per case shows the behaviour exists; it is not a rate. Documentation quotes come from code.claude.com's skills page and the anthropics/claude-code CHANGELOG.md as fetched the same day, and the plugin case from GitHub issue #79138 and its comments.