Custom Slash Commands & Skills

Slash commands and skills are how teams encode reusable workflows in Claude Code. This lesson covers the difference between project and personal commands, skill frontmatter options, and when to use each.

Project vs Personal Commands and Skills

Type	Path	Scope
Project commands	`.claude/commands/`	Version-controlled, shared with team
Personal commands	`~/.claude/commands/`	Personal only
Project skills	`.claude/skills/<name>/SKILL.md`	Version-controlled
Personal skills	`~/.claude/skills/<name>/SKILL.md`	Personal variants

Skill Frontmatter

Skills accept frontmatter that controls execution:

---
context: fork              # Runs in isolated sub-agent context
allowed-tools:             # Restricts available tools
  - Read
  - Write
argument-hint: "path to analyze (default: ./src)"
---

context: fork

The context: fork option runs the skill in an isolated sub-agent. Verbose discovery output stays in the fork; only the skill's summary returns to the main session. This prevents context pollution when the skill produces a lot of intermediate work.

allowed-tools

Restricts which tools the skill can call. A documentation-generator skill might only need Read and Write — no Bash, no Edit. Restricting tools prevents the skill from doing things outside its scope.

argument-hint

The hint shown when the user invokes the skill — describes expected arguments and defaults.

Skills vs CLAUDE.md

Use Skills for	Use CLAUDE.md for
On-demand task-specific workflows	Always-loaded universal standards
"Generate API client from OpenAPI spec"	"All commits use Conventional Commits format"
Verbose discovery (use `context: fork`)	Persistent context Claude needs every interaction

Team-Wide Commands Belong in the Repo

If your team wants everyone to have a /review command, it goes in .claude/commands/review.md in the project repo — version-controlled. Putting it in ~/.claude/commands/ keeps it personal; new team members won't get it without manual setup.

Skills File Structure

.claude/
  skills/
    review-pr/
      SKILL.md            # Skill definition + instructions
      examples/           # Optional: reference material the skill can read
        example1.md
        example2.md
      checklist.md        # Optional: structured outputs the skill follows

The SKILL.md file is required. Supporting files in the same directory are read by the skill at runtime.

Skills to Develop

Place team-wide commands in .claude/commands/ in the repo, not in ~/.claude/commands/.
Use context: fork for skills that produce verbose intermediate work.
Restrict skill allowed-tools to the minimum set needed.
Choose skills for on-demand workflows; choose CLAUDE.md for always-loaded standards.

Exam tip (Q4): A team-wide /review command goes in .claude/commands/ within the project repo. ~/.claude/commands/ is for personal commands only.