The slash command is the entry point. The skill is the specification behind it. When you type /review-pr, Claude is not running "slash command logic." It is loading a SKILL.md file with instructions, process steps, and an output contract, then executing based on that. The slash command tells Claude which skill to load. The skill tells Claude what to do.

Most developers treat the two as the same thing. At Agent Engineer Master, this confusion is the first thing we audit in any skill library: does each slash command have an actual specification behind it, or just a placeholder name?

TL;DR: A slash command is the /name syntax you type to invoke a skill. A skill is the SKILL.md file that defines what Claude does when invoked. Every skill automatically creates a slash command. Not every slash command has a real skill behind it.

What is a slash command in Claude Code?

A slash command is a shortcut that tells Claude to load a named skill and execute its instructions. You type /skill-name, the Claude Code runtime locates the corresponding SKILL.md file, loads its full contents into the active context window, and Claude executes based on what is in that file. The slash command contains no logic. It is a pointer.

When there is no matching SKILL.md, or when the SKILL.md is a single vague line, Claude invents the behavior from scratch each time. This is why teams blame Claude for being "inconsistent." It is not Claude being unpredictable. It is the absence of a specification.

In Claude Code, skills can be installed at two levels: user-level in ~/.claude/skills/ (available across all your projects) or project-level in .claude/skills/ (scoped to one repository). A team of five sharing a project-level skill library gets the same slash commands on every machine without any per-person setup (source: Claude Code documentation, 2026).

What is a Claude Code skill?

A Claude Code skill is a SKILL.md file with three core components: YAML frontmatter, numbered process steps, and an output contract. The frontmatter names the skill and controls when it triggers. The steps define what Claude does in sequence. The output contract defines what the skill produces and what it refuses to produce.

