Custom slash commands and skills

Scope first

Commands in .claude/commands/ are project-scoped and shared through version control. Commands in ~/.claude/commands/ are yours alone. Same split as CLAUDE.md, same failure mode when you pick the wrong one.

For a personal variant of a shared skill, create it in ~/.claude/skills/ under a different name. Editing the shared one to suit yourself changes it for everybody.

One namespace, two places to define things

Commands and skills feed the same slash-command surface, so the same name in either place produces the same command:

.claude/commands/review.md      ->  /review
.claude/skills/review/SKILL.md  ->  /review

Two definitions claiming one invocation name is a collision the team has to resolve rather than a fallback arrangement. Migrating a command into a skill means retiring the old file in the same change.

Skill frontmatter worth knowing

A portable skill at .claude/skills/database-migration/SKILL.md keeps its identity and configuration in frontmatter:

---
name: database-migration
description: Runs the team's database migration workflow.
when_to_use: When adding, altering, or rolling back a migration.
context: fork
allowed-tools: Read, Grep, Bash
argument-hint: "[migration-name]"
---

• name is the skill's portable identifier. The open Agent Skills specification requires it, limits it to 1-64 lowercase letters, numbers, and hyphens, and requires it to match the parent directory. Agents load name and description during discovery before opening the full instructions, so an explicit name gives tools a stable identity to index and validate. Claude Code can fall back to the directory name for a local or project skill, but relying on that fallback makes the file non-conformant with the portable standard. For these skills, the directory still determines the slash command.
• description and when_to_use help Claude decide when to select a skill. In when_to_use, list the situations that should trigger the skill instead of repeating what it does. Otherwise, the skill may be found only when someone already knows to request it. The directory name is the command you type.
• context: fork runs the skill in an isolated subagent context, so its intermediate work doesn't fill the main conversation. Use it for tasks such as codebase analysis or exploratory research when the main conversation needs the conclusion but not every step used to reach it.
• allowed-tools temporarily pre-approves the listed tools for the turn that invokes the skill. It does not remove other tools. Use disallowed-tools or permission deny rules when a capability must be unavailable.
• argument-hint is autocomplete text showing the expected arguments. It neither validates them nor prompts interactively when one is missing. The skill body or its invoked script must validate required inputs and fail clearly.

A skill is invocable both by name and by Claude judging it relevant; user-invocable and disable-model-invocation turn one of those off, never on.

Skill or CLAUDE.md?

The distinction is when it applies.

CLAUDE.md is always loaded — it belongs to universal standards that should hold for every interaction. A skill is invoked on demand — it belongs to a task-specific workflow you want available but not always present.

Putting an occasional workflow in CLAUDE.md makes it load on every turn. Put that workflow in a skill so it loads only when it is needed.