home / skills / outfitter-dev / agents / claude-commands

claude-commands skill

/plugins/outfitter/skills/claude-commands

This skill helps you author reusable slash commands for Claude Code, enabling fast creation and management of command files.

npx playbooks add skill outfitter-dev/agents --skill claude-commands

Review the files below or copy the command above to add this skill to your agents.

Files (12)

SKILL.md

10.5 KB

---
name: claude-commands
description: This skill should be used when creating slash commands, writing command files, or when "/command", ".claude/commands", "$ARGUMENTS", or "create command" are mentioned.
metadata:
  version: "2.0.0"
  related-skills:
    - claude-hooks
    - claude-plugins
    - skills-dev
allowed-tools: Read Write Edit Grep Glob Bash TaskCreate TaskUpdate TaskList TaskGet
---

# Claude Command Authoring

Create custom slash commands that extend Claude Code with reusable prompts and workflows.

## Commands vs Skills

**Critical distinction**:

| Aspect         | Commands (This Skill)                   | Skills                                 |
| -------------- | --------------------------------------- | -------------------------------------- |
| **Purpose**    | Reusable prompts invoked by users       | Capability packages auto-triggered     |
| **Invocation** | Explicit: `/command-name args`          | Automatic (model-triggered by context) |
| **Location**   | `commands/` directory                   | `skills/` directory with `SKILL.md`    |
| **Structure**  | Single `.md` file                       | Directory with resources               |
| **Arguments**  | `$1`, `$2`, `$ARGUMENTS`                | No argument system                     |

Commands are user-initiated. Skills are model-initiated.

---

## Quick Start

### Basic Command

Create `.claude/commands/review.md`:

```markdown
---
description: Review code for best practices and issues
---

Review the following code for:
- Code quality and readability
- Potential bugs or edge cases
- Performance considerations
- Security concerns
```

Use with: `/review`

### Command with Arguments

Create `.claude/commands/fix-issue.md`:

```markdown
---
description: Fix a specific GitHub issue
argument-hint: <issue-number>
---

Fix issue #$1 following our coding standards.
Review the issue, implement a fix, add tests, and create a commit.
```

Use with: `/fix-issue 123`

### Command with Context

Create `.claude/commands/commit.md`:

```markdown
---
description: Create git commit from staged changes
allowed-tools: Bash(git *)
---

## Context
<!-- NOTE: Place "!" before the opening backtick for preprocessing to work -->
Current branch: `git branch --show-current`
Staged changes: `git diff --staged`
Recent commits: `git log --oneline -5`

## Task

Create a commit with a clear message based on the staged changes.
```

Use with: `/commit`

---

## Workflow Overview

1. **Discovery** - Define purpose, scope, and target users
2. **Design** - Choose features and configuration
3. **Implementation** - Write frontmatter and content
4. **Validation** - Verify against quality standards

---

## Stage 1: Discovery

Before writing code, clarify:

- **Purpose**: What task does this command automate?
- **Scope**: Project-specific or personal workflow?
- **Arguments**: What inputs does it need?
- **Tools**: What operations will it perform?

**Key questions**:
- Will this be shared with the team (project) or personal use?
- Does it require bash execution or file references?
- Should tool access be restricted for safety?

---

## Stage 2: Design

### Command Scopes

| Scope | Location | Visibility | Use Case |
|-------|----------|------------|----------|
| Project | `.claude/commands/` | Team via git | Shared workflows |
| Personal | `~/.claude/commands/` | You only | Individual preferences |
| Plugin | `<plugin>/commands/` | Plugin users | Distributed via marketplace |

Project commands show "(project)" in `/help`. Personal show "(user)".

### Core Features

| Feature | Syntax | Purpose |
|---------|--------|---------|
| Arguments | `$1`, `$2`, `$ARGUMENTS` | Dynamic input from user |
| Bash execution | `!`backtick`command`backtick | Include shell output in context |
| File references | `@path/to/file` | Include file contents |
| Tool restrictions | `allowed-tools:` | Limit Claude's capabilities |

### Frontmatter Schema

```yaml
---
description: Brief description for /help      # Required for discovery
argument-hint: <required> [optional]          # Shown in autocomplete
allowed-tools: Read, Grep, Bash(git *)        # Restrict tool access
model: claude-3-5-haiku-20241022             # Override model
disable-model-invocation: true                # Prevent SlashCommand tool
---
```

See [frontmatter.md](references/frontmatter.md) for complete schema.

---

