Claude Code: Slash Commands vs Skills vs CLAUDE.md — Complete Guide

Claude Code gives you three ways to customize its behavior: CLAUDE.md files, slash commands, and Skills. Each solves a different problem, triggers differently, and operates at different scope. Using the wrong one is not catastrophic — but it misses the leverage. The one-line framing: CLAUDE.md is always-on context that shapes every session; slash commands are on-demand instructions you type explicitly; Skills are automated procedures Claude selects based on what you describe. Understanding the distinction turns configuration from guesswork into architecture.

CLAUDE.md — Always-On Session Context

CLAUDE.md is a markdown file that Claude reads at the start of every session. Its contents become part of the system context — always active, always present, without you doing anything. You do not invoke it. You do not type a command. It is simply there, shaping every conversation in that project.

The file follows a strict hierarchy. Claude merges rules from multiple levels, with more specific paths taking precedence over broader ones. Understanding this hierarchy is critical for any non-trivial project.

• User-level (~/.claude/CLAUDE.md): applies to every Claude Code session across all projects on the machine — good for personal preferences, global code style rules, and conventions you always want enforced
• Project root (./CLAUDE.md): applies to the entire repository, the most common place to put team conventions, architecture constraints, and workflow rules
• Path-specific files (e.g., src/api/CLAUDE.md): applies only when working in that directory subtree — useful for module-specific rules that would clutter the project root
• @import directives: any CLAUDE.md can import another markdown file inline, so a project root can delegate to domain-specific guides without bloating a single file

• Best for: coding conventions that apply to all work in the project, architecture rules (never call the DB layer from controllers), team standards that must be ambient, context that would be tedious to re-explain every session
• Not for: workflows you only want sometimes, procedures with conditional steps, anything that generates overhead when you are just prototyping or exploring

Slash Commands — Ad-hoc On-Demand Instructions

Slash commands are markdown files stored in .claude/commands/ (project-scoped) or ~/.claude/commands/ (global). You invoke them by typing /command-name in the chat. Nothing happens until you type it — they are completely inert otherwise. The filename determines the command name: a file named review.md becomes the /review command.

# Code Review Checklist

Review the code at $ARGUMENTS and report findings organized by severity.

## Security
- Check for SQL injection, XSS, or injection vectors
- Verify authentication and authorization on all endpoints
- Flag any secrets or credentials in code

## Correctness
- Identify logic errors or off-by-one mistakes
- Check error handling — are errors swallowed silently?
- Verify that edge cases (null, empty, boundary values) are handled

## Test Coverage
- Note any untested code paths
- Flag missing assertions in existing tests
- Suggest what a meaningful test would cover if tests are absent

Return a prioritized list: Critical → High → Medium → Low.

The $ARGUMENTS substitution is the key composability feature. When you type /review src/api/auth.ts, Claude receives the full command body with src/api/auth.ts substituted in place of $ARGUMENTS. This lets a single command file handle any target you specify at invocation time. You can pass file paths, PR numbers, branch names, or any freeform string your command body knows how to use.

• Best for: checklists you want to run explicitly and occasionally, ad-hoc procedures you want to invoke on specific targets, instructions that are useful sometimes but would create noise if always active, team-shared workflows where the command name is the shared vocabulary
• Not for: rules that should always apply, complex multi-step automated workflows, anything you want Claude to trigger without you explicitly typing it

Skills — Reusable Automated Procedures

Skills are markdown instruction files with YAML frontmatter. Unlike slash commands, you do not invoke them by typing a specific name. Instead, Claude reads the frontmatter description at session start and autonomously selects the matching skill based on what you describe in natural language. If your description matches, Claude fires the skill. This makes Skills fundamentally different from slash commands: they are intent-driven rather than name-driven.

---
description: Run the test suite and summarize results. Use when asked to run tests, check coverage, or verify the test suite passes.
allowed-tools: Bash, Read
---

# Run Tests

1. Run the full test suite: npm test -- --coverage
2. Capture stdout and stderr
3. If tests fail, identify the failing test names and their error messages
4. Read the coverage report from coverage/lcov-report/index.html if it exists
5. Summarize: total tests, pass count, fail count, coverage percentage by module
6. If any tests failed, list them with their error messages and suggest likely root causes
7. If coverage dropped below 80% on any module, flag it explicitly

When you say run tests on the auth module or check if the test suite passes, Claude matches that intent against the skill description and invokes it automatically. You never type a command name. The trigger is the description match, not a keyword. This is what makes Skills suitable for complex workflows you want to feel conversational rather than command-driven.

• description (required): write it as a natural-language trigger — 'Run the test suite and summarize results. Use when asked to...' — Claude matches this against your request
• allowed-tools: restricts which tools the skill can use, limiting blast radius — list only what the workflow genuinely needs
• context: controls session isolation — load keeps current context, fork runs in an isolated copy, reset starts a clean context
• subagent-type: designates this skill for use by a specific subagent type if you are running multi-agent workflows
• tools: alternative to allowed-tools in some configurations, specifies available tool set

