These past few days, while reorganizing my Claude Code skill architecture, I noticed something unexpected: when typing /, my Command instructions no longer appeared correctly. Turns out, Anthropic quietly merged Custom Commands into the Skills system back in v2.1.3 [1], with a single changelog entry:
“Merged slash commands and skills, simplifying the mental model with no change in behavior”
Simplifying the mental model. Sounds great, right? But the community’s reaction tells a different story.
What Were Commands and Skills?
Before the merge, Claude Code had two separate systems:
Custom Commands (.claude/commands/*.md) were user-triggered instructions. Drop a deploy.md file in there, and you get a /deploy slash command. The key behavior: it only loaded into context when you explicitly typed /deploy. No invocation, no tokens consumed. Predictable and controllable.
Skills (.claude/skills/*/SKILL.md) were richer knowledge modules with frontmatter support, subdirectory structures, and Progressive Disclosure. The critical difference: Claude could auto-load them when it judged them relevant — no user action required.
The core distinction wasn’t about feature richness — it was about who controls when things load. Commands: “I say when.” Skills: “Claude decides.”
What Changed After the Merge?
Post v2.1.3, .claude/commands/ files still work (backward compatible), but they’re now treated as Skills. The official docs state [2]:
“Custom commands have been merged into skills. A file at
.claude/commands/deploy.mdand a skill at.claude/skills/deploy/SKILL.mdboth create/deployand work the same way.”
Just moving house? Not quite. There’s a behavioral change that caught many off guard: commands that previously only loaded on manual trigger can now be auto-loaded by Claude.
GitHub Issue #14851 [3] was the first to report this: “Commands are now apparently ‘skills’ and are loaded into context without being invoked. This effectively removes command functionality from Claude Code.”
If you had 10 custom commands sitting quietly in your commands directory consuming zero tokens, after the merge Claude started scanning and loading the ones it deemed “relevant” — silently eating into your context budget.
Three Community Concerns
1. Context Pollution
The most reported issue. Heavy command users with dozens of custom instructions saw their context budgets eroded after the merge. In Context Engineering terms, this violates the JIT loading principle — turning “on-demand” into “eager loading.”
2. Controllability
A detailed analysis on paddo.dev [5] highlighted the controllability dilemma: you can’t force Claude to load a skill when you need it, and you can’t prevent it from loading when you don’t. Loading timing is entirely LLM-decided — a regression for developers who need precise workflow control.
3. Documentation Confusion
Initially, the changelog said “merged” but docs still described Commands and Skills separately. Issues #17578 and #17288 reflected developer confusion about which directory to use and what behavioral differences remain.
Technical Comparison
| Commands (Old) | Skills (New) | |
|---|---|---|
| Location | .claude/commands/*.md | .claude/skills/*/SKILL.md |
| Trigger | User-only (/command) | User or Claude auto-loads |
| Context loading | On invocation only | May be auto-loaded |
| Supporting files | Not supported | Supported (templates, scripts) |
| Frontmatter | Not supported | Supported (description, invoke, tools) |
| Backward compat | Still works (no removal date) | Recommended path forward |
My Take
Perhaps Anthropic’s direction is right — merging two systems that do the same thing into one makes architectural sense. And Skills are genuinely more powerful: frontmatter control, subdirectory structure, Progressive Disclosure — things Commands couldn’t do.
But the transition pain is real, especially around auto-loading. For developers already carefully managing token budgets, an uncontrollable new source of context consumption isn’t “simplifying the mental model” — it’s adding a new variable to manage.
The .claude/commands/ directory still works with no announced removal date (Issue #37447 [4] is tracking this). If you’re still using Commands, no rush to migrate. But long-term, moving to Skills seems inevitable.
Perhaps the best strategy: migrate your most important Commands to Skills format, but explicitly set invoke: user in the frontmatter — preserving “I say when” control while gaining Skills’ other benefits.
If you want to migrate your Commands to Skills yourself, I wrote a separate resource article explaining how. It includes a downloadable Agent Playbook — just download it and tell your Agent to follow the steps.
References:
[1] Claude Code v2.1.3 Release — Release changelog announcing the Commands/Skills merge https://github.com/anthropics/claude-code/releases/tag/v2.1.3
[2] Extend Claude with skills — Official Docs — Official Skills system documentation https://code.claude.com/docs/en/skills
[3] Issue #14851 — Commands loaded as skills without invocation — First GitHub issue reporting auto-loading behavior https://github.com/anthropics/claude-code/issues/14851
[4] Issue #37447 — Track full deprecation of .claude/commands/ — Tracking timeline for commands directory removal https://github.com/anthropics/claude-code/issues/37447
[5] Claude Skills: The Controllability Problem — paddo.dev — Analysis of Skills controllability issues https://paddo.dev/blog/claude-skills-controllability-problem/
Support This Series
If these articles have been helpful, consider buying me a coffee