Claude Command Authoring Skill

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:

---
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:

---
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:

---
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

Discovery - Define purpose, scope, and target users
Design - Choose features and configuration
Implementation - Write frontmatter and content
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 | !backtickcommandbacktick | Include shell output in context | | File references | @path/to/file | Include file contents | | Tool restrictions | allowed-tools: | Limit Claude's capabilities |

Frontmatter Schema

---
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 for complete schema.

Stage 3: Implementation

File Structure

---
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):

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

Usage: /compare old.ts new.ts

All arguments ($ARGUMENTS):

Fix the following issues: $ARGUMENTS

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

Combined with file references:

Analyze this file: @$1

Usage: /analyze src/main.ts

See arguments.md for advanced patterns.

Bash Execution

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

## 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 for patterns.

File References

Include file contents directly:

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

See file-references.md for details.

Tool Permissions

Restrict what Claude can do:

# 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 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

# 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 for organization patterns.

Testing Commands

Create the command file
Verify with /help - should see your command listed
Test basic invocation: /your-command
Test with arguments: /your-command arg1 arg2
Verify tool restrictions if using allowed-tools

Debug Mode

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 | Complete frontmatter schema and fields | | arguments.md | Argument handling and patterns | | bash-execution.md | Shell command execution | | file-references.md | File inclusion syntax | | permissions.md | Tool restriction patterns | | namespacing.md | Directory organization | | sdk-integration.md | Agent SDK usage | | community.md | Community examples and resources |

See 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

Agent Skills: Claude Command Authoring

Install this agent skill to your local

Skill Files