Custom slash commands and skills

What you’ll be able to do

• Choose project scope (.claude/commands/, .claude/skills/) or user scope (~/.claude/…) for a command or skill
• Use context: fork to keep verbose or exploratory skill output out of the main conversation
• Restrict a skill’s tools with allowed-tools and prompt for required input with argument-hint
• Create a personal variant of a team skill without affecting teammates
• Decide whether guidance belongs in a skill (on demand) or CLAUDE.md (always loaded)

What you need to know

Where a command or skill lives decides who gets it

Custom slash commands and skills follow the same sharing rule as CLAUDE.md: anything in the repository is shared through version control, and anything in your home directory is yours alone.

• Project-scoped commands — .claude/commands/. A file such as .claude/commands/review.md becomes a /review command for everyone who clones or pulls the repo. Use this for team-wide workflows like the standard review checklist.
• User-scoped commands — ~/.claude/commands/. Personal commands that follow you across projects and are never shared.
• Skills — .claude/skills/. Each skill is a directory containing a SKILL.md file: YAML frontmatter for configuration, followed by the instructions. Project skills are shared the same way project commands are.
• Personal skills — ~/.claude/skills/. Your own skills, invisible to teammates.

If you want a team skill to behave differently for you, for example a stricter or terser version of the shared review skill, don't edit the shared file, and don't reuse its name. Create a personal variant in ~/.claude/skills/ with a different name. The team's version stays as it is for everyone else, and both are available to you without ambiguity.

SKILL.md frontmatter: three options the exam names

context: fork — run the skill in an isolated sub-agent context. By default a skill runs inline: everything it reads and prints goes into the main conversation. That's a problem for skills that produce a lot of output. A codebase-analysis skill that reads forty files, run a few times in a long session, piles up overlapping reports until the early specifics are buried. With context: fork, the skill does its work in a separate context and only its result comes back. Use it for two kinds of skill:

• Verbose output, such as codebase analysis or dependency mapping, where the main session needs the summary, not the transcript.
• Exploratory context, such as brainstorming alternative designs, where the side paths you rejected shouldn't keep steering the main session.

Forking isn't free. The forked context doesn't share the main conversation's history, so the skill has to get what it needs from its arguments and its own reading. A skill whose output is the deliverable, like a short drafted paragraph, gains little from it.

allowed-tools — restrict what the skill can do while it runs. List only the tools the skill needs. A skill that generates scaffolding files can be limited to reading and writing files, so it can't run shell commands or take destructive actions. A read-only analysis skill can be limited to read and search tools. This is a configuration guarantee, not a request in the instructions.

argument-hint — prompt for required parameters. If a skill needs an input, such as a module path or a ticket ID, argument-hint shows developers what to supply when they invoke it without arguments. Otherwise the skill either guesses or fails partway through.

Skill or CLAUDE.md?

The two have different loading behavior, which decides what goes where:

• CLAUDE.md is always loaded. Use it for universal standards that should shape every session: naming conventions, the test command, architectural rules.
• A skill is invoked on demand. Use it for a task-specific workflow that matters only when someone runs it: a release checklist, a migration procedure, a codebase audit.

A twelve-step release procedure in CLAUDE.md costs context in every session, including the many that have nothing to do with releases. A coding standard packaged as a skill applies only when someone remembers to invoke it. Each mistake turns the other's strength into a weakness.

Key concept

Location decides sharing: .claude/ for the team, ~/.claude/ for you, with a different name for personal variants. In SKILL.md, context: fork isolates verbose or exploratory work, allowed-tools restricts what the skill can do, and argument-hint prompts for required input. Workflows go in skills; universal standards go in CLAUDE.md.

When a scenario describes a skill flooding the main session, look for context: fork. When it describes a skill doing more than it should, look for allowed-tools.

Practice scenario

Build exercise — Ship a team skill and a personal variant

Intermediate · 30 min

What you’ll learn

• Configuring context: fork, allowed-tools, and argument-hint together
• Seeing the difference between inline and forked skill output in the main session
• Keeping a personal variant from affecting the shared version

1. Create .claude/skills/map-module/SKILL.md with argument-hint for the module path and allowed-tools limited to read and search tools. Invoke it once with no arguments and once with a path.

   • Why: You’re checking that the hint prompts for the missing input and that the restriction holds while the skill runs.
   • You should see: The hint appear when the argument is missing, and the skill read and search without trying to edit files or run commands.

2. Run the skill on a large module without context: fork, then add context: fork and run it again.

   • Why: The difference in what lands in the main conversation is the whole case for forking a verbose skill.
   • You should see: The inline run leave a long trail of reads and reasoning in the session; the forked run return only the short summary.

3. Copy the skill to ~/.claude/skills/ under a new name and change its summary format. Confirm the project version is unchanged.

   • Why: Personal customization must not change what teammates get when they pull.
   • You should see: Both skills available to you, and git status showing nothing changed in .claude/skills/.

Exam traps

Putting a team-wide command in ~/.claude/commands/, where only you can use it

User-scoped commands are personal and not version-controlled. Team commands go in the repository’s .claude/commands/.

Editing the shared team skill to suit personal preferences instead of creating a differently named personal variant

Changing the shared file changes it for everyone. A personal variant in ~/.claude/skills/ with a different name leaves the team’s version alone.

Letting a codebase-analysis skill run inline so its verbose output floods the main conversation

Inline skills leave everything they produce in the main context. context: fork runs the work in an isolated sub-agent context and returns only the result.

Assuming a skill is isolated or tool-restricted by default without setting context: fork or allowed-tools

Both are opt-in frontmatter settings. Without them, the skill runs in the main conversation with the session’s normal tool access.

Relying on developers to remember a skill’s required parameter instead of setting argument-hint

argument-hint prompts for the missing input at invocation time, so the skill doesn’t have to guess.

Putting an occasional, task-specific workflow in CLAUDE.md so it loads in every session

CLAUDE.md is always loaded and is for universal standards. Task-specific workflows belong in skills that load on demand.

Sources

• Claude Code Docs
• Anthropic, Claude Certified Architect – Foundations Exam Guide v1.0 (July 2026)