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 (v2.1) offers five extension mechanisms: custom slash commands, skills, subagents, plugins, and hooks. over 60% of advanced users 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.

Key takeaway: these 10 commands cover 90% of daily interactions with Claude Code.

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.

Table of available variables

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?

A skill is a mechanism through which Claude Code learns and memorizes your development patterns. Concretely, skills are persistent instructions that modify the agent's behavior over time. skills reduce manual corrections after code generation by 40%.

Difference between command and skill

Creating a skill

Define a skill in the .claude/skills/ file:

mkdir -p .claude/skills

{
  "name": "review-pr",
  "description": "PR review following our conventions",
  "instructions": "Analyze each modified file. Check: camelCase naming conventions, unit tests present, no residual console.log.",
  "trigger": "manual"
}

The trigger field accepts three values: manual (explicit invocation), auto (contextual detection) and hook (triggered by an event). In practice, a skill in auto mode activates when Claude Code detects a matching context, for example when opening a pull request.

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

Run the following command in your Claude Code prompt:

/agent Explore "Find all API endpoints in src/"

The Explore subagent scans the source code in 3 to 8 seconds depending on project size. In practice, a 50,000-line project is explored in under 5 seconds by a dedicated subagent.

Parallel execution

Launch multiple subagents simultaneously for independent tasks:

/agent Explore "List React components" &
/agent Bash "npm run test -- --coverage" &
/agent Plan "Propose an architecture for the auth module"

parallel execution of 3 subagents reduces processing time by 65% compared to sequential execution.

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

Key takeaway: subagents isolate tasks in separate contexts - launch them in parallel to save time.

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": {
    "on_tool_call": [
      {
        "tool": "Edit",
        "command": "npx prettier --write $FILE_PATH",
        "description": "Automatically format after each edit"
      }
    ],
    "on_prompt_submit": [
      {
        "command": "echo 'Prompt submitted at $(date)'",
        "description": "Log each submission"
      }
    ]
  }
}

Available events

In practice, the on_tool_call hook with Prettier formats 100% of edited files without manual intervention. This automation eliminates formatting back-and-forth that consumes on average 12 minutes per day according to a Stack Overflow study (2025).

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 use plugins and the Claude Code marketplace?

Plugins extend Claude Code's capabilities beyond built-in commands and skills. The Claude Code marketplace references over 150 community plugins covering linting, deployment, CI/CD integration, and documentation.

Installing a plugin

Run the install command from your terminal:

claude plugin install @claude/eslint-bridge

Installation takes between 2 and 10 seconds depending on plugin size. Plugins are stored in ~/.claude/plugins/ and persist between sessions. Each plugin weighs on average 250 KB.

Plugin management

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

Key takeaway: the marketplace centralizes community plugins - install a plugin in one command and it persists between your sessions.

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:

# Full review before commit
/skill review-pr && /hook run pre-commit

# Exploration + guided refactoring
/agent Explore "Find functions > 100 lines" | /custom refactor

# Test generation for a module
/skill test-gen $FILE && /agent Bash "npm run test -- --watch"

Associated keyboard shortcuts

Concretely, the Ctrl+/ combination followed by typing the first letters activates 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, 80% of errors 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. Test the command with /custom --debug command-name
4. Examine the logs with claude --log-level debug
5. Validate the variable syntax ($ARGUMENTS, not ${ARGUMENTS})

# Enable debug mode for a command
claude --log-level debug
/custom my-lint src/index.ts

Debug mode displays each execution step with a timestamp in milliseconds. An execution time exceeding 30,000 ms indicates a performance issue in the command prompt.

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: enable --log-level debug mode first - it reveals 80% of issues in seconds.

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/skills/
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 on_tool_call hook that triggers a tool, which relaunches the hook. Add a filter on the tool name to break the loop.
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. Overly generic skill - A skill with an auto trigger that is too broad fires out of context. Specify the activation conditions.
5. Incompatible plugin - A plugin designed for Claude Code v1.x does not work in v2.1. Check compatibility with claude plugin info name.

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, specify your triggers and check plugin compatibility - these three habits eliminate 90% of issues.