Claude Code Custom Commands
How Claude Code custom commands relate to slash commands and skills, when to use each, and how to keep reusable workflows maintainable.
Custom commands are reusable prompts you can invoke from Claude Code instead of typing the same workflow every time. In current Claude Code, the broader pattern is moving toward skills: Markdown-based workflow packages with clearer descriptions, optional resources, and better reuse.
Last checked on May 24, 2026. Older tutorials often say "custom slash commands"; current docs emphasize skills while still acknowledging command-style workflows.
Short Answer
Use a small command for a simple repeated prompt. Use a skill when the workflow has steps, examples, validation, or team-specific instructions.
Commands vs Skills
| Need | Use | Why |
|---|---|---|
| One short shortcut such as "review this diff" | Custom command | Low overhead and easy to read. |
| Reusable workflow with a checklist | Skill | Better description, structure, and discoverability. |
| Team process with examples or templates | Skill | Can include supporting files. |
| External tool capability | MCP server or plugin | Commands alone do not create external tools. |
| Project-wide behavior every session | CLAUDE.md | It should load as context, not be invoked manually. |
Practical Examples
Small command idea:
# Review the current diff
Check the current git diff for correctness, missing tests, and risky changes.
Lead with concrete findings and file references.Skill idea:
.claude/skills/release-check/
SKILL.md
checklist.md
examples/Use the skill when the workflow needs a repeatable checklist, examples, or validation steps.
Maintenance Rules
- Keep the name obvious. A future teammate should know when to use it.
- Put stable project facts in
CLAUDE.md, not inside every command. - Do not hide risky permissions in a command.
- Test commands on a small diff before using them on a release branch.
- Remove commands that duplicate a newer skill.
Common Mistakes
| Mistake | Better approach |
|---|---|
| A 300-line command file | Convert it into a skill with supporting docs. |
| Commands that assume one machine path | Use project-relative paths or CLAUDE.md. |
| Commands that ask Claude to skip review | Keep review and permission gates explicit. |
| Duplicating official docs | Link to official docs and keep only team-specific policy. |