Claude Code Custom Commands: Arguments and Skills

Create Claude Code custom commands with .claude/commands, pass arguments, choose when to use skills, and keep reusable workflows safe and maintainable.

Claude Code Custom Commands

Claude Code custom commands are reusable slash-command prompts for repeated workflows such as code review, release notes, issue triage, migrations, and deploy checklists. Current Claude Code treats old .claude/commands/*.md files and newer skills as part of the same slash-command workflow: commands still work, but skills are the better home for workflows that need metadata, arguments, supporting files, or automatic invocation.

Quick Answer

Use a custom command for a short prompt you want to invoke manually:

# .claude/commands/review.md

Review the current git diff. Focus on correctness bugs, regressions, security risks, and missing tests.
Lead with concrete findings and file references.

Then run:

/review

Use a skill when the workflow needs a description, argument hints, allowed tools, examples, scripts, or supporting files:

.claude/skills/release-check/SKILL.md

Commands vs Skills

Need	Use	Why
One short reusable prompt	`.claude/commands/name.md`	Lowest overhead.
A workflow with arguments or examples	`.claude/skills/name/SKILL.md`	Skills support frontmatter and supporting files.
Team process with checklists	Skill	Easier to document and maintain.
External tool access	MCP, CLI, or plugin	A command only gives instructions; it does not create a tool.
Always-on project context	`CLAUDE.md`	It should load as memory, not be invoked manually.

Pass Arguments

Text after the command name becomes its arguments. Write the command so Claude knows how to use that trailing text:

# .claude/commands/explain.md

Explain the target provided after `/explain`.
If the user gives a file path, inspect that file first.
If the user gives a concept, explain it with examples from this repository.

Usage:

/explain src/core/auth/index.ts
/explain MCP server permissions

For named positional arguments and autocomplete hints, use a skill:

---
description: Draft release notes for the target version.
argument-hint: '[version]'
arguments: version
---
Draft release notes for $version from the current git history.

Useful Command Examples

Review Current Diff

# .claude/commands/review.md

Review the current git diff for correctness bugs, regressions, security issues, and missing tests.
Return findings first, with file paths and line numbers.
Do not summarize unless there are findings.

Write Release Notes

# .claude/commands/release-notes.md

Read the commits since the latest tag and draft concise release notes.
Separate user-facing changes, fixes, and internal maintenance.
Call out migration or rollback risks.

Triage GitHub Issues

# .claude/commands/triage-issues.md

Use GitHub CLI to list open issues, group them by theme, and suggest the next three to handle.
Do not modify issues unless explicitly asked.

Safety Rules

Keep commands short. Move long procedures into skills.
Do not hide broad permissions in a command.
Keep project facts in CLAUDE.md, not repeated in every command.
Test a command on a small diff before using it on release work.
Remove commands that duplicate a better skill.

Claude Code Custom Commands: Arguments and Skills