takazudo/custom-command-creator

Custom Command Creator

Guide for creating effective custom slash commands in Claude Code.

What Are Custom Commands?

Custom slash commands are Markdown files that define reusable prompts. They're simpler than skills - single files for quick, frequently-used prompts.

Use commands when:

• Same prompt is used repeatedly
• Prompt fits in one file
• Explicit control over when to run

Use skills instead when:

• Claude should auto-detect the capability
• Multiple files or scripts needed
• Complex workflows with validation steps

Command Locations

| Location | Path | Scope | |----------|------|-------| | Project | .claude/commands/<name>.md | This project only (shows as "project") | | Personal | $HOME/.claude/commands/<name>.md | All your projects (shows as "user") |

Priority: Enterprise > Personal > Project. When commands share a name across levels, personal ($HOME/.claude/commands/) overrides project (.claude/commands/) — commands follow the same precedence as skills, since custom commands are a skill variant. See Skills for the full precedence rule.

Command Anatomy

Every command is a single Markdown file with optional frontmatter:

---
description: Brief description of what the command does
allowed-tools: Bash(git:*), Read
argument-hint: [filename] [options]
---

# Command Instructions

Your prompt content here with $ARGUMENTS placeholder.

See frontmatter.md for all available fields.

Core Features

Arguments

Pass dynamic values to commands using placeholders:

All arguments - $ARGUMENTS:

Fix issue #$ARGUMENTS following our coding standards

Usage: /fix-issue 123 high-priority → $ARGUMENTS = "123 high-priority"

Positional arguments - $1, $2, etc.:

Review PR #$1 with priority $2 and assign to $3

Usage: /review-pr 456 high alice → $1="456", $2="high", $3="alice"

Bash Execution

Run shell commands before the prompt is sent using !command`` syntax:

---
allowed-tools: Bash(git:*)
---

## Context
- Git status: !`git status`
- Current branch: !`git branch --show-current`
- Recent commits: !`git log --oneline -5`

## Task
Create a commit based on the above changes.

Important: Must include Bash in allowed-tools for this to work.

File References

Include file contents using @ prefix:

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

Compare @src/old.js with @src/new.js

Extended Thinking

Set the effort frontmatter field (low–max) to control reasoning depth — see references/frontmatter.md. The old "thinking keywords" prompting pattern ("think hard", "ultrathink") is superseded; current docs no longer document it.

Namespacing

Use subdirectories to organize related commands:

.claude/commands/
├── frontend/
│   └── component.md  → /component (project:frontend)
├── backend/
│   └── api.md        → /api (project:backend)
└── deploy.md         → /deploy (project)

Same-named commands in different subdirectories are distinguished by their namespace label.

Command Creation Workflow

When the user asks to create a command, follow this workflow.

Step 1: Determine Command Name and Location

If the user provides a name, use it. If they describe what they want, derive an appropriate kebab-case name.

Choose location based on context:

• Global command ($HOME/.claude/commands/<name>.md): User says "global", or wants it available across all projects
• Local/project command (.claude/commands/<name>.md): User says "local" or "project", or wants it scoped to current repo
• If unclear: Ask the user which they prefer

For local commands, find the project root first:

git rev-parse --show-toplevel  # Use repo root, or cwd if not a git repo

Ensure the target directory exists before writing.

Step 2: Gather Details

Ask the user if needed:

• What should the command do?
• Does it need arguments? If so, what arguments?
• Should it use bash execution (!command``) for dynamic context?
• Should it restrict allowed tools?

Step 3: Write the Command File

Create the command file with proper structure:

Required best practices:

• Always include frontmatter with description field
• Use argument-hint if the command accepts arguments (e.g., [filename], [pr-number])
• Use $ARGUMENTS for all args or $1, $2 for positional args
• If using bash execution, include allowed-tools in frontmatter
• If manual-only invocation needed, add disable-model-invocation: true

Template:

---
description: Brief description of what the command does
argument-hint: [expected-args]
allowed-tools: Bash(git:*), Read
---

# Command Title

Clear instructions for what Claude should do.

