Claude Code Skills vs Slash Commands: Complete 2026 Guide

If you have spent any time with Claude Code in 2026, you have probably noticed that the line between “skills” and “slash commands” is blurry. The documentation uses both terms. The community uses both terms. And if you look at the underlying mechanics, the distinction has shifted significantly from how it worked a year ago.

This guide settles the confusion, gives you a decision framework for 10 real engineering scenarios, and documents the hybrid invocation pattern that no one else seems to have written up.

The Core Distinction in 30 Seconds

Auto-invocation vs. Manual Triggering

The most important difference is not syntax — it is who decides when to run.

Slash commands (the original .claude/commands/ format) are always manual. You type /deploy and the command runs. Claude never triggers it on its own.

Skills (the current .claude/skills/ format) support both modes:

• Manual invocation: You type /skill-name, same as a slash command
• Autonomous invocation: Claude reads the skill’s description field and decides to load it when the current task matches

That second mode is what makes skills qualitatively different. A skill with the right description can intercept Claude’s behavior without you doing anything — it routes Claude’s reasoning the same way a system prompt would.

One more thing worth knowing: in 2026, the two formats are unified. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. Your existing commands files keep working unchanged. The skills format is the recommended path for new workflows because of the features it adds.

Side-by-Side Comparison

Skills are a superset of slash commands. Everything a command can do, a skill can do, plus more.

When to Use Skills

Skills win when you want Claude to apply judgment about when to run something, or when you need supporting infrastructure around the instruction set.

Pattern 1: Context-Sensitive Workflows That Should Run Automatically

The canonical skill use case: a workflow that should trigger based on what you are doing, not because you remembered to type a command.

Example: A migration-safety skill that runs whenever Claude writes a database migration.

---
description: >
  Check a new database migration for backward compatibility, rollback safety,
  and index impact. Use when writing or reviewing database migration files.
allowed-tools: Read Bash(psql *) Bash(pg_dump *)
---

Review the migration file for:

1. Backward compatibility — can the old app version run against the new schema?
2. Rollback path — does a down migration exist and is it safe?
3. Index creation — does the migration create indexes without CONCURRENTLY on large tables?
4. Data migrations — are they in a separate step from schema changes?

Output: pass/fail per check, with specific line references for failures.

This skill loads automatically when Claude is working with migration files. Without it, Claude might write a perfectly valid migration that locks a table during deployment. The skill patches that gap without requiring you to remember to invoke anything.

Pattern 2: Reference Material for Claude to Consult

Not every skill is about running a procedure. Some skills are knowledge packages — conventions, architecture decisions, domain context — that Claude should apply to its work without you explicitly referencing them.

---
description: >
  API design conventions for this codebase. Use when writing new endpoints,
  reviewing API changes, or designing new resources.
user-invocable: false
---

## API Conventions

- RESTful naming: nouns for resources, verbs for actions when necessary
- Consistent error envelope: `{ "error": { "code": "...", "message": "...", "details": [] } }`
- Pagination: cursor-based for large collections, offset for admin endpoints
- Versioning: path-based (/v1/, /v2/), never break v1 without 6-month notice

user-invocable: false hides this from the / menu since it is not something you invoke directly — Claude loads it when it is relevant.

Pattern 3: Multi-Phase Workflows with Supporting Files

When a workflow is too complex for a single file, the skills directory structure keeps it organized.

.claude/skills/deploy/
├── SKILL.md           # Entry point and orchestration instructions
├── pre-deploy.md      # Pre-deployment checklist
├── rollback.md        # Rollback procedure reference
└── environments/
    ├── staging.md     # Staging-specific notes
    └── production.md  # Production-specific constraints

The SKILL.md references supporting files:

---
name: deploy
description: Run the deployment workflow
disable-model-invocation: true
allowed-tools: Bash(git *) Bash(kubectl *) Bash(aws *)
---

Deploy $ARGUMENTS to the target environment.

Reference @pre-deploy.md for the pre-deployment checklist.
Reference @environments/$ARGUMENTS.md for environment-specific constraints.
If deployment fails, follow the rollback procedure in @rollback.md.

This structure keeps SKILL.md readable while giving Claude access to detailed reference material that only loads when needed.

When to Use Slash Commands

There are still good reasons to use the .claude/commands/ format or the equivalent pattern with disable-model-invocation: true.

Pattern 4: Side-Effect Operations You Control Manually

Deployments, commits, releases, sending Slack messages — anything with irreversible side effects should never auto-invoke. You want to trigger these explicitly.

---
name: release
description: Cut a release for this project
disable-model-invocation: true
---

Prepare and cut a release:

1. Check that all tests pass: run `npm test`
2. Update CHANGELOG.md with changes since the last tag
3. Bump the version in package.json
4. Commit: `chore: release vX.Y.Z`
5. Tag: `git tag vX.Y.Z`
6. Push branch and tag: `git push && git push --tags`

