Custom commands and skills - Cheatsheet

This cheatsheet gathers all the syntax for creating your own slash commands, configuring reusable skills, orchestrating subagents and automating your Claude Code workflows with hooks. Use this practical reference to master custom commands, skills and Claude Code extensibility in minutes.

Custom commands and skills in Claude Code form the extensibility system that allows adapting the AI agent to your specific workflows. Claude Code (v1.0.33) offers four complementary mechanisms: custom slash commands, skills, subagents, and hooks. over 60% of advanced users create at least one custom command within their first week of use.

What are the most used custom commands in Claude Code?

Custom slash commands extend the set of built-in commands. Each command corresponds to a Markdown file stored in .claude/commands/ (project) or ~/.claude/commands/ (global). See the complete command reference for the exhaustive list of built-in commands.

In practice, a custom slash command reduces a 200-word prompt to 2 words. The essential slash commands cheatsheet covers the built-in commands in detail.

Key takeaway: each custom slash command is a Markdown file in .claude/commands/ that encapsulates a reusable prompt.

How to create a custom slash command step by step?

A custom command is a Markdown file whose name becomes the command suffix. Create the .claude/commands/ directory at the root of your project if it does not exist already.

Command file structure

# Create the project commands directory
mkdir -p .claude/commands

# Create a /custom:review command
touch .claude/commands/review.md

The Markdown file content constitutes the prompt sent to Claude Code. You can use the $ARGUMENTS variable to capture arguments passed after the command.

<!-- .claude/commands/review.md -->
Analyze the file $ARGUMENTS and provide:
1. Potential bugs
2. Performance issues
3. Improvement suggestions
Respond in English with corrected code examples.

Project vs global scope

Run your command by typing /custom:review src/auth.ts in the Claude Code prompt. The command accepts all text arguments after the name. Concretely, the file is between 5 and 500 lines depending on prompt complexity.

To avoid common errors during creation, see the common errors guide which details classic pitfalls.

Key takeaway: name your command files with short, explicit names - the file name becomes the command.

How do skills work so the AI learns your patterns?

Skills represent a level above slash commands: they are persistent instructions that Claude Code automatically loads based on context. A skill is a Markdown file placed in .claude/ that describes conventions, patterns, or business rules.

Available skill types

# Project skill: code conventions
echo "Always use arrow functions in TypeScript" > .claude/CLAUDE.md

# Directory-specific skill
echo "React components follow the Container/Presenter pattern" > src/components/.claude/CLAUDE.md

skills reduce manual corrections by 40% on projects that adopt them. Verify that your CLAUDE.md file contains clear, concise instructions - Claude Code reads it entirely at each startup.

The dedicated custom commands and skills page explores the contextual skill loading mechanics in depth.

Best practices for skills

• Be specific: "Use vitest for tests" rather than "use a good test framework"
• Give examples: include code blocks showing the expected pattern
• Limit size: aim for 50 to 200 lines per skill file for fast loading
• Structure by theme: separate naming conventions, architecture patterns, and test rules

In practice, a 100-line CLAUDE.md file loads in under 50 ms and remains in memory throughout the session.

Key takeaway: skills are CLAUDE.md files loaded automatically - they teach your conventions to Claude Code without repeated effort.

How to orchestrate subagents in Claude Code?

Subagents are autonomous Claude instances launched by the main agent via the Task tool. Each subagent has its own context and its own tools. Use subagents to parallelize independent tasks such as search and implementation.

Available subagent types

Subagent call syntax

// Conceptual subagent orchestration example
// Claude automatically uses Task internally
Task({
  subagent_type: "Explore",
  prompt: "Find all API routes that use authentication",
  description: "Search auth routes"
})

In practice, an Explore subagent analyzes a 50,000-file repository in 15 to 30 seconds. You can launch up to 5 subagents in parallel to maximize performance.

Concretely, subagents protect the main context: a search subagent that reads 200 files does not pollute the parent agent's context window.

To understand how to effectively manage context between main agent and subagents, see the context management guide.

Key takeaway: subagents parallelize work and protect your context window - use Explore for search and general-purpose for implementation.

What hooks allow automating workflows deterministically?

Hooks are shell commands executed automatically in response to Claude Code events. Unlike skills (probabilistic), hooks are deterministic: they run every time, without exception. Configure your hooks in the .claude/settings.json file.

