Creating Commands

When this skill is invoked, Claude Code provides the base directory. Throughout this skill, we refer to it as ${SKILL_DIR}.

Reference files: ${SKILL_DIR}/references/

IMPORTANT: Do NOT search the project directory for skill files. If you cannot find a file, use Glob: .claude/plugins/cache/**/creating-commands/**/*.md

Create effective slash commands for Claude Code that enable users to trigger reusable prompts with /command-name syntax. Slash commands expand as prompts in the current conversation, allowing teams to standardize workflows and operations. This skill teaches you to structure commands with XML tags, YAML frontmatter, dynamic context loading, and intelligent argument handling.

1. Create .claude/commands/ directory (project) or use ~/.claude/commands/ (personal)
2. Create command-name.md file
3. Add YAML frontmatter (at minimum: description)
4. Write command prompt
5. Test with /command-name [args]

File: .claude/commands/optimize.md

---
description: Analyze this code for performance issues and suggest optimizations
---

Analyze the performance of this code and suggest three specific optimizations:

Usage: /optimize

Claude receives the expanded prompt and analyzes the code in context.

All generated slash commands should use XML tags in the body (after YAML frontmatter) for clarity and consistency.

`` - What the command does and why it matters

What needs to happen and why this matters.
Context about who uses this and what it accomplishes.

` or ` - How to execute the command

Sequential steps to accomplish the objective:
1. First step
2. Second step
3. Final step

`` - How to know the command succeeded

Clear, measurable criteria for successful completion.

`` - When loading dynamic state or files

Current state: ! `git status`
Relevant files: @ package.json

(Note: Remove the space after @ in actual usage)

`` - When producing artifacts that need checking

Before completing, verify:
- Specific test or check to perform
- How to confirm it works

`` - When running tests is part of the workflow

Run tests: ! `npm test`
Check linting: ! `npm run lint`

`` - When creating/modifying specific files

Files created/modified:
- `./path/to/file.ext` - Description

---
name: example-command
description: Does something useful
argument-hint: [input]
---

Process $ARGUMENTS to accomplish [goal].

This helps [who] achieve [outcome].

Current state: ! `relevant command`
Files: @ relevant/files

1. Parse $ARGUMENTS
2. Execute operation
3. Verify results

- Operation completed without errors
- Output matches expected format

Simple commands (single operation, no artifacts):

• Required: `, , `
• Example: /check-todos, /first-principles

Complex commands (multi-step, produces artifacts):

• Required: `, , `
• Add: ` (if loading state), (if creating files), ` (what gets created)
• Example: /commit, /create-prompt, /run-prompt

Commands with dynamic arguments:

• Use $ARGUMENTS in ` or ` tags
• Include argument-hint in frontmatter
• Make it clear what the arguments are for

Commands that produce files:

• Always include `` tag specifying what gets created
• Always include `` tag with checks to perform

Commands that run tests/builds:

• Include `` tag with specific commands
• Include pass/fail criteria in ``

Determine whether a command needs arguments:

Needs arguments — task operates on user-specified data:

• Use $ARGUMENTS for single input: Fix issue #$ARGUMENTS
• Use $1, $2, $3 for structured input: Review PR #$1 with priority $2
• Add argument-hint in frontmatter

No arguments — task operates on implicit context (conversation, known files, project state):

• Omit argument-hint and don't reference $ARGUMENTS

For detailed examples and patterns, see [${SKILL_DIR}/references/arguments.md](references/arguments.md).

Project commands: .claude/commands/

• Shared with team via version control
• Shows (project) in /help list

Personal commands: ~/.claude/commands/

• Available across all your projects
• Shows (user) in /help list

File naming: command-name.md → invoked as /command-name

Required - Describes what the command does

description: Analyze this code for performance issues and suggest optimizations

Shown in the /help command list.

Optional - Tells users what arguments the command expects

argument-hint: [issue-number]
argument-hint:   

Shown in autocomplete. Omit for self-contained commands that don't take arguments.

Optional - Restricts which tools Claude can use

allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)

Formats:

• Array: allowed-tools: [Read, Edit, Write]
• Single tool: allowed-tools: SequentialThinking
• Bash restrictions: allowed-tools: Bash(git add:*)

