Custom commands and skills - Command reference

Custom commands, skills and hooks in Claude Code transform your terminal into an extensible development environment. This reference guide lists the complete syntax for creating your own slash commands, configuring reusable skills, orchestrating subagents and automating your workflows with deterministic hooks.

Custom commands and skills in Claude Code form the extensibility system that allows you to adapt the tool to your specific workflows. Claude Code offers five extension mechanisms: custom slash commands, skills, subagents, plugins, and hooks. many create at least one custom command within their first week of use.

What are the most used commands in Claude Code?

Before detailing each category, here is the quick reference table of essential commands. Each command runs directly in the Claude Code prompt.

For a comprehensive view of native slash commands, see the essential slash commands reference which covers each option in detail.

Custom commands (created via .md files in .claude/commands/) are invoked directly by their name: /review, /gen-test, etc. There is no /custom or /skill prefix.

How to create custom slash commands in Claude Code?

A custom slash command is a Markdown file stored in the .claude/commands/ directory of your project. Claude Code automatically detects these files and exposes them as / commands.

Creation syntax

Create a Markdown file in the .claude/commands/ folder:

mkdir -p.claude/commands
touch.claude/commands/my-lint.md

The file name becomes the command name. A file my-lint.md creates the command /my-lint. The recommended maximum size of a command file is 2,000 tokens, or about 1,500 words.

Command file structure

Write the content of your command with clear instructions:

Analyze the file $ARGUMENTS with the following rules:
- Check for unused imports
- Detect unused variables
- Flag functions over 50 lines
Return a structured report as a Markdown table.

The $ARGUMENTS variable captures all text entered after the command. In practice, /my-lint src/index.ts replaces $ARGUMENTS with src/index.ts.

Available variable

$ARGUMENTS is the only substitution variable available in command files. It captures all text entered after the command name.

Command scope

Distinguish two scope levels for your commands:

If you want to go further, the custom commands examples page offers concrete ready-to-use cases for code review, test generation, and refactoring.

Key takeaway: a custom command is a Markdown file in .claude/commands/ - no special syntax, just natural language text.

How do skills work in Claude Code?

Claude Code offers two types of skills. The CLAUDE.md file teaches your conventions passively (loaded automatically). Declarative skills in .claude/skills/ (project) or ~/.claude/skills/ (user) are Markdown files with a structured YAML frontmatter. Claude Code discovers them automatically and recursively. The /skills command lists all available skills.

Declarative skill frontmatter

---
title: "My skill"
description: "Skill description"
invoke: auto  # auto or manual
scope: project  # global or project
allowedTools: ["Read", "Glob", "Grep"]
disallowedTools: ["Bash"]
restrictSubagents: true
---

Variables available in skills: $ARGUMENTS, $CLAUDE_PROJECT_DIR, $CLAUDE_USER_HOME.

Bundled skills

Claude Code ships with built-in skills: /simplify, /batch, /loop, /debug, /update-config, /keybindings-help.

Difference between command, declarative skill, and CLAUDE.md

Configuring project conventions

Add your conventions to the CLAUDE.md file at the root of your project:

# Project conventions
- camelCase naming for variables
- Unit tests mandatory for each exported function
- No residual console.log in committed code

Claude Code automatically reads this file at the start of each session and applies these instructions to all its responses.

To discover advanced usage patterns, see the first conversations tips which show how to combine skills and conversational context.

Key takeaway: a skill is a persistent instruction that teaches Claude Code your conventions - it activates automatically or on demand.

How to orchestrate subagents in Claude Code?

Subagents are specialized Claude instances launched from your main session. Each subagent has its own context and its own tools. This architecture allows parallelizing complex tasks without polluting your main context window.

Available subagent types

Launching a subagent

Subagents are internal processes that Claude Code automatically creates to parallelize complex tasks. You do not invoke them directly via slash commands. Simply state your request and Claude Code decides when to delegate to a subagent.

# Claude Code creates subagents internally when needed
> Find all API endpoints in src/ and list all React components

In practice, Claude Code uses subagents to explore source code and execute tasks in parallel transparently.

The first conversations cheatsheet summarizes shortcuts for managing your sessions daily.

Key takeaway: subagents are internal to Claude Code and trigger automatically, without a dedicated slash command.

What automation hooks can be configured?

A hook is a shell command executed automatically in response to a Claude Code event. Unlike skills (probabilistic), hooks are deterministic: they trigger on every occurrence of the configured event. The configuration file is found in .claude/settings.json.

Hook configuration

Add a hook to your settings file:

{
 "hooks": {
 "PostToolUse": [
 {
 "matcher": "Edit",
 "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
 }
 ],
 "PreToolUse": [
 {
 "matcher": "Bash",
 "command": "echo 'Bash command detected'"
 }
 ]
 }
}

Available events

Other events: StopFailure, TeammateIdle, ConfigChange, CwdChanged, FileChanged, PreCompact, PostCompact, WorktreeCreate, WorktreeRemove, SessionEnd, Elicitation, ElicitationResult, InstructionsLoaded, PermissionRequest, PostToolUseFailure.

