Custom commands and skills - FAQ

Custom commands, skills and hooks in Claude Code let you automate your development workflows and teach your patterns to the AI. Create custom slash commands in minutes, delegate tasks to autonomous subagents and trigger deterministic actions via hooks to save up to 40% of time on your repetitive tasks.

Custom commands and skills in Claude Code form an extensibility system that transforms the AI agent into a tailored assistant. Claude Code (version 1.0+) offers five extension mechanisms: custom slash commands, skills, subagents, hooks, and third-party integrations. over 60% of advanced users create at least one custom command within their first week of use.

How to create a custom slash command in Claude Code?

Create a Markdown file in the .claude/commands/ directory of your project to define a custom slash command. Each .md file automatically becomes a command accessible via /.

The file name determines the command name. For example, .claude/commands/review.md creates the /review command. You can organize your commands in subfolders to group them by category.

Here is how to structure your first command:

mkdir -p .claude/commands
touch .claude/commands/review.md

The file content defines the prompt sent to Claude Code. Use the $ARGUMENTS variable to capture parameters passed by the user:

Analyze the file $ARGUMENTS and check:
1. TypeScript typing errors
2. OWASP Top 10 security vulnerabilities
3. Compliance with our ESLint conventions
Suggest concrete fixes with code.

For commands shared across your machine, place them in ~/.claude/commands/. These global commands are available in all your projects.

In practice, a custom slash command reduces a 200-word prompt to a 3-word invocation. See the complete custom commands reference to discover advanced syntax with multiple variables.

Key takeaway: a custom slash command is a Markdown file in .claude/commands/ - one file = one command.

What are the most common use cases for custom commands?

Custom commands cover four main categories: code review, test generation, documentation, and deployment.

Here concretely are the most commonly created commands by development teams:

# .claude/commands/test-unit.md
Generate unit tests for $ARGUMENTS using:
- Framework: Vitest
- Pattern: AAA (Arrange, Act, Assert)
- Coverage: branches and edge cases
- Mocks: vi.mock for external dependencies

# .claude/commands/doc-api.md
Document the API endpoint in $ARGUMENTS:
- HTTP method and URL
- Required and optional parameters
- Response codes (200, 400, 401, 500)
- Working curl example

teams that adopt at least 5 custom commands reduce by 35% the time spent on code review tasks. The essential slash commands provide a solid foundation before creating your own variants.

Key takeaway: focus your custom commands on tasks you repeat more than 3 times per week.

How do skills work in Claude Code?

Skills are Markdown files automatically loaded by Claude Code to teach it your conventions, patterns, and coding preferences. Add your skills to the CLAUDE.md file at the root of your project or in nested CLAUDE.md files per directory.

A skill differs from a slash command: the command is invoked explicitly, while the skill is read and applied automatically at each session. The CLAUDE.md memory system details the complete architecture of this persistent memory.

Here is how to declare a skill in your CLAUDE.md:

# Code conventions

## TypeScript
- Use interfaces rather than types for objects
- Name files in kebab-case
- Prefix interfaces with I (IUser, IProduct)
- Always use string enums for statuses

## Tests
- One test file per source file
- Name tests: "should [action] when [condition]"
- Minimum 80% branch coverage

In practice, a 50-line CLAUDE.md file is enough to align Claude Code with 90% of your team conventions. The skill is applied from the session start, without any action on your part.

Key takeaway: skills in CLAUDE.md teach your patterns to Claude Code - it applies them automatically without invocation.

Can subagents be used to parallelize tasks?

Launch subagents with Claude Code's Task tool to execute multiple tasks in parallel and divide complex work. A subagent is an autonomous Claude instance that processes a specific subtask.

Subagents have their own context and can read files, execute commands, and produce results. You can launch several simultaneously for independent tasks. Concretely, an Explore type subagent searches your codebase while a general-purpose type implements a feature.

Here are the subagent types available as of February 2026:

In practice, launching 3 subagents in parallel to analyze a 50,000-line project takes about 45 seconds versus 3 minutes sequentially. Discover how agentic coding leverages this parallelization to solve complex problems.

Key takeaway: subagents divide the work - launch several in parallel for independent tasks.

