Create and Configure Custom Slash Commands and Skills
This module is about turning repeated Claude Code workflows into reusable, scoped commands or skills.
The exam will likely ask questions like:
Should this be a CLAUDE.md rule, a slash command, or a skill?
Should it live in .claude/commands/ or ~/.claude/commands/?
Should it run inline or with context: fork?
Should it have argument-hint?
Should allowed-tools be narrow or broad?
How do you customize a shared skill without affecting teammates?
Current Claude Code docs note that custom commands have effectively merged into skills: a file like .claude/commands/deploy.md and a skill like .claude/skills/deploy/SKILL.md both create /deploy, and existing .claude/commands/ files still work.
Skills are now recommended for richer workflows because they support frontmatter, supporting files, automatic invocation, and subagent execution. (Claude)
1. Core mental model
Use these three mechanisms differently:
| Mechanism | Best for | Loads when? |
|---|---|---|
CLAUDE.md |
Always-on project standards and durable context | At session/context load |
| Slash command | Explicit user-triggered prompt template | When user types /command |
| Skill | Reusable task-specific workflow, often auto-invoked | Metadata visible; body loads when invoked |
Claude Code docs say skills are useful when you keep pasting the same checklist, prompt, or multi-step procedure, or when a section of CLAUDE.md has become a procedure rather than a fact. Unlike CLAUDE.md, a skill body loads only when used, so long procedural material does not cost context until needed. (Claude)
Exam shortcut:
Universal standard? CLAUDE.md.
Reusable explicit workflow? Slash command or skill.
Reusable workflow with metadata, tools, files, or forked execution? Skill.
2. Project-scoped vs user-scoped slash commands
Project-scoped commands
Put team-wide commands here:
Example:
Use project-scoped commands when:
The workflow should be shared by the team.
The command should be version-controlled.
The command reflects project-specific conventions.
New teammates should receive it automatically.
Example .claude/commands/review-diff.md:
---
description: Review the current git diff for correctness, tests, and risky changes.
argument-hint: "[optional focus area]"
allowed-tools: Bash(git diff *) Read Grep Glob
---
Review the current git diff.
Focus on: $ARGUMENTS
Check:
1. Correctness bugs
2. Missing tests
3. Backward compatibility risks
4. Security-sensitive changes
5. Whether the change follows project conventions
Use `git diff` to inspect the current changes.
Return findings grouped by severity.
This creates:
Claude Code command names come from file or directory names: a file under .claude/commands/deploy.md creates /deploy; a skill directory like .claude/skills/deploy-staging/SKILL.md creates /deploy-staging. (Claude)
User-scoped commands
Put personal commands here:
Use user-scoped commands when:
The workflow is personal.
It reflects your own preferences.
It should apply across projects.
It should not be committed or shared with teammates.
Example:
Good personal command:
---
description: Generate a commit summary in my preferred format.
argument-hint: "[optional scope]"
---
Summarize the current changes using my preferred commit format:
type(scope): short summary
Focus area: $ARGUMENTS
Exam trap:
If a teammate needs the command, do not put it in
~/.claude/commands/. Put it in.claude/commands/or, preferably for richer workflows,.claude/skills/.
3. Skills: directory + SKILL.md
A skill is a directory containing a required SKILL.md.
Example:
Claude Code docs say every skill needs a SKILL.md file with YAML frontmatter between --- markers and markdown instructions; the directory name becomes the command you type, and the description helps Claude decide when to load it automatically. (Claude)
Minimal skill:
---
description: Summarize a pull request and identify risky changes. Use when asked to review or summarize PR changes.
argument-hint: "[PR number or branch]"
---
Summarize the pull request identified by $ARGUMENTS.
Return:
1. What changed
2. Risky files
3. Test coverage gaps
4. Suggested reviewer focus areas
Invoked as:
4. Skill locations and sharing
| Location | Scope | Use for |
|---|---|---|
.claude/skills/<skill-name>/SKILL.md |
Project | Team-shared project workflow |
~/.claude/skills/<skill-name>/SKILL.md |
User | Personal workflow across projects |
Nested package .claude/skills/ |
Package/subdirectory | Monorepo package-specific skill |
Claude Code docs list personal skills under ~/.claude/skills/, project skills under .claude/skills/, and plugin skills under plugin directories. They also note that if skills share names across levels, enterprise overrides personal, personal overrides project, and any user/project skill can override a bundled skill with the same name. (Claude)
Exam trap: personal customization
Suppose the team has:
You want your own variant. Do not edit the shared skill unless the whole team should change. Instead create:
or another distinct name.
Why distinct name?
Avoids overriding or confusing the shared team skill.
Keeps personal preferences personal.
Prevents changing teammate behavior.
Exam answer pattern:
Create a personal variant in
~/.claude/skills/with a different name, rather than modifying the project-scoped skill.
5. Frontmatter fields you must know
The official task statement emphasizes:
Current Claude Code docs list these in skill frontmatter: argument-hint shows expected arguments in autocomplete, allowed-tools lists tools Claude can use without asking permission when the skill is active, and context: fork runs the skill in a forked subagent context. (Claude)
[!NOTE] Other real frontmatter fields exist beyond the three core ones. Two worth knowing: -
disable-model-invocation: true— the skill only runs when explicitly invoked (e.g. a deliberate/deploy), and is never auto-chosen by the model. Useful for side-effecting workflows that should never fire just because code "looks ready." -user-invocable: false— marks the skill as background knowledge the model may load when relevant, but not a user-facing command (it will not appear as a/commandto type).(Source basis: code.claude.com/docs/en/skills.)
5.1 argument-hint
Use argument-hint when the skill requires parameters.
Example:
---
description: Fix a GitHub issue following project conventions.
argument-hint: "[issue-number]"
---
Fix GitHub issue $ARGUMENTS.
Steps:
1. Read the issue.
2. Find relevant code.
3. Implement the fix.
4. Add or update tests.
5. Summarize changes.
When a developer types:
Claude Code can show the hint:
Use for:
[issue-number]
[component-name]
[migration-name]
[service-name] [environment]
[file-path] [output-format]
Exam trap:
If developers forget required parameters, add
argument-hint; do not rely on tribal knowledge.
5.2 allowed-tools
Use allowed-tools to shape tool access for a skill.
Example:
---
description: Generate a migration file for a named database change.
argument-hint: "[migration-name]"
allowed-tools: Read Glob Write
---
Create a new migration for: $ARGUMENTS
Steps:
1. Inspect existing migration naming patterns.
2. Create a new migration file.
3. Do not run destructive database commands.
4. Return the file path and summary.
Exam expectation:
Use allowed-tools to keep the skill’s tool surface narrow.
Avoid broad Bash access unless the workflow truly needs it.
Important current-doc nuance: Claude Code docs say allowed-tools pre-approves listed tools while the skill is active; it does not remove all other tools from availability by itself. Tools not listed still follow normal permission settings. For hard blocking, use disallowed-tools or broader permission settings. (Claude)
Exam-safe wording:
allowed-toolsis the frontmatter field the exam expects you to use to constrain/pre-approve the skill’s intended tool surface. In production, remember that true denial requires permissions ordisallowed-tools.
Bad:
Better:
or, when Bash is necessary:
5.3 context: fork
Use context: fork when the skill’s work should happen in an isolated subagent context.
Example:
---
description: Explore the codebase and produce an architecture map for a requested subsystem.
argument-hint: "[subsystem or feature]"
context: fork
agent: Explore
allowed-tools: Read Grep Glob
---
Research the subsystem: $ARGUMENTS
Steps:
1. Find entry points with Grep and Glob.
2. Read only relevant files.
3. Trace important imports and call paths.
4. Identify key components, data flow, and risks.
5. Return a concise summary with file references.
Claude Code docs say context: fork creates a new isolated context; the subagent receives the skill content as its prompt, does not have access to the main conversation history, and returns summarized results to the main conversation. (Claude)
Use context: fork for:
Verbose codebase analysis
Exploratory research
Brainstorming alternatives
Architecture mapping
Large PR summarization
Risk analysis
Work that may produce lots of intermediate context
Do not use context: fork for passive guidelines like:
Why? The forked skill needs an actionable task. Current docs explicitly say context: fork only makes sense for skills with explicit instructions; if the skill only contains guidelines, the subagent gets no task and returns without meaningful output. (Claude)
6. Slash command vs skill
Use a slash command when
The workflow is simple.
It is always manually invoked.
It does not need supporting files.
It does not need automatic invocation.
It does not need context: fork.
Example:
Use a skill when
The workflow is multi-step.
It needs a description for automatic invocation.
It needs supporting files, examples, scripts, or templates.
It needs argument hints.
It benefits from context: fork.
It needs skill-specific tool permissions.
It should be packaged as a reusable capability.
Current docs say .claude/commands/ still works and supports the same frontmatter, but skills are recommended because they support additional features like supporting files. (Claude)
Exam shortcut:
Simple explicit prompt template → slash command.
Reusable capability with metadata/files/fork/tools → skill.
Always-on rule → CLAUDE.md.
7. Skill vs CLAUDE.md
This is one of the most important D3.2 distinctions.
Put in CLAUDE.md
Repository layout
Build commands
Test commands
Coding standards
Naming conventions
Architecture principles
Universal project rules
Example:
# Testing Standard
- Add regression tests for bug fixes.
- Use Vitest in packages/api.
- Use Playwright for browser-level flows.
Put in a skill
Repeated checklist
Multi-step workflow
Codebase analysis procedure
PR review process
Migration generator
Release preparation workflow
Security audit workflow
Example:
---
description: Perform a security review of the current diff.
argument-hint: "[optional focus area]"
context: fork
allowed-tools: Read Grep Glob Bash(git diff *)
---
Review the current diff for security issues...
Exam trap:
Do not put a long procedural workflow into always-loaded CLAUDE.md if it is only needed occasionally. Make it a skill.
8. Good examples
Example 1: Project-scoped command
File:
Content:
---
description: Create a focused test plan for a feature or bug fix.
argument-hint: "[feature-or-ticket]"
allowed-tools: Read Grep Glob
---
Create a test plan for: $ARGUMENTS
Include:
1. Existing test files to inspect
2. Unit test cases
3. Integration test cases
4. Regression edge cases
5. Manual verification steps
Use Grep and Glob to find nearby tests before recommending new ones.
Best when the team wants a shared /create-test-plan.
Example 2: Project-scoped skill with forked exploration
File:
Content:
---
description: Map a requested subsystem by finding entry points, tracing imports, and summarizing architecture. Use when asked to understand a feature area or subsystem before implementation.
argument-hint: "[subsystem-or-feature]"
context: fork
agent: Explore
allowed-tools: Read Grep Glob
---
Map the subsystem: $ARGUMENTS
Instructions:
1. Start with Grep for key terms and exported names.
2. Use Glob to find likely directories and tests.
3. Read only relevant files.
4. Trace imports and wrapper modules.
5. Summarize:
- Entry points
- Core modules
- Data flow
- Important tests
- Risks or unclear areas
Return only a concise summary with file references.
Why this is strong:
Uses context: fork to prevent exploratory context from polluting the main session.
Uses narrow tools: Read, Grep, Glob.
Has argument-hint.
Has a clear task, not just passive guidelines.
Example 3: Personal variant
Shared team skill:
Your personal variant:
Content:
---
description: Personal PR review workflow with extra focus on API compatibility and migration risk.
argument-hint: "[PR number or branch]"
context: fork
allowed-tools: Bash(gh pr *) Bash(git diff *) Read Grep Glob
---
Review PR: $ARGUMENTS
Focus especially on:
1. API compatibility
2. Data migration risk
3. Error handling
4. Test coverage
5. Rollback considerations
Why this is exam-correct:
Personal behavior is in user scope.
Different name avoids overriding team behavior.
The team skill remains unchanged.
9. Common exam traps
Trap 1: Putting a team command in user scope
Wrong:
when everyone on the project needs it.
Right:
or:
Trap 2: Putting a personal variant in project scope
Wrong:
if it is only your personal preference.
Right:
Trap 3: Using CLAUDE.md for occasional long workflows
Wrong:
Right:
Trap 4: Using context: fork for passive standards
Wrong:
Right:
Use context: fork for task-oriented workflows such as exploration or analysis, not always-on standards.
Trap 5: Broad tool access
Wrong:
for a migration file generator.
Better:
or very narrow Bash patterns if needed.
Trap 6: Missing argument-hint
Wrong:
when users often invoke /generate-migration without a name.
Right:
10. Scenario-based practice questions
Question 1
A team wants every developer in a repository to have access to /prepare-release, a workflow that checks the changelog, runs release validation, and prepares release notes.
Where should it live?
A) ~/.claude/commands/prepare-release.md
B) .claude/commands/prepare-release.md or .claude/skills/prepare-release/SKILL.md
C) ~/.claude/CLAUDE.md
D) .mcp.json
Answer
B. Team-wide commands or skills should be project-scoped and version-controlled. User scope is personal and will not automatically reach teammates.
Question 2
A developer has a personal PR review style and wants a command that adds extra checks they personally care about. The team already has .claude/skills/pr-review/SKILL.md.
What should the developer do?
A) Edit the team skill directly.
B) Create a personal skill in ~/.claude/skills/ with a different name.
C) Add personal instructions to project CLAUDE.md.
D) Disable the team skill for everyone.
Answer
B. Personal customization belongs in user scope. A different skill name avoids overriding or changing the shared team workflow.
Question 3
A codebase-analysis skill produces a lot of intermediate findings and exploratory notes. Those notes pollute the main session and influence later implementation decisions.
What should you add?
A) context: fork
B) argument-hint only
C) Move it to CLAUDE.md
D) Remove its description
Answer
A. context: fork runs the skill in an isolated subagent context and returns only summarized results to the main conversation.
Question 4
A skill is invoked as /fix-issue, but developers often forget to provide the issue number.
What frontmatter should you add?
A) context: fork
B) argument-hint: "[issue-number]"
C) user-invocable: false
D) model: inherit
Answer
B. argument-hint tells users what arguments are expected when invoking the skill.
Question 5
A skill generates a new migration file. It needs to inspect existing migrations and write a new file, but it should not run destructive database commands.
Which tool configuration is best?
A) allowed-tools: Bash(*)
B) allowed-tools: Read Glob Write
C) allowed-tools: WebSearch
D) No tool constraints
Answer
B. The skill needs file inspection and file creation, not arbitrary shell access. Narrow tool access is safer and more aligned with the task.
Question 6
A long “how to perform a security review” checklist is used only occasionally, but it is currently in CLAUDE.md and consumes context every session.
What is the best change?
A) Move it into a project skill like .claude/skills/security-review/SKILL.md.
B) Move it into ~/.claude/CLAUDE.md.
C) Duplicate it in every prompt.
D) Delete all security guidance.
Answer
A. Occasional multi-step workflows belong in skills. CLAUDE.md is for always-loaded standards and project context.
Question 7
A skill contains only this:
---
context: fork
description: API conventions for this project.
---
Always return the standard error envelope.
What is the problem?
A) context: fork is unnecessary because this is passive guidance, not an actionable task.
B) The description is too long.
C) It must use Bash.
D) It must be in user scope.
Answer
A. Forked skills need explicit tasks. Passive standards should live in CLAUDE.md, rules, or a normal reference skill, not a forked subagent workflow.
Question 8
A project has both:
What should you expect?
A) The command always wins.
B) The skill takes precedence.
C) Neither will work.
D) Both run simultaneously.
Answer
B. Current Claude Code docs say if a skill and command share the same name, the skill takes precedence. (Claude)
Question 9
A workflow requires supporting files: a template, example outputs, and a validation script.
Which mechanism is best?
A) Simple .claude/commands/foo.md only
B) A skill directory under .claude/skills/foo/ with SKILL.md and supporting files
C) CLAUDE.md
D) /memory
Answer
B. Skills support a directory of supporting files, such as templates, examples, scripts, and reference docs. Commands are simpler; skills are better for packaged workflows. (Claude)
Question 10
A deploy workflow has side effects and should never be auto-invoked by Claude just because code “looks ready.”
What should you add?
A) disable-model-invocation: true
B) user-invocable: false
C) context: fork only
D) Remove the description
Answer
A. Although not in your official task statement’s core list, this is a useful related exam-adjacent concept: disable-model-invocation: true prevents Claude from automatically invoking side-effecting skills; the user must invoke them manually. Current docs specifically use deploy-like workflows as examples. (Claude)
11. High-yield checklist for D3.2
Memorize this:
1. Project commands live in .claude/commands/ and are shared via version control.
2. User commands live in ~/.claude/commands/ and are personal.
3. Project skills live in .claude/skills/<name>/SKILL.md.
4. User skills live in ~/.claude/skills/<name>/SKILL.md.
5. Skills need SKILL.md with YAML frontmatter and markdown instructions.
6. The skill directory name determines the slash command name.
7. Use argument-hint to show expected parameters.
8. Use context: fork for verbose or exploratory workflows that should not pollute the main session.
9. Do not use context: fork for passive standards with no actionable task.
10. Use allowed-tools to narrow/pre-approve the skill’s intended tools.
11. Avoid broad Bash access unless clearly necessary.
12. Create personal variants in ~/.claude/skills/ with different names.
13. Use skills for on-demand task workflows.
14. Use CLAUDE.md for always-loaded universal standards.
15. Skills are preferred over legacy custom commands when you need supporting files, auto invocation, frontmatter controls, or forked execution.
D3.2 mental model
CLAUDE.md = always-loaded project memory.
Slash command = explicit reusable prompt.
Skill = reusable capability with metadata, optional files, tool configuration, arguments, and forked execution.
Project scope = team behavior.
User scope = personal behavior.
context: fork = isolate noisy or exploratory work.
argument-hint = tell the developer what input is required.
allowed-tools = keep the workflow’s tool surface narrow.