Do existing .claude/commands/ files need to be manually rewritten into the Skill directory structure?
No. Official documentation explicitly states that existing .claude/commands/ files continue to work fine and don't break because of the merge — this isn't a forced migration, it's simply that the official recommendation for "new automation" now points to the Skill directory. If a simple single-instruction command you already have works fine and doesn't need extra scripts or reference material, there's no need to rewrite it specifically to keep up with the newer approach.
The more sensible approach is gradual: prioritize the Skill directory for new workflows (especially if you anticipate needing to expand with scripts or reference material down the line), and migrate existing simple command files over only when you genuinely need to expand functionality or happen to be refactoring that part of the logic anyway — no need to migrate purely for migration's sake.
If I want a Skill to be triggerable only by me manually, without Claude judging context and loading it on its own, how do I actually configure that?
Add the disable-model-invocation: true field to that Skill's SKILL.md frontmatter. Once set, this Skill's description won't be included in what Claude checks when judging whether to load something — Claude will never trigger it on its own, and it only runs when you manually type /name. Official documentation specifically calls out this setting as suited to workflows with side effects, or ones where you want to control the timing yourself — things like deployment or sending messages, where you don't want Claude deciding the moment is right and acting on its own.
This field is independent of whether you choose a single-file command or a Skill directory structure — in other words, even if you write a workflow as a full Skill directory (with scripts and reference material), you can still add this field to keep it manual-trigger-only. The choice of triggering method and which file structure you use are completely separate decisions.
Are built-in commands like /simplify and /batch also part of this merge into the Skill system?
They're a related but not identical mechanism. Official documentation categorizes commands like /doctor, /code-review, /batch, /debug, and /loop as "bundled skills" — characterized as "prompt-based," meaning Claude is given a detailed playbook and lets it orchestrate the work using its own tools, which operates on the same underlying principle as a custom Skill you write yourself under .claude/skills/. This is different from built-in commands like /help or /compact, which execute fixed logic directly and don't involve Claude's reasoning at all.
From a user's perspective, there's no difference in how you trigger them — both are typed as / plus a name. The difference is in the underlying mechanism: a bundled Skill has Claude reason through a given playbook and use tools to complete the task, while a purely fixed-logic built-in command directly executes hardcoded program behavior with no model reasoning involved. To turn off all bundled Skills, there's a disableBundledSkills setting, though /doctor stays typable even with that setting on.
When did this system merge happen? Do I need to confirm my Claude Code version actually supports it?
Community write-ups note that this unification was introduced in version 2.1.3 — before that, commands and Skills were two completely separate systems, developed and maintained independently, which is where the "the two behave fundamentally differently" framing in older tutorials originated. If you're running a version after that, the two systems are already unified and there's nothing extra to configure or enable.
The safer way to confirm is checking your current version number directly (Claude Code generally has a command to check this), and if your version is noticeably older than that point, or you're not sure, running the update command before testing is the safer move — given how frequently Claude Code releases updates, most people actively using it today are almost certainly already on a post-merge version, but if your environment hasn't been updated in a long while, it's still worth the ten seconds to check rather than assuming you're automatically current.
If you've recently searched "what's the difference between a Claude Code command and a Skill," you've probably run into a batch of articles converging on the same answer: a command only runs when you manually type /command, while a Skill gets loaded automatically once Claude judges the situation matches — the core difference being "who pulls the trigger." That framing was accurate a few months ago, but the official documentation's current wording has since changed.
Claude Code's current documentation states, describing the Skill system, in unmistakably plain terms: "Custom commands have been merged into skills." Specifically, a file at .claude/commands/deploy.md and a Skill at .claude/skills/deploy/SKILL.md both create the exact same /deploy command, working identically — existing .claude/commands/ files still work fine and don't break because of the merge, but the official recommendation for new automation now points to the Skill directory instead.
The distinction that used to be treated as the core dividing line, manual versus automatic triggering, can now actually be achieved by either format — the difference is no longer "commands can only be manual, Skills can only be automatic," but that Skill frontmatter provides an explicit toggle to control this directly. Setting disable-model-invocation: true makes that Skill triggerable only by you typing /name manually, with Claude never deciding on its own to load it — exactly matching what old tutorials described as "command behavior." Conversely, leaving that field unset (the default) lets Claude judge automatically whether to load it based on the description field, while you can still trigger it manually too — both trigger paths coexist rather than being two mutually exclusive systems each permanently locked into one behavior.
Since triggering mechanism is no longer the dividing line, the actual difference now lies in file structure itself: .claude/commands/ holds a single Markdown file, suited to logic that's simple and doesn't need extra resources; .claude/skills/<name>/ is a directory that, beyond the core SKILL.md, can also hold supporting files like scripts/ (executable scripts) and references/ (extended reference material, loaded only when genuinely needed). When a workflow gets complex enough to need extra scripts or a lot of reference material, the Skill directory structure lets you split those out for separate management rather than crowding everything into a single file; if it's just one commonly used fixed instruction, the single-file command approach remains entirely sufficient, and there's no official mandate to migrate every existing simple command over.
One more practical detail worth knowing: if .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both exist at once, official documentation clearly states the Skill version takes precedence — /deploy runs whatever's defined in the Skill directory. This means if you're gradually migrating old commands into Skills, having both files briefly coexist mid-migration causes no errors; the newer version naturally takes over, with no need to manually delete the old file first before the new one takes effect.
This isn't a harmless wording quirk. If you design a team's automation workflows around the old distinction — say, deciding "this workflow needs automatic triggering, so it must be written as a Skill; that one should only be manually controlled, so it must be written as a command" — you could end up forcibly splitting simple, single-file-appropriate logic into an overly complex directory structure, or mistakenly assume the command format can never let Claude judge context automatically, giving up on automation that was actually achievable all along. The correct basis for choosing between them now is "does this workflow's complexity need extra supporting files," not "do I want it to trigger automatically or manually."
Before adding a new workflow next time, ask the structural question first: beyond a Block of instruction text, does this workflow need scripts, templates, or a lot of reference material alongside it? If so, use a Skill directory — put the core logic in SKILL.md and split extended content into scripts/ or references/. If not, a single-file command is entirely sufficient, and there's no need to over-engineer simple logic just because "Skills are apparently newer and more recommended." As for whether Claude should trigger it automatically — that's what the independent disable-model-invocation toggle handles, unrelated to which file structure you choose.