## Stage 3: Implementation

### File Structure

```markdown
---
description: Deploy to environment with validation
argument-hint: <environment> [--skip-tests]
allowed-tools: Bash(*), Read
---

# Deployment

Target: $1
Options: $2

## Pre-flight Checks
<!-- NOTE: Place "!" before the opening backtick for preprocessing to work -->
Environment: `echo "$1" | grep -E "^(staging|production)$" || echo "Invalid"`
Tests: `[[ "$2" == *"--skip-tests"* ]] && echo "Skipped" || bun test`

## Task

Based on validation above, proceed with deployment or explain issues.
```

### Argument Patterns

**Positional arguments** (`$1`, `$2`, `$3`):

```markdown
Compare file $1 with file $2 and summarize differences.
```

Usage: `/compare old.ts new.ts`

**All arguments** (`$ARGUMENTS`):

```markdown
Fix the following issues: $ARGUMENTS
```

Usage: `/fix memory leak in auth slow query in search`

**Combined with file references**:

```markdown
Analyze this file: @$1
```

Usage: `/analyze src/main.ts`

See [arguments.md](references/arguments.md) for advanced patterns.

### Bash Execution

Execute commands and include output. The `!` must precede the opening backtick for preprocessing to work:

```markdown
## Git Context
<!-- NOTE: Place "!" before the opening backtick for preprocessing to work -->
Branch: `git branch --show-current`
Status: `git status --short`
Diff: `git diff --stat`

Based on the above, suggest next steps.
```

**Important**: Output is truncated at 15,000 characters by default. Use `SLASH_COMMAND_TOOL_CHAR_BUDGET` to adjust.

See [bash-execution.md](references/bash-execution.md) for patterns.

### File References

Include file contents directly:

```markdown
Review this configuration:
- Package: @package.json
- TypeScript: @tsconfig.json
- User input: @$1
```

See [file-references.md](references/file-references.md) for details.

### Tool Permissions

Restrict what Claude can do:

```yaml
# Read-only analysis
allowed-tools: Read, Grep, Glob

# Git operations only
allowed-tools: Bash(git *), Read

# Full bash with restrictions
allowed-tools: Bash(bun *), Bash(npm *), Read, Write, Edit
```

See [permissions.md](references/permissions.md) for patterns.

---

## Stage 4: Validation

After creating a command, validate against these checklists.

### Frontmatter Checks

- [ ] Opens with `---` on line 1, closes with `---`
- [ ] `description` present and action-oriented
- [ ] `argument-hint` uses `<required>` and `[optional]` syntax
- [ ] `allowed-tools` uses correct names (case-sensitive)
- [ ] Uses spaces (not tabs) for indentation

### Naming Conventions

- [ ] Kebab-case filename: `my-command.md`
- [ ] No spaces or special characters
- [ ] Action-oriented: verb-noun pattern preferred
- [ ] Concise: 1-3 words

**Good**: `review-pr.md`, `deploy-staging.md`, `fix-issue.md`
**Bad**: `my command.md`, `DoStuff.md`, `helper.md`

### Description Quality

- [ ] Action-oriented (starts with verb)
- [ ] Specific about what it does
- [ ] Under 80 characters
- [ ] Helpful for `/help` discovery

**Good**: "Deploy to staging with health checks and Slack notification"
**Bad**: "Deploy stuff" or "Helps with deployment"

### Content Quality

- [ ] Clear instructions for Claude
- [ ] Proper argument handling if used
- [ ] Bash commands validated (test in terminal first)
- [ ] File paths relative to project root
- [ ] Error handling for edge cases

### Validation Report Format

```markdown
# Command Validation: [command-name]

## Summary
- **Status**: PASS | FAIL | WARNINGS
- **Location**: [path]
- **Issues**: [count]

## Critical Issues (must fix)
1. [Issue with fix]

## Warnings (should fix)
1. [Issue with fix]

## Strengths
- [What's done well]
```

---

## Namespacing

Organize commands in subdirectories:

```
.claude/commands/
+-- frontend/
|   +-- component.md      # /component (project:frontend)
|   +-- styling.md        # /styling (project:frontend)
+-- backend/
|   +-- migration.md      # /migration (project:backend)
+-- review.md             # /review (project)
```

The namespace appears in `/help` but commands are invoked without prefix: `/component` or `/frontend/component`.

See [namespacing.md](references/namespacing.md) for organization patterns.

---

## Testing Commands