If omitted: All tools available

Execute bash commands before the prompt using the exclamation mark prefix directly before backticks (no space between).

Note: Examples below show a space after the exclamation mark to prevent execution during skill loading. In actual slash commands, remove the space.

Example:

---
description: Create a git commit
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
---

- Current git status: ! `git status`
- Current git diff: ! `git diff HEAD`
- Current branch: ! `git branch --show-current`
- Recent commits: ! `git log --oneline -10`

Based on the above changes, create a single git commit.

The bash commands execute and their output is included in the expanded prompt.

Use @ prefix to reference specific files:

---
description: Review implementation
---

Review the implementation in @ src/utils/helpers.js

(Note: Remove the space after @ in actual usage)

Claude can access the referenced file's contents.

1. Always use XML structure

# All slash commands should have XML-structured bodies

After frontmatter, use XML tags:

• `` - What and why (always)
• `` - How to do it (always)
• `` - Definition of done (always)
• Additional tags as needed (see xml_structure section)

2. Clear descriptions

# Good
description: Analyze this code for performance issues and suggest optimizations

# Bad
description: Optimize stuff

3. Use dynamic context for state-dependent tasks

Current git status: ! `git status`
Files changed: ! `git diff --name-only`

4. Restrict tools when appropriate

# For git commands - prevent running arbitrary bash
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)

# For analysis - thinking only
allowed-tools: SequentialThinking

5. Use $ARGUMENTS for flexibility

Find and fix issue #$ARGUMENTS

6. Reference relevant files

Review @ package.json for dependencies
Analyze @ src/database/* for schema

(Note: Remove the space after @ in actual usage)

Common command patterns with full examples are in [${SKILL_DIR}/references/patterns.md](references/patterns.md):

• Simple analysis — single operation, no state (e.g., security review)
• Git workflow — state-dependent with ` and allowed-tools`
• Parameterized — uses $ARGUMENTS with argument-hint
• File-specific — combines @ $ARGUMENTS file references with analysis

Arguments reference: [${SKILL_DIR}/references/arguments.md](references/arguments.md)

• $ARGUMENTS variable
• Positional arguments ($1, $2, $3)
• Parsing strategies
• Examples from official docs

Patterns reference: [${SKILL_DIR}/references/patterns.md](references/patterns.md)

• Git workflows
• Code analysis
• File operations
• Security reviews
• Examples from official docs

Tool restrictions: [${SKILL_DIR}/references/tool-restrictions.md](references/tool-restrictions.md)

• Bash command patterns
• Security best practices
• When to restrict tools
• Examples from official docs

1. Analyze: Determine purpose, whether arguments are needed, complexity level (simple vs. complex), and security profile
2. Frontmatter: Add description (required), argument-hint (if arguments needed), allowed-tools (if tool restrictions needed)
3. Body: Use XML tags — always `, , ; add , , , as needed (see `)
4. Arguments: Use $ARGUMENTS or positional $1/$2 in tags (see ``)
5. Save: Project commands in .claude/commands/, personal in ~/.claude/commands/

A well-structured slash command meets these criteria:

YAML Frontmatter:

• description field is clear and concise
• argument-hint present if command accepts arguments
• allowed-tools specified if tool restrictions needed

XML Structure:

• All three required tags present: `, , `
• Conditional tags used appropriately based on complexity
• No raw markdown headings in body
• All XML tags properly closed

Arguments Handling:

• $ARGUMENTS used when command operates on user-specified data
• Positional arguments ($1, $2, etc.) used when structured input needed
• No $ARGUMENTS reference for self-contained commands

Functionality:

• Command expands correctly when invoked
• Dynamic context loads properly (bash commands, file references)
• Tool restrictions prevent unauthorized operations
• Command accomplishes intended purpose reliably

Quality:

• Clear, actionable instructions in `` tag
• Measurable completion criteria in ``
• Appropriate level of detail (not over-engineered for simple tasks)
• Examples provided when beneficial

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: outcomeeng
• Source: outcomeeng/claude
• License: MIT

Install and usage instructions live in the source repository linked above.