Each hook uses the "matcher" field (regex) to target a tool (e.g., "Edit", "Write", "Bash"), an optional "if" field for fine-grained filtering, and "command" to define the shell script. Hook types include: command (shell), prompt (AI prompt), agent (sub-agent), and http (HTTP request). Exit codes: 0 = allow, 2 = block, other = allow with log.

To avoid common pitfalls when setting up hooks, see the common errors on custom commands page which documents infinite loop cases and hook conflicts.

Key takeaway: a hook executes a deterministic shell command on each event - use it for formatting, linting, and logging.

How to extend Claude Code with MCP?

Claude Code extends via the MCP (Model Context Protocol), an open standard for connecting external tools. Claude Code also has a native plugin system: claude plugin install to install and claude plugin uninstall to uninstall. The /plugin command lists and manages your plugins in an interactive session.

Configure an MCP server in your .claude/settings.json file:

{
 "mcpServers": {
 "github": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-github"],
 "env": { "GITHUB_TOKEN": "ghp_xxx" }
 }
 }
}

You can also add an MCP server via the command line:

claude mcp add github -- npx @anthropic/mcp-server-github

To deepen your environment customization, the guide on custom commands and skills offers an overview of the extensibility architecture.

Key takeaway: Claude Code extends via MCP (external tool servers), custom commands (Markdown files), and the native plugin system (claude plugin install).

What are the most effective command combinations?

Experienced users chain commands, skills, and hooks to create automated workflows. Here are the most common combinations observed in SFEIR Institute projects.

Useful one-liners

Combine commands and subagents for powerful workflows:

# Code review (custom command defined in.claude/commands/review.md)
/review

# Test generation for a file
/gen-test src/utils/parser.ts

# Security audit (custom command defined in.claude/commands/audit.md)
/audit

Keyboard shortcuts

Concretely, type / then the first letters of the command name to activate auto-completion. The essential slash commands cheatsheet lists all native shortcuts.

If you want to master these techniques in real-world conditions, the Claude Code training from SFEIR Institute (1 day) guides you step by step through creating custom commands, configuring skills, and orchestrating subagents with hands-on labs on your own projects.

Key takeaway: combine slash commands, skills and hooks in one-liners to automate your recurring workflows.

How to debug a custom command that does not work?

Debugging custom commands follows a systematic process. In practice, many come from three causes: an incorrect file path, a misnamed variable, or a scope conflict.

Diagnostic checklist

1. Verify that the .md file is in .claude/commands/
2. Check the file name (no spaces, no special characters)
3. Type / in Claude Code to check the command appears in autocomplete
4. Test the prompt directly in a conversation to isolate the problem
5. Validate the variable syntax ($ARGUMENTS, not ${ARGUMENTS})

# Check command files
ls -la.claude/commands/

# Test the command
/my-lint src/index.ts

The essential slash commands tips offer additional diagnostic techniques for complex cases. You can also check the first conversations command reference to compare the expected behavior of native commands.

Key takeaway: type / to check command detection and test the prompt directly in conversation to isolate issues.

Can commands and skills be shared with a team?

Sharing commands and skills relies on the file system and Git. Commands stored in .claude/commands/ at the project level are automatically versioned and shared via your Git repository.

Recommended sharing strategy

Commit your commands with the project:

git add.claude/commands/ CLAUDE.md.claude/settings.json
git commit -m "feat: add team coding standards commands"
git push

teams that share a set of 5 to 10 custom commands reduce their review time by 25% over a quarter. The installation and first launch cheatsheet details the initial configuration for new team members.

For teams that want to structure their adoption, the AI-Augmented Developer training (2 days) covers setting up team conventions, skill sharing, and CI/CD pipeline integration. The AI-Augmented Developer -- Advanced training (1 day) goes deeper into subagent orchestration and custom plugin creation.

Key takeaway: version your commands in .claude/commands/ with Git to automatically share them with your team.

What are the pitfalls to avoid with custom commands?

The most frequent errors are documented and avoidable. Here are the 5 pitfalls you will encounter most often, with their solutions.

1. Infinite hook loop - A PostToolUse hook that triggers a tool, which relaunches the hook. Add a precise matcher to target only the relevant tools.
2. Scope conflict - A global command (~/.claude/commands/) masks a project command. Rename one of the two commands.
3. Unresolved variable - $ARGUMENTS remains empty if no text is passed. Add a default value in your prompt.
4. Contradictory instructions - Two CLAUDE.md files with opposite instructions create unpredictable behavior. Audit your files regularly.
5. Blocking hook - A hook without a timeout can freeze Claude Code. Wrap each hook with timeout N to limit duration.

The common errors for custom commands and skills page details each error scenario with step-by-step solutions. Also see the custom commands examples to draw inspiration from proven configurations.

Key takeaway: filter your hooks with precise matchers, avoid contradictory instructions in CLAUDE.md, and add timeouts to your hooks.