[DOCS] Clarify relationship between skills and slash commands post v2.1.1

[PaulRBerg]

What type of docs issue?

Unclear

Section or topic

Skills and slash commands documentation - specifically how they relate to each other after v2.1.1

What's wrong or missing?

Boris Cherny stated on 𝕏 (in response to a question about the v2.1.1 launch):

Yes! Skills and slash commands are the same thing

This creates confusion for users who have been treating them as distinct concepts:

• Skills: Auto-invoked by Claude based on context
• Slash commands: Manually invoked by the user via /command

The current documentation doesn't clearly explain what "same thing" means in practice:

1. Can skills now be manually invoked with /skill-name?
2. Can slash commands now be auto-invoked by Claude when contextually relevant?
3. If they're truly unified, why maintain two separate names and directory structures?

Suggested fix

1. Update the docs to explicitly explain the unified behavior:

   • How the merger works under the hood
   • Whether both manual and auto-invocation apply to all registered prompts
   • The practical implications for plugin/skill authors

2. Consider terminology consolidation in future versions:

   • If they're the same concept, using one term would reduce cognitive overhead
   • If there are still meaningful distinctions, document them clearly

3. Add a migration note for users familiar with the pre-v2.1.1 mental model

Impact

Medium

[PaulRBerg]

It generally feels to me that now there are multiple ways of achieving the same behavior with Claude Code, and this creates a 'feature creep' effect.

[gerrywastaken]

Can skills now be manually invoked with /skill-name?

claude-code/CHANGELOG.md

Line 95 in f34e253

- Improved skills from `/skills/` directories to be visible in the slash command menu by default (opt-out with `user-invocable: false` in frontmatter)

Can slash commands now be auto-invoked by Claude when contextually relevant?

claude-code/CHANGELOG.md

Line 638 in 553d6ff

- Added SlashCommand tool, which enables Claude to invoke your slash commands. https://code.claude.com/docs/en/slash-commands#SlashCommand-tool

If they're truly unified, why maintain two separate names and directory structures?

Good question. I also wish there was a way to say... I want this to be manually invoked EXCLUSIVELY, never auto invoked by Claude.

Additionally (and related), I believe slash commands didn't previously have their fontmatter injected into the context window, but now with claude autoselecting them, I guess that is no longer the case?

[PaulRBerg]

Thanks for your comment @gerrywastaken

Added SlashCommand tool, which enables Claude to invoke your slash commands

That tool has been available for some time.

What I am interested to know is this: are slash commands automatically loaded by Claude now, without me explicitly telling Claude to run a specific command? Because if yes, there really is no meaningful difference between skills and slash commands. Keeping them as two separate concepts just increases the learning curve, for no benefit.

I believe slash commands didn't previously have their fontmatter injected into the context window

AFAIK, the entire context of the slash commands was loaded in context. But of course, don't quote me on this - confirmation from an Anthropic engineer would be helpful.

[dennisonbertram]

I second this bit of confusion. I have been thinking of slash commands as ways to deterministically invoke some sort of behavior or process that I want to have happen right now, while skills, I thought of as a knowledge base for how to do something.

With the two combined, it's a little unclear to me the difference between asking to do something and knowing how to do something. I would assume, for example, I might ask to do something by a slash command that, under the hood, might automatically invoke multiple skills to complete.

Maybe a nice way to visualize it is a slash command called "/Bake-Bread" that invokes my bakery skill, but on it's own my bakery skill doesn't necessarily mean that I'm trying to bake bread. Indeed "/Bake-a-cake" might also invoke my bakery skill but be a totally different process.

[gerrywastaken]

@PaulRBerg I think the fontmatter was preloaded from the slash command, otherwise Claude wouldn't know that there was a relevant tool available to call with the SlashCommand tool.

AFAIK, the entire context of the slash commands was loaded in context.

I meant without invoking it. Again, so Claude knows what slash commands are available, just like with skills. The whole thing is then loaded when invoked.

[PaulRBerg]

My understanding is that the entire contents of the slash command Markdown used to be loaded into context upon startup (in previous versions of Claude Code). Just like all MCP tools were loaded into context.

But in any case. That's the previous behavior. Now, we should clarify the current behavior.

[PaulRBerg]

The release notes for v2.1.3 say:

Merged slash commands and skills, simplifying the mental model with no change in behavior

What does that mean? Haven't they been merged in v2.1.1?

[abreufilho]

I am having a lot of trouble to properly invoke skills from slash commands and vice versa (consistently). And the release-notes for 2.1.3 seems not to be updated in the docs.

[khalido]

It would be nice to clearly document the one thing to use b/W skills and commands.

I would like to see something like:

Skills add behaviours and new abilities. Add custom skills in /skills.

• Ai receives all skills on startup, can auto invoke
• Human can manually trigger by /skill

Then a line on how to sync your custom git skills to GitHub or somewhere.

Currently it's a bit confusing. Claude code wasn't triggering a skill yesterday, I asked it why and it replied that skills are for me to use manually. So even the AI is confused!

Claude code harness has a lot of built in skills. E.g CC handles GitHub excellently. In the ancient times ppl built git skills for Claude code. It would be nice to have a big picture list of the kind of things we shouldn't bother writing skills for as Claude code is already on top of those.

This would be useful to stop over adding un-necessary skills. I noticed many of the skills out there seem un necessary. Which leads to a Claude code feature request - review and rate the useful if a skill. Since this changes over time this would be useful.

[PaulRBerg]

CC handles GitHub excellently. In the ancient times ppl built git skills for Claude code

Oh, so would you recommend I delete my gh-cli skill, @khalido?

How can I see a list of all built-in CC skills?

[abreufilho]

@PaulRBerg you didn't ask me, but chiming in anyway: you can definitely clean up that gh-cli overprompting. unless you have very specific constraints, teaching the model basic CLI usage now is redundant.

it's like explaining how to walk: you don't need to keep explaining "lift knee, extend leg, place foot" every time. eventually the model just "knows" how to walk. the training data on these big models already covers gh, git, etc perfectly.

on the topic of context/loading behavior discussed above: previously slash commands dumped everything into context on startup. now, with the unification, they seem to follow the "progressive disclosure" pattern mentioned in the docs. it likely loads just the frontmatter/definitions first so it knows what exists (auto-discovery), and reads the actual heavy content only when the task requires it.

and regarding the "manual exclusive" question @gerrywastaken asked: the docs actually clarify this now. if you want a command that only you can run (and Claude never auto-invokes), you need disable-model-invocation: true. the user-invocable flag is just for the UI menu. if you set that to false, it hides from the menu but Claude can still grab it if it thinks it's relevant. so to truly stop the "feature creep" of auto-execution, you have to disable the model invocation explicitly.

Edit with references of the docs:
https://code.claude.com/docs/en/slash-commands#when-to-use-each
https://code.claude.com/docs/en/skills#control-skill-visibility
https://code.claude.com/docs/en/skills#available-metadata-fields
https://code.claude.com/docs/en/skills#add-supporting-files-with-progressive-disclosure