Slash Commands & Skills
Build reusable, on-demand workflows with skills and slash commands — and know why they differ from always-on CLAUDE.md guidance.
Where CLAUDE.md supplies always-on background knowledge, skills and slash commands package *on-demand* procedures you invoke by name. Both surface as /commands, but they differ in file structure — and knowing which is which is a reliable exam point.
Two file shapes, one command system
- Skill (canonical) — a *directory* containing a
SKILL.mdentrypoint, e.g..claude/skills/deploy/SKILL.md. The directory can hold supporting files alongside the entrypoint. - Command (legacy alias) — a *flat* Markdown file, e.g.
.claude/commands/deploy.md. Dropping a bare.mdfile directly into.claude/skills/does not create a command.
Drop a flat deploy.md into .claude/skills/. Skills are not flat files, so this creates no command at all.
.claude/skills/deploy.md # creates nothingGive the skill its own directory with a SKILL.md entrypoint. The folder can also bundle supporting files.
.claude/skills/deploy/SKILL.md # valid /deployA flat deploy.md inside .claude/skills/ creates nothing. Skills need a directory with SKILL.md; only .claude/commands/ accepts flat Markdown files.
Scoping: shared vs personal
The scoping rule matches CLAUDE.md: anything under the repo's .claude/ is committed and shared via git; anything under ~/.claude/ is personal. Put team workflows like /review or /deploy-check in the project; keep personal productivity commands in your home directory.
Skill frontmatter that matters
A skill's YAML frontmatter tunes how it runs. Three fields show up repeatedly on the exam:
- `context: fork` — runs the skill in an isolated sub-agent so verbose output stays contained and the main conversation stays clean. Ideal for codebase analysis or brainstorming.
- `allowed-tools` — pre-approves the listed tools so the skill can use them without a permission prompt. It does not restrict other tools; they remain callable under normal settings.
- `argument-hint` — prompts the developer for required parameters when the skill is invoked without arguments.
---
name: deploy-check
description: Run the pre-deploy checklist for this service.
context: fork
allowed-tools: [Bash, Read, Grep]
argument-hint: <environment>
---
# Deploy Check
1. Run the test suite and report failures.
2. Verify the migration list against $ARGUMENTS.
3. Summarize readiness in a short checklist.Skills vs CLAUDE.md
The dividing line is timing. Skills are task-specific and load on demand — only the short description sits in context until you invoke the skill (explicitly or by intent match), at which point the full body loads. CLAUDE.md is always-loaded reference material applied to every session. So: don't bury task procedures in CLAUDE.md, and don't turn a skill into always-on guidance.
Skills = on-demand workflows whose body loads only when invoked. CLAUDE.md = always-on standards. Matching the mechanism to the need is the recurring test theme.
A crisp description helps Claude auto-select the right skill without an explicit /name. Say what the skill does and when to use it.
How the exam will try to trick you
The distractors below look right under time pressure — learn the tell.
- The trap
Dropping a flat
deploy.mdinto.claude/skills/creates a/deploycommand.Correct answerSkills need a directory with a
SKILL.mdentrypoint (e.g..claude/skills/deploy/SKILL.md); flat.mdfiles only work in.claude/commands/.Why: A loose file inside
.claude/skills/is not recognized and creates no command at all. - The trap
Put team-shared commands in
~/.claude/commands/so the whole team can use them.Correct answerTeam commands belong under the project's
.claude/commands/or.claude/skills/, which git shares on clone.Why: User-scope paths are personal and never version-controlled, so teammates never receive them.
- The trap
Skills behave like
CLAUDE.md, automatically applying to every session.Correct answerSkills load on demand — only their description sits in context until you invoke them explicitly or by intent match.
Why: Skills are task-specific workflows, not always-on standards; use
CLAUDE.mdor.claude/rules/for every-session guidance. - The trap
A verbose brainstorming or codebase-analysis skill runs fine without
context: fork.Correct answerAdd
context: forkso the skill runs in an isolated sub-agent and its verbose output stays out of the main conversation.Why: Without isolation the exploratory output floods the context window and degrades response quality.
Key takeaways
- Skills are directories with a SKILL.md; commands are flat Markdown files.
- A flat .md inside .claude/skills/ creates nothing.
- Project .claude/ is shared via git; ~/.claude/ is personal.
- context: fork isolates verbose output in a sub-agent.
- allowed-tools pre-approves tools; argument-hint prompts for inputs.
- Skills load on demand; CLAUDE.md is always loaded.
Frequently asked questions
How do Claude Code slash commands work?+
You define a workflow as a skill directory (SKILL.md) or a flat command file under .claude/, then invoke it as /name in a session. Claude loads the full body on invocation and follows the steps, optionally taking arguments.
What is the difference between a skill and a slash command?+
They produce the same /commands but differ structurally. A skill is a directory containing SKILL.md and can bundle supporting files; a command is a single flat Markdown file. Skills are the canonical form; commands are a legacy alias.
When should I use a skill instead of CLAUDE.md?+
Use a skill for a task-specific procedure you run occasionally, so its body only consumes context when invoked. Use CLAUDE.md for always-on standards that should apply to every session automatically.