## Context (if using bash execution)
- Dynamic info: !`git status --short`

## Task
What to accomplish with $ARGUMENTS.

Step 4: Format the command file

Format the created command file using the mdx-formatter to ensure consistent markdown formatting:

pnpm dlx @takazudo/mdx-formatter --write <path-to-command-file.md>

Step 5: Verify and Report

After creating the file:

1. Confirm the file exists at the target path
2. Show the user the full content of the created file
3. Tell them they can use it with /<command-name>
4. For global commands: Remind that a personal (global) command takes priority over a project-level command with the same name — see the Priority note in "Command Locations" above
5. For local commands: Suggest committing to git so the team can share it

Key Rules for Creation

• Command filename must be kebab-case (lowercase, hyphens): my-command.md
• Always include description in frontmatter - commands without it are harder to discover
• Keep the command focused on a single task
• Use $ARGUMENTS / $1 / $2 for dynamic values, not hardcoded values
• Don't overcomplicate - a command is a single Markdown file for a reusable prompt
• Local commands are great for project-specific workflows (deploy, test patterns, review checklists)
• File paths must use $HOME instead of ~: When command instructions reference home directory paths (e.g., log directories, config files), always write $HOME/cclogs/... or $HOME/.claude/..., never ~/cclogs/... or ~/.claude/.... The ~ character is only expanded by interactive shell login contexts. In Node.js fs operations, non-login shells, and many tool contexts, ~ is treated as a literal character, which creates an actual directory named ~/ inside the working directory instead of resolving to the user's home directory. This applies to paths in the command body text, bash execution snippets, and any instructions that an agent will follow. (Guard note: the ~/... forms above are the deliberate NEVER-case this rule warns against — a future blanket ~→$HOME find-and-replace must skip this line, or it destroys the contrast the rule depends on.)

Examples

Simple Review Command

---
description: Quick code review
---

Review this code for:
- Security vulnerabilities
- Performance issues
- Code style violations

Git Commit with Context

---
description: Create a git commit with context
allowed-tools: Bash(git:*)
---

## Context
- Status: !`git status`
- Diff: !`git diff HEAD`
- Branch: !`git branch --show-current`
- Recent commits: !`git log --oneline -5`

## Task
Create a single git commit for the staged changes.
Message should be concise and follow conventional commits.

PR Review with Arguments

---
description: Review a pull request
argument-hint: [pr-number]
allowed-tools: Bash(gh:*)
---

## PR Context
- PR info: !`gh pr view $1`
- PR diff: !`gh pr diff $1`
- PR comments: !`gh pr view $1 --comments`

## Task
Review PR #$1 for:
1. Code quality and best practices
2. Potential bugs or edge cases
3. Security concerns
4. Test coverage

Model-Specific Command

Most commands should omit model and inherit the session's active model. Pin a model only when the command's task clearly calls for it, e.g. a cheap, high-volume task that doesn't need a large model:

---
description: Quick lint-style pass over the diff
model: claude-haiku-4-5-20251001
---

Perform a lint-style pass on $ARGUMENTS.

Preventing Auto-Invocation

To prevent Claude from invoking a command automatically via the Skill tool:

---
description: Deploy to production (manual only)
disable-model-invocation: true
---

Deploy the application to production.

Command-Scoped Hooks

Define hooks that run only during command execution:

---
description: Deploy with validation
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"
          once: true
---

Deploy to staging environment.

The once: true option runs the hook only once per session.

Troubleshooting

Command not appearing

1. Check file is in correct location (.claude/commands/ or $HOME/.claude/commands/)
2. Verify .md extension
3. Run /help to see available commands

Arguments not working

1. Use $ARGUMENTS for all args or $1, $2 for positional
2. Check for typos in placeholder names

Bash execution failing

1. Ensure allowed-tools: Bash(...) is in frontmatter
2. Check command syntax is correct
3. Verify the shell command works standalone

Related Resources

• Skills: For complex multi-file capabilities
• Hooks: For automated workflows around tool events
• Permissions: For controlling tool access