Create and configure custom slash commands and skills

A custom slash command is just a Markdown file whose filename becomes the command name. Put review.md in a directory and you get a /review command that inserts that file's contents as a prompt. The only question that decides who can run it is which directory it lives in.

Project-scoped commands live in .claude/commands/ inside the repository. Because that directory is committed, every developer who clones or pulls the repo automatically gets the command, with no per-machine setup. This is the correct home for anything the team should share: a standard code-review checklist, a release-notes generator, a test-scaffolding prompt.

User-scoped commands live in ~/.claude/commands/ in an individual developer's home directory. These are personal and are never shared through version control. Use this scope for your own shortcuts that teammates neither need nor should inherit.

Watch for the classic distractor: there is no .claude/config.json with a commands array, and CLAUDE.md is for project context and instructions, not command definitions. Commands are files in a commands/ directory, full stop.

A command is Markdown with optional YAML frontmatter. The body is the prompt; the frontmatter tunes behavior. A minimal team command looks like this:

---
description: Run the team's standard code-review checklist
argument-hint: <path-to-changed-files>
allowed-tools: Read, Grep, Glob
---
Review the changes in $ARGUMENTS against our checklist:
- correctness and edge cases
- security (injection, authz)
- test coverage

$ARGUMENTS captures everything the user typed after the command; $1, $2 capture positional arguments. You can also embed live context: a line beginning with ! runs a shell command and includes its output, and @path/to/file inlines a file. Subdirectories create namespaces, so .claude/commands/frontend/component.md becomes /frontend:component.

Keep commands focused. A command is essentially a saved, parameterized prompt, so the value is in encoding the exact wording and criteria your team agreed on, not in trying to make one command do everything.

Skills are the richer sibling of slash commands. A skill is a directory under .claude/skills/ (project) or ~/.claude/skills/ (personal), containing a SKILL.md file plus any supporting scripts or resources the workflow needs. The SKILL.md frontmatter carries a name and a description, and the description is what lets Claude invoke the skill on demand when a task matches, rather than requiring the developer to remember to trigger it.

That on-demand nature is the key architectural difference from CLAUDE.md. Skills load only when they are relevant, so a large library of specialized workflows costs nothing until one is actually used. Beyond name and description, SKILL.md frontmatter supports three configuration options worth memorizing for this task: context: fork, allowed-tools, and argument-hint.

Think of a skill as a self-contained, reusable capability (analyze a module, scaffold a service, run a migration playbook) that bundles instructions and tooling, where a slash command is a lighter-weight saved prompt. Both come in project and user scopes governed by the same directory rule as commands.

Some skills generate a lot of intermediate output. A codebase-analysis skill might read dozens of files; a brainstorming skill might explore several discarded alternatives. If that all lands in the main conversation, it burns context-window budget and buries the actual answer under exploration noise.

Setting context: fork in the skill's frontmatter runs the skill in an isolated sub-agent context. The skill does its verbose work in that separate context and returns only its result to the main session, so the exploratory detail never pollutes the primary conversation.

---
name: analyze-module
description: Deep-analyze a module and report its public API and dependencies
context: fork
argument-hint: <module-path>
---

Reach for context: fork whenever a skill's process is noisy but its output is compact: codebase discovery, dependency tracing, generating and comparing options. It is the skill-level equivalent of delegating to a sub-agent to protect the main context, and it pairs naturally with the Explore-style discovery patterns used elsewhere in Claude Code.

allowed-tools restricts which tools a skill (or command) may use while it runs. This is a safety fence, not a convenience: a scaffolding skill that should only create files can be limited to Write, Edit so it cannot run Bash and delete something. A read-only audit skill can be limited to Read, Grep, Glob. Restricting tools in the frontmatter is a deterministic guardrail, unlike a prompt instruction that merely asks the model to behave.

---
name: scaffold-endpoint
description: Generate a new API endpoint from our template
allowed-tools: Read, Write, Edit
argument-hint: <resource-name>
---

argument-hint declares the parameters a skill expects. When a developer invokes the skill without supplying them, the hint is surfaced to prompt for the required input, so the skill does not silently run on missing or wrong arguments. Together, allowed-tools bounds what the skill can do and argument-hint clarifies what it needs, which are the two most common reliability fixes for a skill that either does too much or receives too little.

Suppose a shared project skill mostly works for you but you want a stricter or differently tuned version. The wrong move is editing the committed .claude/skills/ file, because that change ships to everyone through version control and silently alters their behavior.

The correct move is to create a personal variant in ~/.claude/skills/ under a different name. Because it lives in your user scope, it is yours alone, and because it has a distinct name it does not shadow or collide with the team skill. You get your customization while the shared workflow stays stable for the rest of the team.

This mirrors the command scoping rule and the CLAUDE.md hierarchy from task 3.1: user scope is private, project scope is shared, and you never fork team behavior by mutating the shared artifact in place.

A recurring exam decision is whether a piece of guidance belongs in a skill or in CLAUDE.md. The dividing line is when it should be active.

CLAUDE.md is always loaded into every session, so it is the right place for universal standards that apply to essentially all work: code style, repo conventions, non-negotiable rules. The cost is that everything in it consumes context on every turn, whether relevant or not.

Skills are invoked on demand for a specific task, so they are the right place for task-specific workflows: a migration procedure, a specialized generator, an analysis playbook. They cost nothing until triggered, which lets you maintain a large catalog of specialized capabilities without bloating baseline context.

So: universal and always-relevant goes in CLAUDE.md; specialized and occasionally-needed goes in a skill. If you find yourself wrapping a rarely-used procedure in CLAUDE.md 'so Claude always knows it,' that is usually a skill.