• Best for: recurring multi-step workflows (deploy, test, review, migrate), procedures where you want tool restrictions, workflows that benefit from context isolation via fork or reset, complex automation you want to trigger with natural language
• Not for: simple one-off instructions, rules that should always be ambient, cases where explicit invocation via a typed command is actually preferable for control

How the Three Layers Interact

The three layers load at different points in the session lifecycle and operate independently. CLAUDE.md files are read at session start and remain active for the entire session — they are always in context. Skill frontmatter is also scanned at session start so Claude knows what skills are available for matching, but the skill body is only loaded and executed when the skill is actually invoked. Slash command files sit on disk and are never loaded until you explicitly type their name.

In practice, the most effective pattern combines all three layers by responsibility. CLAUDE.md holds the conventions and constraints that define the project: code style, architecture rules, team standards. Skills handle the recurring automated workflows that happen regularly: running the test suite, deploying to staging, reviewing a PR. Slash commands cover the occasional explicit actions where you want manual control: a one-off security audit, generating a changelog, running a specific checklist on demand.

Decision Framework

• Should this apply to every session automatically without any invocation? Use CLAUDE.md — it is the right layer for ambient, always-on context.
• Is this something I want to type explicitly and run occasionally on a specific target? Use a slash command — the explicit invocation gives you control, and $ARGUMENTS lets you target it.
• Is this a complex workflow I want Claude to select automatically based on what I describe, potentially with tool restrictions or context isolation? Use a Skill with frontmatter configuration.
• Does this need subagent isolation, a clean context window, or restricted tool access for safety? A Skill with context: fork or context: reset and an allowed-tools list is the only mechanism that provides this.

A Concrete Example — Code Review Workflow

Suppose you want to enforce a consistent code review process on pull requests. You can implement this with any of the three layers. The right choice depends on how you want it to trigger and what overhead is acceptable.

Option 1: CLAUDE.md rule

# Code Review Standards

When reviewing any code change, always check:
- All public functions have docstrings or JSDoc comments
- No console.log or debug statements in production paths
- Error handling covers the network and I/O failure cases
- New dependencies are justified in the PR description

Apply these standards to every file you modify or review, unprompted.

Adding this to .claude/CLAUDE.md means Claude applies these standards to every session in the project — including casual prototyping sessions where the overhead of review standards is noise. It works, but it is blunt. Every conversation pays the cost.

Option 2: Slash command

# PR Review

Review the pull request at $ARGUMENTS against our team standards.

Fetch the diff, then check each changed file for:
1. Missing docstrings on public interfaces
2. Debug statements left in production paths
3. Unhandled error cases in network or I/O operations
4. New dependencies without justification in the PR description

Output a structured report: file path, finding, severity (Critical / High / Medium / Low).
Flag anything Critical at the top before the full report.

Stored as .claude/commands/pr-review.md, this becomes /pr-review 1234. You control exactly when it runs — it is an explicit gate you open, not an ambient rule. Good when you want code review to be optional or when you are the one deciding which PRs get the full treatment.

Option 3: Skill

---
description: Review code changes for quality, correctness, and team standards. Use when asked to review a PR, check a diff, or audit code changes before merging.
allowed-tools: Bash, Read, WebFetch
context: fork
---

# PR Review Skill

1. Identify the PR or diff target from the user's request
2. Fetch the diff using gh pr diff if a PR number is given, or git diff for local changes
3. For each changed file, check:
   - Public interfaces have docstrings or JSDoc
   - No debug statements in production code paths
   - Error handling covers network and I/O failures
   - New dependencies are justified
4. Produce a structured report grouped by severity
5. Summarize: total findings, critical count, recommendation (approve / request changes)

This triggers automatically when you say review these changes or can you audit this PR before I merge. Claude matches the intent against the description and fires the skill. The context: fork means it runs in an isolated copy of the session — findings and tool calls do not pollute your working context. The allowed-tools list restricts what the skill can touch. This is the highest-leverage option for a workflow you run regularly.

Exam Relevance — CCA-F Domain 3

Domain 3 of the Claude Certified Architect Foundations exam covers Claude Code Configuration and Workflows, which accounts for 20% of the total score. All three mechanisms appear in this domain. Expect questions on CLAUDE.md precedence rules when two files at different hierarchy levels define conflicting instructions, correct frontmatter for a skill that requires subagent isolation (context: fork) or tool restrictions (allowed-tools), and the distinction between hooks — which are external automation that intercepts agent actions at the process level — versus Skills, which are instruction sets Claude selects based on description matching. If you want structured practice on this domain, the concept library at /learn/claude-code-workflows walks through each mechanism with worked examples and common exam question patterns.