How to configure hooks to automate actions?

Hooks are shell commands executed automatically by Claude Code in response to specific events. Configure them in the .claude/settings.json file of your project.

A hook triggers deterministically, without AI intervention. This is the fundamental difference with a command or skill: the hook is a reliable and 100% reproducible automation.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo 'Bash command detected'"
      }
    ]
  }
}

hooks support four events: PreToolUse, PostToolUse, Notification, and Stop. Each hook receives contextual environment variables like $CLAUDE_FILE_PATH.

You can chain multiple hooks on the same event. Verify that your hook scripts return an exit code of 0 to indicate success. A non-zero code blocks the current action. To explore the security of these automations further, see the permissions and security FAQ.

Key takeaway: hooks automate deterministic actions on specific events - zero AI, 100% reliable.

Which configuration files control commands and skills?

Five main files and directories govern Claude Code extensibility. Verify their presence with the following command:

ls -la .claude/commands/ CLAUDE.md .claude/settings.json

The CLAUDE.md file at the root is the entry point for skills. The .claude/commands/ directory contains your slash commands. The .claude/settings.json file configures hooks and permissions.

Here concretely is the typical file tree of a well-configured project:

my-project/
├── CLAUDE.md                    # Project global skills
├── .claude/
│   ├── commands/
│   │   ├── review.md            # /review
│   │   ├── test-unit.md         # /test-unit
│   │   └── deploy/
│   │       └── staging.md       # /deploy:staging
│   └── settings.json            # Hooks and permissions
├── src/
│   └── CLAUDE.md                # Skills specific to src/
└── tests/
    └── CLAUDE.md                # Skills specific to tests

The installation and first launch guide explains how to initialize this structure from the first use of Claude Code. Also see the custom commands tips to optimize your file tree.

Key takeaway: five files structure your extensions - CLAUDE.md, .claude/commands/, .claude/settings.json and their per-directory variants.

How to share custom commands with your team?

Commit the .claude/commands/ directory to your Git repository to share your commands with the entire team. Every developer who clones the project automatically gets the same slash commands.

Concretely, your .gitignore should NOT exclude .claude/commands/. However, add .claude/settings.local.json to .gitignore for personal configurations.

# .gitignore recommended for Claude Code
.claude/settings.local.json
# DO NOT ignore:
# .claude/commands/
# CLAUDE.md

Teams of more than 5 developers often adopt a review process for new commands. You create a pull request that adds a file to .claude/commands/, the team reviews it like standard code. this practice reduces practice divergence within a team by 25%.

To go further with team command management, see the custom commands cheatsheet which summarizes all sharing best practices.

Key takeaway: commit .claude/commands/ in Git - your commands become a versioned team standard.

Is there a plugin marketplace for Claude Code?

Claude Code does not have a centralized plugin marketplace like VS Code. Extensibility relies on custom commands, skills, and hooks.

The community nevertheless shares commands and configurations via public GitHub repositories. You will find collections of ready-to-use commands for testing, refactoring, and documentation.

Integration with the MCP (Model Context Protocol) allows connecting Claude Code to external tool servers. MCP is an open standard published by Anthropic in 2024 that unifies communication between AI agents and data sources.

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

In practice, over 150 MCP servers are available on npm as of February 2026. Each server adds specialized tools: database access, web browsing, cloud file management. To understand how these integrations fit into the agentic paradigm, see the agentic coding FAQ.

Key takeaway: no centralized marketplace, but MCP and community repositories offer a rapidly growing extension ecosystem.

How to debug a custom command that does not work?

Run the / command in Claude Code to list all detected commands and immediately identify whether your file is recognized.

Three causes cover 90% of errors on custom commands: an incorrect file path, a missing .md extension, or a UTF-8 encoding issue. Check these points in order.

# Check that the file exists and is readable
file .claude/commands/my-command.md

# Check the encoding
file -I .claude/commands/my-command.md
# Expected: text/plain; charset=utf-8

If your command uses $ARGUMENTS but receives nothing, make sure to pass arguments after the command name: /my-command file.ts. The $ARGUMENTS variable captures all text after the command name.