Do not proceed past step 1 if tests fail.

disable-model-invocation: true ensures Claude never decides to cut a release because your code looks production-ready.

Pattern 5: Personal Utility Commands

One-off utilities that are too specific to your personal workflow to benefit from autonomous invocation. Things like:

• /standup — Summarize yesterday’s git commits for standup
• /wip — Create a WIP commit with a timestamp
• /explain-pr — Summarize the current PR branch for a non-technical colleague

These are things you remember to type when you need them. Autonomous invocation would not help and might occasionally misfire.

Pattern 6: Shared Team Standards That Require Explicit Acknowledgment

Some workflows work better when invocation is intentional — code review before merging, security checks before deploying, documentation audits before a release. Making these manual creates a ritual that reinforces the practice.

---
name: sec-check
description: Security review before pushing to main
disable-model-invocation: true
---

Run a security review on the current branch diff.

Check for:
- Hardcoded credentials, API keys, tokens
- Unvalidated external inputs reaching SQL or system calls
- New dependencies with known CVEs (run `npm audit` or equivalent)
- Debug endpoints or logging that expose sensitive data

Output: PASS or FAIL with specific file:line references for failures.
Do not approve the check automatically — wait for explicit confirmation.

The Gray Zone — 5 Scenarios Where It Is Not Obvious

Scenario 1: Code Review

The question: Should review be a skill that auto-invokes before every commit, or a command you type when you are ready?

The answer: Both can work, and the right choice depends on your workflow. Auto-invocation (description without disable-model-invocation) makes sense if you want Claude to proactively flag issues as you work. Manual invocation makes sense if you want review to be a deliberate checkpoint.

Hybrid approach: make it a skill with auto-invocation enabled, but write the description narrowly:

description: >
  Review code for correctness and security issues. Use when the user
  explicitly asks for a review, or when they are about to commit.

The “about to commit” clause enables auto-invocation at the right moment without triggering on every file edit.

Scenario 2: Test Generation

The question: Should test generation auto-invoke when you write new functions, or stay manual?

The answer: Auto-invocation works well here. A description like “Use when writing new functions or classes that are missing test coverage” gives Claude a clear signal without being too broad.

The risk is interruption: if Claude auto-generates tests while you are in the middle of writing business logic, it can be disruptive. Consider user-invocable: false paired with a tight description so Claude invokes it only when you reach a natural stopping point.

Scenario 3: Documentation Updates

The question: Should documentation updates happen automatically after code changes?

The answer: Be careful. Auto-invoking a skill that writes files can create a lot of noise if the description is too broad. Write it to trigger specifically on exported API changes:

description: >
  Update API documentation after changes to exported functions, interfaces,
  or public APIs. Do not invoke for internal code changes.

And consider whether you actually want Claude writing documentation files without review — that might warrant disable-model-invocation: true and a manual workflow.

Scenario 4: Dependency Updates

The question: Auto-invoke when package files change, or manual?

The answer: Manual. Dependency updates can break things in subtle ways and should be a deliberate decision. A skill with disable-model-invocation: true that you invoke when you are ready to handle dependency work is safer than one that fires whenever Claude touches a lock file.

Scenario 5: Environment-Specific Behavior

The question: Should different skills activate in production vs. staging?

The answer: Skills support a paths field for file-based activation, but there is no native environment awareness. The workaround is to use the ! shell injection to read environment state at runtime:

---
description: Apply production safety checks
---

Current environment: !`cat .env | grep NODE_ENV | cut -d= -f2`

If the environment is production:
- Do not run destructive operations
- Require explicit confirmation for any write operations
- Log all actions to stdout

Otherwise, proceed normally.

The Hybrid Pattern — Skills That Call Commands

This is the pattern no one else documents. A skill can invoke other skills internally using Claude Code’s Skill tool. This lets you build a coordinating skill that delegates to specialized sub-skills, each with their own tool restrictions and context.

Architecture

/deploy-workflow (coordinating skill)
  ├── Invokes /sec-check (security review)
  ├── Invokes /run-tests (test suite)
  └── Invokes /deploy (deployment)

Each sub-skill can have:

• Different allowed-tools restrictions
• Different model settings (lightweight model for checks, full model for complex decisions)
• context: fork to run in isolation

Working Example

Coordinating skill (SKILL.md):

---
name: deploy-workflow
description: Full pre-deployment workflow — security, tests, then deploy
disable-model-invocation: true
allowed-tools: Skill
---

Run the complete pre-deployment workflow in sequence:

1. Invoke /sec-check to run the security review. Stop if it fails.
2. Invoke /run-tests to run the full test suite. Stop if tests fail.
3. Ask the user to confirm before proceeding.
4. If confirmed, invoke /deploy $ARGUMENTS.

If any step fails, report the failure and stop. Do not continue to the next step.