1. **Create** the command file
2. **Verify** with `/help` - should see your command listed
3. **Test** basic invocation: `/your-command`
4. **Test** with arguments: `/your-command arg1 arg2`
5. **Verify** tool restrictions if using `allowed-tools`

### Debug Mode

```bash
claude --debug
```

Shows command loading and execution details.

---

## Troubleshooting

### Command Not Found

- Verify file location: `.claude/commands/name.md`
- Check filename: lowercase, `.md` extension, no spaces
- Restart Claude Code or use `/clear`

### Arguments Not Working

- Use `$1`, `$2` not `{1}`, `{2}`
- Use `$ARGUMENTS` for all arguments
- Quote arguments with spaces: `/cmd "arg with spaces"`

### Bash Commands Failing

- Use `!` before backticks: `` !`command` ``
- Test command in terminal first
- Check output length (15k char limit)
- Verify `allowed-tools` includes `Bash`

### Tool Restrictions Not Applied

- Check YAML syntax (no tabs, proper quoting)
- Tool names are case-sensitive: `Read` not `read`
- Use wildcards for bash: `Bash(git *)`

---

## References

| Reference | Content |
|-----------|---------|
| [frontmatter.md](references/frontmatter.md) | Complete frontmatter schema and fields |
| [arguments.md](references/arguments.md) | Argument handling and patterns |
| [bash-execution.md](references/bash-execution.md) | Shell command execution |
| [file-references.md](references/file-references.md) | File inclusion syntax |
| [permissions.md](references/permissions.md) | Tool restriction patterns |
| [namespacing.md](references/namespacing.md) | Directory organization |
| [sdk-integration.md](references/sdk-integration.md) | Agent SDK usage |
| [community.md](references/community.md) | Community examples and resources |

See [EXAMPLES.md](EXAMPLES.md) for complete real-world examples.
See `scripts/` for scaffolding and validation utilities.

---

## Related Skills

- **claude-hook-authoring**: Add automation triggers to command workflows
- **claude-plugin-development**: Bundle commands into distributable plugins
- **claude-code-configuration**: Configure Claude Code settings globally

Overview

This skill provides a concise guide and conventions for authoring custom slash commands for Claude Code. It explains file layout, frontmatter schema, argument patterns, bash execution, file references, and validation checklists. Use it to create reproducible, safe, and discoverable project or personal commands. The guidance focuses on practical rules and examples so commands work reliably in team and local contexts.

How this skill works

Commands are single Markdown files placed in a commands directory and invoked explicitly with a slash (e.g., /review or /fix-issue 123). Each command uses YAML frontmatter to declare description, allowed tools, model overrides, and argument hints; content can reference positional arguments ($1, $2), $ARGUMENTS, file inclusions (@path), and preprocessed bash output (!`command`). After authoring, commands are discovered via /help and validated against naming, frontmatter, and content quality checks.

When to use it

When you need a reusable, user-invoked prompt or workflow (slash command).
When automating repo-specific tasks like reviews, commits, or deployments.
When you want to expose controlled tool access (Bash, Read, Grep) for a command.
When you need argument parsing or file inclusion in a prompt.
When bundling shareable commands for a project, plugin, or personal use.

Best practices

Use concise, action-oriented descriptions under 80 characters for /help discovery.
Name files in kebab-case without spaces (e.g., fix-issue.md).
Declare allowed-tools explicitly to limit runtime capabilities and increase safety.
Prefer positional arguments ($1, $2) or $ARGUMENTS and document argument-hint in frontmatter.
Test bash snippets in a terminal before embedding; prefix backticks with ! for preprocessing.
Validate commands with the provided checklist: frontmatter, naming, content, and tool syntax.

Example use cases

Create /review to check code quality, potential bugs, and security issues for a PR.
Create /fix-issue <number> to fetch an issue reference, implement a fix, and produce a commit message.
Create /commit to generate a git commit message from staged changes using Bash context.
Create deployment commands that run pre-flight checks and optionally skip tests via flags.
Bundle commands into a plugin folder to distribute common workflows to other projects.

FAQ

Where do command files live for project vs personal use?

Project commands belong in .claude/commands/ (shared via git). Personal commands go in ~/.claude/commands/ and are private to your account.

How do I pass arguments with spaces?

Quote arguments when invoking (e.g., /cmd "arg with spaces"). Use $ARGUMENTS to access the whole argument string.

How do I include shell output in the command context?

Prefix backticks with an exclamation mark like !`git status --short` to run the command and embed its output.