Claude Code Custom Commands

Quick Answer

Custom commands are markdown files that Claude Code loads as slash commands. Put them in the skills folder (global or project) and invoke with the Skill tool. Each file has frontmatter with name and description, plus a markdown body describing the workflow. TLDR: great for repeat workflows like standardized commits, code reviews, or deploy checklists. Commit the skills folder to share with your team.

Summary of the 6 things a custom command can do

1. Run a multi-step repeat workflow
2. Enforce team standards like commit format
3. Drop in shared review checklists
4. Wrap a deploy process with safety checks
5. Generate boilerplate for common tasks
6. Automate onboarding or setup steps

What custom commands actually are

A custom command (also called a skill) is a markdown file stored in a skills folder. When you type its name with a slash prefix, Claude Code loads the file and executes the described workflow.

The files are plain markdown with YAML-style frontmatter at the top. No special DSL, no compiled format, no build step. You write a doc describing what the command should do, and Claude follows it.

This design has the same benefits as CLAUDE.md. Files are portable, shareable, and editable. There is no hidden state. The command is exactly what is written in the file.

File location

2 locations matter.

Global skills at ~/.claude/skills/.md are available in every project. Personal workflows go here: your preferred commit flow, your code review checklist, your deploy steps.

Project skills at .claude/skills/.md (relative to the repo root) are available only in that project. Team workflows go here: commit format enforced by the team, review checklist specific to the codebase, deploy process for the project.

Commit the project skills folder to git. Every team member gets the same commands.

The frontmatter format

Every skill file starts with YAML frontmatter. 2 fields matter.

The name field is the command identifier. Users invoke it with a slash and the name: /commit, /review, /deploy.

The description field is a short explanation of what the command does and when to use it. Claude uses this when deciding whether to offer the command as a suggestion.

A minimal frontmatter looks like 3 lines of YAML between triple-dash fences. Name, description, and a blank line before the markdown body.

How to invoke a custom command

2 ways to run a skill.

Directly by name with a slash. Type /commit and Claude runs the workflow.

Through the Skill tool programmatically. The agent decides to invoke the command based on the description. Useful for agents dispatching subtasks that happen to match a skill.

Both paths load the same file and execute the same workflow. Direct invocation is what you will use day to day.

Example 1: a /commit skill

The most common custom command is a standardized commit workflow. Write it once, invoke it every time you want to commit.

The workflow: run tests, check lint, stage changes, ask Claude for a conventional commit message, show the message for review, commit. Maybe push to a branch.

The skill file captures each step as a short markdown list. Claude follows the list in order, pausing where the instructions say to pause. The user invokes /commit and gets a consistent commit flow without typing the 5 steps every time.

This saves about 30 seconds per commit. On a team doing 20 commits a day, that is 10 minutes saved daily, plus the benefit of consistent commit messages across all team members.

Example 2: a /review skill

A code review checklist skill. When you finish a feature and before opening a PR, invoke /review and Claude runs through a predefined checklist against your changes.

The checklist typically covers 8 to 12 things. Tests pass. Lint passes. No console.log left in code. No TODO comments without a ticket. Type coverage acceptable. Error handling present. Accessibility checks pass (if a UI change). Documentation updated if the public API changed.

Claude runs each check, reports findings, and gives a pass-or-fix summary. The user fixes and re-runs until clean.

This replaces the checklist that lived in a team wiki that nobody read. Making it a slash command makes it unavoidable.

Example 3: a /deploy skill

A deploy safety checklist skill. Before shipping, /deploy runs 5 checks.

1. All tests pass on the target branch
2. Migrations are reversible
3. Feature flags are in the expected state
4. Changelog is updated
5. On-call rotation knows the change is landing

Each check either passes automatically or prompts you for confirmation. Deploy only happens if all 5 clear.

This kind of skill saves more than time. It prevents the Friday deploy disaster where someone forgot a migration was non-reversible and panic followed.

When custom commands make sense

3 criteria to check before writing a skill.

The workflow repeats. If you do something 10 times a week, a skill pays for itself within a day.

The workflow has clear steps. If the steps are judgment calls, a skill is the wrong shape. Write a CLAUDE.md rule or keep it in human hands.

The output matters. Commits, PRs, deploys, releases are all worth standardizing. One-off tasks are not.

Do not over-skill. Every skill is a file to maintain. A team with 40 skills often has half of them unused. Start with 3 to 5 high-value ones and grow from there.

Skills vs CLAUDE.md

Skills are invoked on demand. CLAUDE.md is always active. 2 different tools for different jobs.

CLAUDE.md holds rules that apply to every task. Language version, folder layout, forbidden patterns. Things Claude should always follow.

Skills hold workflows for specific situations. The commit flow, the review flow, the deploy flow. Things Claude does only when invoked.

Do not put workflow steps in CLAUDE.md. They bloat the context on every turn and often do not apply. Do not put general rules in skills. They are ignored unless the skill is invoked.

Sharing skills with a team

Commit .claude/skills/ to the repo. Every team member who clones the repo gets the skills. New hires pick them up automatically on their first session.

This is the cleanest way to enforce team workflows. No wiki article to read, no onboarding doc to skim. The workflow is a slash command away.

When a skill changes, the commit diff shows exactly what changed. Team members see the update on their next pull.

Plugin system

Claude Code supports installable skill packages. The claude plugin install command pulls a package and drops its skills into a plugin folder. Useful for community-maintained workflows: popular commit styles, standardized review checklists, common deploy patterns.

Some teams maintain an internal plugin with the company standard skills. New projects inherit the standard by installing the plugin. Updates propagate to every project that installed it.

For single-project teams, plain project skills are simpler. Plugins pay off when 5 or more projects share the same workflows.

Testing a new custom command

4 steps to verify a skill works.

Write the file at the expected path. Global or project.

Start a fresh Claude Code session in the project folder.

Invoke the skill by name with a slash. Claude should respond by starting the described workflow.

Walk through the workflow. Verify each step runs as expected. If a step is wrong, edit the file and re-invoke.

Skills iterate fast. The feedback loop between writing and testing is about 10 seconds. Expect to go through 3 to 5 revisions before a skill feels right.

Common skill patterns

Teams building out a skill library tend to land on a similar set. Here are the 8 most common skills seen in practice.

1. /commit for standardized commits
2. /review for pre-PR checklists
3. /deploy for deploy safety
4. /test for running the full test suite
5. /cleanup for removing dead code
6. /onboard for setting up new env
7. /release for version bump and tag
8. /debug for standardized debug workflows

None of these are complicated. Each is 30 to 80 lines of markdown. The value is consistency across a team, not complexity.

A note on naming

Skill names should be verbs, short, and memorable. /commit beats /standardized-commit-workflow. /review beats /code-review-checklist-enforcement.

Short names mean users remember and use them. Long names mean users forget and type the full workflow by hand. Every skill you write fights for space in the team muscle memory. Keep the names tight.