The frontmatter contains:

  • name: Becomes the slash command name automatically.
  • description: The trigger condition for automatic invocation. Capped at 1,024 characters and must stay on a single line (source: Claude Code documentation). Claude Code 2.1.86 introduced a 250-character display cap in the /skills listing, so front-load the trigger condition in the first 250 characters (source: anthropics/claude-code GitHub, issue #40121, 2025). This is the most important line in the file.
  • tools, model, and other metadata: Optional configuration for the skill's runtime environment.

The process steps are numbered instructions Claude follows in sequence. These can include tool calls, reference file loads, and conditional branches. The output contract defines what the skill produces and what it explicitly does not produce.

A skill without an explicit output contract is a fair-weather skill. It works on the examples you tested and breaks on the inputs you did not anticipate.

For the full anatomy of a SKILL.md file, see What Is a Claude Code Skill?.

How do slash commands and skills connect?

Every SKILL.md file with a name field in its frontmatter automatically generates a slash command matching that name. A skill named review-pr becomes /review-pr with no additional configuration required. The connection is built into the Claude Code runtime and maintained automatically.

When you invoke the slash command, here is the exact sequence:

  1. Claude Code looks up the SKILL.md file by its name field.
  2. The full file contents load into the active context window.
  3. Claude reads the process steps and executes them in order.
  4. Output follows the contract defined in the skill.

The slash command handles step 0. Steps 1 through 4 are entirely determined by the SKILL.md file. Each skill adds approximately 100 tokens to Claude's startup context budget regardless of how long or short the SKILL.md is (source: AEM research synthesis, 2026). A three-line placeholder costs the same context as a 200-line production spec. The difference is what you get back.

"The failure mode isn't that the model is bad at the task. It's that the task wasn't specified tightly enough. Almost every production failure traces back to an ambiguous instruction." - Simon Willison, creator of Datasette and llm CLI (2024)

"When you give a model an explicit output format with examples, consistency goes from ~60% to over 95% in our benchmarks." - Addy Osmani, Engineering Director, Google Chrome (2024)

When do you need a slash command without a full skill?

You can create a lightweight slash command without a SKILL.md file. These inline commands live as short entries in CLAUDE.md or your settings and work for single-step operations where output consistency is not required and you will not need to load reference files or branch conditionally. The threshold for moving to a full skill is lower than most people think.

Signs you need a SKILL.md instead of an inline command:

  • You have corrected Claude's output three or more times for the same invocation.
  • Output format changes between sessions.
  • The task involves more than one sequential step.
  • The workflow touches operations where sequence matters: deployments, API writes, data modifications.

At AEM, we track a simple proxy: if you have invoked the same informal command more than ten times, you have already spent more time correcting inconsistencies than it would have taken to write the specification once. That estimate is based on commissions where teams showed us their correction history before engaging us to build a proper skill.

When does a slash command need a full skill behind it?

Any workflow with more than one step, a required output format, or access to reference files needs a SKILL.md. These conditions cover the majority of real development tasks, including deployments, API writes, and any repeated workflow you invoke more than three times a week.

The specific signals:

  1. Multi-step sequence: Claude cannot reliably maintain step order across a multi-step workflow from a one-line description.
  2. Consistent output format: Without an output contract, Claude produces whatever format it considers reasonable that session.
  3. Reference file access: Only a SKILL.md process step can declare and load a reference file at a specific point in the workflow.
  4. Repeated use: Any workflow you invoke more than three times a week belongs in a formal spec.

In our commission work at AEM, skills with explicit process sections and output contracts pass the consistency bar on the first build. Skills with vague descriptions or missing output contracts account for the majority of revision cycles across 200+ production builds (source: AEM internal, 2026). AWS research on multi-agent systems documents a 37% performance gap between lab and production, attributing the gap primarily to incomplete specifications (source: AWS multi-agent systems research, 2025). A well-structured SKILL.md is the specification that closes that gap for single-skill workflows.

This pattern does not scale to cross-domain orchestration. A single SKILL.md specifies one workflow. If your task requires multiple agents running in parallel, dynamic tool selection across domains, or runtime decision trees with unpredictable depth, you need a multi-agent architecture, not a more elaborate skill. Recognizing that boundary early prevents building a skill that grows into a fair-weather monster.

See When Does a Workflow Need Multiple Agents vs a Single Skill? for the decision framework.

What does the minimal file structure look like?

A SKILL.md that generates a working slash command needs at minimum a name field and at least one process step. Three lines are enough to create a functional slash command. A description field enables automatic triggering but is not required for slash command invocation.

---
name: review-pr
description: "Reviews a pull request for missing tests, API surface changes, and logic errors. Invoke when the user asks to review a PR, check a diff, or audit a code change."
---

## Process

1. Read the diff provided by the user.
2. Identify missing test coverage for changed or new functions.
3. Flag any API surface changes that break backwards compatibility.
4. Output findings as a numbered list grouped by severity: critical, moderate, minor.

The name field creates /review-pr. The description controls automatic activation when the user's intent matches. The process steps determine every output. Without those steps, you have a slash command pointing at nothing useful. With 10 skills installed, Claude Code loads approximately 1,000 tokens of skill metadata at session start, keeping the overhead proportional to library size (source: Claude Code documentation, 2026).

For how this compares to prompt-based approaches, see What's the Difference Between a Claude Code Skill and a Prompt?.

Frequently Asked Questions

Every slash command in Claude Code either points to a SKILL.md file or runs inline from CLAUDE.md. The distinction matters: inline commands cannot load reference files, branch on conditions, or enforce output contracts. For any workflow you invoke more than a handful of times, a SKILL.md is the right call.

Can I have a slash command that runs without a SKILL.md file? Yes. Claude Code supports inline slash commands defined in CLAUDE.md. These work for simple one-step tasks but cannot load reference files, follow multi-step sequences, or enforce output contracts. If the task has more than one step, build a SKILL.md.

Does every SKILL.md file get a slash command? Every SKILL.md with a name field in its frontmatter creates a slash command automatically. A skill without a name field will not appear in the slash command list and can only be loaded programmatically or through the description's automatic triggering.

Can a skill trigger without a slash command? Yes. The description field controls automatic invocation. If Claude determines the description matches the user's intent during context loading, the skill activates. This is independent of the slash command and can be tuned by rewriting the description to be more or less specific.

What happens when two skills share a name? Project-level skills override user-level skills with the same name. User-level skills override system defaults. No error is thrown; the most specific scope wins silently. If your project-level skill is not behaving as expected, check whether a user-level skill with the same name is shadowing it.

How do I test that a slash command is loading the right skill? Type the slash command and observe whether Claude orients immediately to the process steps in your SKILL.md without asking for clarifying context. If it asks general questions about what you want, either the skill is not loading or the description is too passive to frame Claude's expectations before execution.

Last updated: 2026-05-05