3.2 Custom Slash Commands & Skills

Lesson 3.1 gave you the always-on layer: CLAUDE.md, loaded every session. But not everything should be always-on. Some things are workflows you run occasionally — a code-review checklist, a brainstorming routine, a deploy sequence. Loading those into every session would waste context on instructions you only need now and then. Task Statement 3.2 is about the ON-DEMAND layer: custom slash commands and skills, which package a workflow you invoke when you want it.

The mental model: CLAUDE.md is the standing rules posted on the office wall — always visible. A skill is a recipe card in a drawer — you pull it out exactly when you're cooking that dish, and it's not cluttering the wall the rest of the time. Both store instructions, but one is always in context and one loads only when invoked.

A useful simplification up front: in Claude Code, custom slash commands and skills have been MERGED into one framework. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both give you a /deploy command. So when this lesson says 'skill,' the same scoping and invocation ideas apply to commands too. Let's cover where they live, how to configure them, and when to choose a skill over CLAUDE.md.

Just like CLAUDE.md, commands and skills are scoped by WHERE you put them — and it's the same project-vs-user split from Lesson 3.1, so the intuition carries straight over.

PROJECT scope: a command in .claude/commands/ or a skill in .claude/skills/ lives in the repository, so it's shared with the whole team via version control. This is where a team-wide /review command belongs — commit it, and every developer gets it on clone or pull. USER scope: the same things in ~/.claude/commands/ or ~/.claude/skills/ are personal to you, available across all your projects but not shared with teammates. This is where your personal /brainstorm skill belongs.

The exam's most direct 3.2 question is exactly this: you want a /review command available to every developer when they clone or pull the repo — where do you put it? Answer: .claude/commands/ in the project (version-controlled, shared). Not ~/.claude/commands/ (that's personal), not CLAUDE.md (that's for instructions/context, not command definitions), and definitely not a fictional '.claude/config.json with a commands array' — that doesn't exist. Same scoping logic as CLAUDE.md: project = team, user = personal.

A skill is a SKILL.md file, and the top of that file holds frontmatter — configuration that shapes how the skill runs. The exam highlights three options, each solving a specific problem.

context: fork runs the skill in an ISOLATED subagent context (recall Domain 1's subagents). Why? Because some skills produce a lot of verbose output — a codebase-analysis skill might read dozens of files, or a brainstorming skill might generate pages of alternatives. Without isolation, all that noise pollutes your main conversation. With context: fork, the skill does its messy work in a separate context and returns only the result — keeping your main session clean. It's the same context-isolation benefit subagents gave you, now available to a skill.

allowed-tools is a SECURITY boundary: it restricts which tools the skill may use while it runs. A brainstorming skill should probably be read-only — give it Read but not Write or Bash, and it cannot accidentally modify or delete anything. argument-hint solves a usability problem: if a skill needs parameters and you invoke it without them, the hint prompts you for what's required, so you're not left guessing what the command expects.

The most important judgment in this lesson — and a recurring exam theme — is choosing between a skill and CLAUDE.md. They're not interchangeable, and the deciding question is simple: is this ALWAYS relevant, or only relevant for a specific task?

CLAUDE.md is for ALWAYS-LOADED universal standards — the conventions and facts that should apply to everything Claude does in the project ('we use 2-space indentation', 'API handlers live in src/api'). A skill is for ON-DEMAND task workflows — a procedure Claude should follow only when doing that particular task (a deploy sequence, a review checklist). Put a multi-step task procedure in CLAUDE.md and you waste context on it every session even when you're not doing that task; put always-on reference in a skill and Claude won't have it when it's needed because the skill isn't invoked.

How does a skill get invoked? Two ways: you type its command (/review), OR Claude auto-invokes it when your request matches the skill's description (this is why a good description matters, echoing the tool-description lesson 2.1). For a personal twist that doesn't disturb teammates, create a personal VARIANT of a skill in ~/.claude/skills/ with a DIFFERENT name — your customization lives alongside, without overriding the shared one.

The 3.2 traps test scope (project vs user), the skill-vs-CLAUDE.md choice, and the frontmatter options. Keep the project/user split and the always-on/on-demand distinction crisp.

• •Wrong scope for a team command. ✗ Putting a team /review in ~/.claude/commands/ (personal). ✓ .claude/commands/ in the project, committed to git.
• •Skills as always-on guidance. ✗ Using a skill for universal standards Claude needs every session. ✓ That's CLAUDE.md; skills load on demand.
• •Task procedures in CLAUDE.md. ✗ Putting a multi-step deploy procedure in CLAUDE.md (wastes context). ✓ Make it a skill, invoked when deploying.
• •Not isolating verbose skills. ✗ A codebase-analysis skill dumping output into the main context. ✓ Use context: fork to run it isolated.

You now understand the on-demand layer: where commands/skills live, the three frontmatter options, and when to choose a skill over CLAUDE.md. The exercise builds one of each and exercises the frontmatter that the exam highlights.

CLAUDE.md (always-on) and skills (on-demand) are two of the three configuration layers. The third — conditional, path-based loading — is the next lesson, 3.3: rules that load only when Claude touches certain files.