Create and Configure Custom Slash Commands and Skills
This module is about turning repeated Claude Code workflows into reusable, scoped commands or skills.
- 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)
Heuristic:
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
2.1 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)
2.2 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
Heuristic:
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)
4.1 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 a skill with a distinct name:
Why distinct name?
- Avoids overriding or confusing the shared team skill.
- Keeps personal preferences personal.
- Prevents changing teammate behavior.
Heuristic:
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
- context: fork runs the skill in a forked subagent context. (Claude)
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:
Heuristic:
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.
Expectation:
- Use allowed-tools to keep the skill’s tool surface narrow.
- Avoid broad Bash access unless the workflow truly needs it.
Important nuance:
Claude Code docs say
allowed-toolspre-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, usedisallowed-toolsor broader permission settings. (Claude)
Safe wording:
allowed-toolsis the frontmatter field the exam expects you to use to pre-approve the skill’s intended tool surface. In production, remember that true denial requires permissions ordisallowed-tools.
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 a map for a requested subsystem.
argument-hint: "[subsystem]"
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)
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
6.1 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:
6.2 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)
7. Skill Vs CLAUDE.md
7.1 Put In CLAUDE.md:
- Repository layout
- Build commands
- Test commands
- Coding standards
- Naming conventions
- Architecture principles
- Universal project rules
7.2 Put in a Skill:
- Repeated checklist
- Multi-step workflow
- Codebase analysis procedure
- PR review process
- Migration generator
- Release preparation workflow
- Security audit workflow
Heuristic:
Do not put a long procedural workflow into always-loaded CLAUDE.md. If it is only needed occasionally. Make it a skill.