Hook configuration

{
  "hooks": {
    "PostToolUse": [
      {
        "tool": "Edit",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH"
      }
    ],
    "PreToolUse": [
      {
        "tool": "Bash",
        "command": "echo 'Bash command executed: $CLAUDE_COMMAND'"
      }
    ],
    "UserPromptSubmit": [
      {
        "command": "echo 'Prompt received at $(date)' >> ~/.claude/prompt-log.txt"
      }
    ]
  }
}

Available hook events

PostToolUse hooks reduce linting correction round-trips by 80%. Run a quick test by adding a logging hook to verify the configuration works.

Permission management during hook execution is detailed in the permissions and security cheatsheet. To combine hooks and Git commands, see the Git integration cheatsheet.

Key takeaway: hooks guarantee deterministic execution - use them for automatic linting, logging, and mandatory validations.

How to extend Claude Code with plugins and MCP?

The Model Context Protocol (MCP) is Anthropic's open standard for connecting Claude Code to external tools. MCP allows adding servers that expose additional tools, resources, and prompts.

MCP configuration

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    }
  }
}

Place this configuration in .claude/settings.json (project) or ~/.claude/settings.json (global). In 2026, the MCP ecosystem has over 150 community servers covering databases, cloud APIs, and DevOps tools.

To get started with custom commands examples, you will find ready-to-use MCP configurations.

Key takeaway: MCP connects Claude Code to any external tool via a standardized protocol - start with the GitHub server for an immediate gain.

What keyboard shortcuts speed up work with commands?

Memorize these shortcuts to navigate efficiently in Claude Code. These combinations work in the Claude Code v1.0.33 interactive terminal.

SFEIR Institute offers the Claude Code one-day training: you will practice creating slash commands, configuring skills and orchestrating subagents on real cases. To go further, the AI-Augmented Developer training covers in 2 days the complete integration of AI into your development workflow, including hooks and augmented CI/CD pipelines.

See the installation cheatsheet to verify your environment is correctly configured before customizing your commands.

Key takeaway: /compact and Escape are the two most useful daily shortcuts - the first manages context, the second interrupts an irrelevant generation.

How to structure a project with commands, skills and hooks combined?

Here is the recommended file tree for a project that fully leverages Claude Code extensibility. Organize your files according to this structure from day one.

my-project/
├── .claude/
│   ├── CLAUDE.md                  # Project skill (global conventions)
│   ├── settings.json              # Hooks + MCP
│   └── commands/
│       ├── review.md              # /custom:review
│       ├── test.md                # /custom:test
│       ├── deploy.md              # /custom:deploy
│       └── changelog.md           # /custom:changelog
├── src/
│   └── components/
│       └── .claude/
│           └── CLAUDE.md          # Directory skill (React patterns)
└── ...

Concretely, this structure adds less than 5 KB to your repository and is versioned with Git like any configuration file. The settings.json file weighs on average 200 to 500 bytes.

To master your first conversations with this configuration in place, the learning curve drops to under 30 minutes.

If you want to deepen these techniques with hands-on exercises, the AI-Augmented Developer -- Advanced training from SFEIR dedicates half a day to creating personalized workflows with skills, hooks, and subagents.

Key takeaway: group commands, skills, and hooks in .claude/ at the root - version everything with Git to share conventions with your team.

What errors to avoid with custom commands?

Check these points before deploying your custom commands to the team. The most frequent errors concern file naming and variable syntax.

• Naming error: the file my-review.md creates the command /custom:my-review, not /review
• Forgotten variable: $ARGUMENTS is case-sensitive - $arguments does not work
• File too long: a prompt over 2,000 words consumes context unnecessarily - aim for 100 to 300 words
• Blocking hook: a PreToolUse hook that fails (exit code != 0) blocks the tool - always test in isolation first
• MCP without token: forgetting the GITHUB_TOKEN environment variable silently fails the MCP server
• Contradictory skill: two CLAUDE.md files with opposite instructions create unpredictable behavior

The complete common errors guide details each of these cases with associated solutions. In practice, 90% of problems are resolved by checking the file path and the $ARGUMENTS syntax.

Key takeaway: test each command in isolation before sharing - a misnamed file or a failing hook can block the entire workflow.