Security check sub-skill (.claude/skills/sec-check/SKILL.md):

---
name: sec-check
description: Security review of current branch changes
disable-model-invocation: true
allowed-tools: Read Bash(git diff *) Bash(npm audit) Bash(trivy *)
---

Run a security review of the current branch diff.

1. Get the diff: `git diff main`
2. Scan for hardcoded credentials and secrets
3. Run `npm audit` and report high/critical CVEs
4. Check for unvalidated external inputs

Return PASS or FAIL with findings. Do not prompt for confirmation.

The key design decisions in this pattern:

• The coordinating skill only needs Skill in allowed-tools — it cannot run Bash directly
• Each sub-skill has tightly scoped tool permissions
• disable-model-invocation: true on all three skills means Claude never auto-runs any part of the workflow
• The coordinating skill handles flow control (stop on failure, confirm before deploy)

This pattern is useful when you have a multi-phase workflow where each phase has distinct risk profiles and you want different safety guarantees per phase.

Decision Matrix (Copy-Paste)

Use this table when you are deciding how to implement a workflow. Ten common engineering scenarios with a recommendation for each.

Migrating Legacy Commands to Skills (2026 Frontmatter Reference)

If you have files in .claude/commands/, they keep working indefinitely. Migrate when you need features that commands do not support.

Migration Steps

1. Create .claude/skills/<name>/SKILL.md
2. Move the content from .claude/commands/<name>.md
3. Add the frontmatter fields you need
4. Test that /name still works
5. Delete the old command file (optional — both can coexist)

Complete Frontmatter Reference

All fields as of 2026 Q2:

---
name: display-name            # Display label (optional; command name comes from directory)
description: >                # Recommended. What it does and when to invoke
  One or two sentences.
  Second sentence if needed.
when_to_use: >                # Optional. Additional trigger context
  Example phrases or situations.
argument-hint: "[issue-id]"   # Shown in autocomplete
arguments: [issue, branch]    # Names for $issue, $branch positional substitution
disable-model-invocation: true  # true = manual only
user-invocable: false         # false = Claude only (hidden from / menu)
allowed-tools: Read Bash(git *) Bash(npm test)  # Permitted tools
disallowed-tools: Write WebFetch  # Blocked tools
model: claude-opus-4-6        # Model override for this invocation
effort: high                  # low / medium / high / xhigh / max
context: fork                 # Runs in a subagent context
agent: Explore                # Which agent when context: fork
hooks:                        # Skill-scoped hooks
  PostToolUse:
    - matcher: Write
      hooks:
        - type: command
          command: git diff --stat
paths:                        # Auto-activate only when working in matching paths
  - "src/db/migrations/**"
shell: bash                   # bash (default) or powershell
---

Which Fields to Add First

When migrating from a command, start with just two fields:

1. description — enables autonomous invocation if you want it, improves autocomplete
2. allowed-tools — scopes tool access to what the skill actually needs

Everything else is optional and can be added as you identify the need.

FAQ

Q: If I convert a command to a skill, will it auto-invoke when I do not want it to?

Only if you add a description without disable-model-invocation: true. A skill without a description will not auto-invoke. A skill with a description and disable-model-invocation: true will not auto-invoke. You control this explicitly.

Q: Can I have both .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md?

They both create /deploy, but a skill takes precedence over a command with the same name. If you want to keep both for some reason, rename one of them.

Q: How does Claude decide which skill to load autonomously?

Claude reads all skill descriptions at session start (up to 1,536 characters per description). When you give a prompt, Claude evaluates whether any skill description matches the task. The match is semantic — Claude is making a judgment call, not doing keyword matching. Write descriptions that are specific enough to be useful but not so narrow that they miss real cases.

Q: Does converting to a skill change the context window cost?

For skills without auto-invocation (disable-model-invocation: true), no — the skill content only loads when you invoke it. For skills with auto-invocation, the description is always in context, but the full skill body only loads when invoked. CLAUDE.md content is always in context regardless.

Q: Can skills call MCP tools?

Yes. Use mcp__<server>__<tool> in allowed-tools. For example: allowed-tools: mcp__github__create_pull_request. Glob syntax works too: mcp__github__* allows all GitHub MCP tools.

Q: What happens to skill content during context compaction?

Auto-compaction re-attaches invoked skills after summarization, keeping the first 5,000 tokens of each. Multiple skills share a 25,000-token budget, prioritizing the most recently invoked. If a critical skill seems to stop influencing behavior after a long session, re-invoke it.

Related Resources

• How to Write Claude Code Skills: Complete Developer Guide (2026) — Full authoring reference with production examples
• 15 Best Claude Code Skills You Should Install in 2026 — Curated skill library from across the ecosystem
• Claude Code Hooks: Complete Reference (2026) — Hooks for deterministic pre/post-action behavior
• Claude Code MCP: Complete Guide (2026) — Extending Claude with external tool servers