For hooks that fail silently, add logging in your script:

#!/bin/bash
echo "[HOOK $(date)] Execution on $CLAUDE_FILE_PATH" >> /tmp/claude-hooks.log
npx eslint --fix "$CLAUDE_FILE_PATH" 2>> /tmp/claude-hooks.log

See the first conversations with Claude Code if you are getting started and encountering initial configuration issues.

Key takeaway: list your commands with /, check the path, .md extension and UTF-8 encoding to resolve 90% of problems.

Can you create commands that modify multiple files at once?

Describe in your custom command the scope of files to modify and Claude Code will process them sequentially or in parallel depending on context. A custom command has no limit on the number of files it can target.

Here is an example of a multi-file command to add license headers:

# .claude/commands/add-license.md
Add the following Apache 2.0 license header at the top of
each TypeScript file in $ARGUMENTS:

// Copyright 2026 SFEIR. All rights reserved.
// Licensed under the Apache License, Version 2.0

Do NOT modify files that already have a license header.
Count and list the modified files.

In practice, this command processes a directory of 80 TypeScript files in under 30 seconds. Claude Code uses the Edit tool for each file, which guarantees atomic and reversible modifications.

The custom commands and skills detail advanced patterns for operations on entire file trees. The permissions mechanism protects you: Claude Code asks for your confirmation before any write in default mode.

Key takeaway: no file limit per command - describe the scope in the prompt and Claude Code handles the traversal and modifications.

When should you use a hook rather than a custom command?

Use a hook when the action must trigger automatically and deterministically, without human intervention. Use a custom command when you want to invoke the AI on demand.

Concretely, configure a PostToolUse hook to run Prettier after each file write. Create a custom /review command for in-depth AI code analysis. The hook runs in 50 ms, the custom command takes 15 to 45 seconds.

The Claude Code training from SFEIR Institute dedicates half a day to creating custom commands and hooks with hands-on labs. You will learn to build a complete automation pipeline in 1 day.

Key takeaway: hook = instant deterministic automation, custom command = on-demand AI invocation.

How to structure skills for a monorepo project?

Place a CLAUDE.md file at each significant level of your monorepo to contextualize instructions based on the package or service. Claude Code loads skills from the current directory and its parents.

monorepo/
├── CLAUDE.md                      # Global conventions
├── packages/
│   ├── api/
│   │   └── CLAUDE.md              # NestJS stack, API conventions
│   ├── web/
│   │   └── CLAUDE.md              # Next.js 15 stack, frontend conventions
│   └── shared/
│       └── CLAUDE.md              # Shared lib rules

When you work in packages/web/, Claude Code loads both the root CLAUDE.md and the one in packages/web/. The most specific skill prevails in case of conflict. this hierarchy supports up to 10 nesting levels without performance loss.

In practice, a 200,000-line monorepo with 5 targeted CLAUDE.md files reduces convention errors by 70% compared to a single root file. To go deeper, the AI-Augmented Developer 2-day training covers monorepo architectures and advanced AI agent customization with exercises on real projects.

Key takeaway: one CLAUDE.md per package in a monorepo - Claude Code automatically merges skills from the current path.

What are the pitfalls to avoid with custom commands?

Avoid five frequent errors that neutralize the effectiveness of your custom commands and skills.

1. Overly vague prompts: "Improve this code" yields nothing exploitable. Specify the criteria: performance, readability, security.
2. Contradictory skills: two CLAUDE.md files giving opposite instructions create inconsistent results. Audit your skills regularly.
3. Blocking hooks: a hook script taking more than 10 seconds slows down the entire session. Limit your hooks to operations under 500 ms.
4. No $ARGUMENTS: forgetting this variable makes the command rigid and not reusable.
5. Too many commands: beyond 20 custom commands, maintainability drops. Group similar commands.

See the custom commands tips for detailed solutions to each of these pitfalls.

The AI-Augmented Developer -- Advanced training from SFEIR Institute, in 1 day, deepens these best practices with real debugging cases for complex agentic workflows.

Key takeaway: prompt specificity, skill consistency, hook speed - these three principles avoid 80% of problems.

---