Custom commands and skills

Creating your own slash commands, configuring skills and hooking into Claude Code lets you automate up to 40% of your development tasks. This guide covers setting up custom commands, having the AI automatically learn your conventions, orchestrating parallel subagents, and integrating MCP plugins.

Custom commands and skills in Claude Code form the extensibility system that adapts the AI agent to your specific development practices. Claude Code v1.0 offers four complementary mechanisms: custom slash commands, declarative skills, automation hooks, and parallel subagents. many create at least one custom command within their first week of use.

How do custom commands work in Claude Code?

A custom command is a Markdown file stored in .claude/commands/ that defines a reusable prompt invocable via /command-name. Create a file, write your prompt, and Claude Code automatically detects it at startup.

The mechanism relies on naming conventions. Each .md file in the .claude/commands/ directory becomes a slash command. You can organize your commands into subfolders to categorize them by domain.

To understand the overall architecture of the tool, check the introduction page to Claude Code which presents all available features.

In practice, project commands are versioned with your code and shared with the entire team. Personal commands remain private on your machine. This separation lets you standardize team practices while keeping your individual shortcuts.

The $ARGUMENTS variable is the mechanism for injecting dynamic parameters into your slash commands. It captures all text entered after the command name.

Key takeaway: custom commands are Markdown files in .claude/commands/ - one file = one reusable slash command for the entire team.

How to create a custom slash command step by step?

Open your terminal and create the commands directory if needed:

mkdir -p.claude/commands

Create a file for your first command. Here is how to define a /review command that performs a code review:

Analyze the current Git diff and perform a code review.
Check for:
- Logic errors
- Security vulnerabilities (injection, XSS)
- Project convention violations
- Missing tests
Format your response with concrete suggestions.

Save this content to .claude/commands/review.md, then test it directly:

claude
> /review

Claude Code detects the file and executes the associated prompt. The load time for a custom command is under 50 ms. You can also create parameterized commands.

Check the step-by-step custom commands tutorial for examples including variables and advanced parameters.

Generate unit tests for the file $ARGUMENTS.
Use the test framework already configured in the project.
Cover nominal cases, edge cases, and errors.

Save this file as .claude/commands/gen-test.md and run it with an argument:

> /gen-test src/utils/parser.ts

commands with arguments cover 75% of enterprise use cases. The system supports commands nested in subfolders, accessible via /folder/command.

To quickly find the syntax, keep the command reference at hand, which lists all available parameters.

Key takeaway: create a .md file in .claude/commands/, use $ARGUMENTS for dynamic parameters, and your command is operational.

What are skills and how does the AI learn your patterns?

Claude Code offers two types of skills. The first type, CLAUDE.md files, teaches your conventions passively. The second type, declarative skills in .claude/skills/ (project) or ~/.claude/skills/ (user), are Markdown files with a YAML frontmatter that defines their behavior: title, description, invoke (auto or manual), scope (global or project), allowedTools, disallowedTools, and restrictSubagents. Claude Code discovers them automatically and recursively. The /skills command lists all available skills.

Declarative skills support three variables: $ARGUMENTS (user input), $CLAUDE_PROJECT_DIR (project root), and $CLAUDE_USER_HOME (home directory).

Your development conventions are also taught via the CLAUDE.md file at the project root (or in subdirectories). This file is read automatically and influences every response from the agent.

Define your naming conventions, architectural patterns, and style rules in the CLAUDE.md file.

## Project React conventions
- Functional components with hooks only
- Files named in PascalCase: UserProfile.tsx
- Types in an adjacent.types.ts file
- Zustand for global state management
- Tests with Vitest + Testing Library
- Minimum coverage: 80%

In practice, a well-written skill reduces manual corrections by 35% experience feedback. Claude Code loads all project skills at the start of each session, in under 100 ms.

You can check the commands and skills cheatsheet to quickly find the syntax for each type of skill.

The CLAUDE.md file is the project memory, read as a priority by Claude Code. Add your high-level instructions there. You can also place CLAUDE.md files in subdirectories for specialized instructions by domain.

To understand how skills integrate into the agentic coding paradigm, see our dedicated guide that explains the role of agent autonomy.

Key takeaway: skills teach your conventions to the AI persistently - they apply automatically to every interaction without manual invocation.

How to use subagents to parallelize your tasks?

A subagent is a secondary Claude instance launched by the main agent to process a subtask in parallel. This mechanism allows breaking down complex work into independent units executed simultaneously.

Concretely, when you ask Claude Code to refactor 5 files, the main agent delegates each file to a dedicated subagent. The total time drops from 5x to about 1.5x the time for a single file.

Since Claude Code v1.0 (2026), the maximum number of simultaneous subagents is 10. Each subagent consumes on average 15% more tokens compared to sequential execution.

Each subagent inherits the project context: skills, CLAUDE.md, and commands. It operates in a sandbox with the same permissions as the main agent. For automated workflows, see the guide on headless mode and CI/CD.

In practice, 80% of tasks involving more than 3 files benefit from subagent parallelization. The orchestration is automatic - you do not have to manage the distribution.

Discover concrete examples of subagents in action in our documented use case gallery.

Key takeaway: subagents parallelize complex tasks with an average time savings of 70% - Claude Code orchestrates them automatically.

Can Claude Code be extended with plugins and a marketplace?

The MCP (Model Context Protocol) is the Claude Code extension system for integrating external tools. An MCP server is a plugin that exposes additional capabilities: database access, API querying, or specialized file reading.

Configure an MCP server in your settings file:

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

Hundreds of community servers are available. You can create your own MCP server in TypeScript or Python. The ecosystem covers databases, monitoring, cloud services, and documentation systems.

To avoid the most common configuration errors, see the common errors with commands and plugins guide which covers MCP connection issues.

Always verify the source of an MCP server before installation. An unverified server could access your files and environment variables. Check the official MCP registry for reliable community servers.

The advanced best practices for Claude Code detail recommended MCP configurations for enterprise use, including access compartmentalization.

Claude Code also has a native plugin system. Install a plugin with claude plugin install and uninstall it with claude plugin uninstall . The /plugin command in an interactive session manages your plugins.

Key takeaway: MCP and the native plugin system extend Claude Code. Hundreds of community MCP servers exist, and you can create your own in TypeScript or Python.

How to automate deterministic actions with hooks?

A hook is a shell script triggered automatically by Claude Code during specific events. Unlike skills that influence AI behavior and manually invoked commands, hooks execute deterministic code on every occurrence of an event.

Configure your hooks in .claude/settings.json:

{
 "hooks": {
 "PreToolUse": [
 {
 "matcher": "Edit",
 "command": "echo 'Modification detected'"
 }
 ],
 "PostToolUse": [
 {
 "matcher": "Bash",
 "command": "npm run lint --fix"
 }
 ]
 }
}

Claude Code supports many hook events, including:

• PreToolUse: triggers before tool execution
• PostToolUse: triggers after tool execution
• UserPromptSubmit: triggers when the user submits a prompt
• SessionStart: triggers at session startup
• Stop: triggers at the end of Claude's response
• Notification: triggers on system messages
• SubagentStart / SubagentStop: triggers on subagent launch and stop
• TaskCreated / TaskCompleted: triggers on task creation and completion

Other available 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, an optional "if" field for fine-grained filtering, and a "hooks" array with entries of type command, prompt, agent, or http. Exit codes determine behavior: 0 allows, 2 blocks, any other code allows and logs.

Here is how a post-tool-use hook on the Edit tool automatically runs ESLint (v9.x) after each file modification. This approach ensures the code complies with your rules without manual intervention.

For ready-to-use hook recipes, see the advanced configuration tips. Hooks guarantee deterministic execution: the script runs systematically, without depending on AI interpretation.

Key takeaway: hooks execute deterministic code on specific events - use them for automatic linting, logging, and mandatory validations.

Should you combine skills, hooks, and subagents for an optimal workflow?

The power of Claude Code lies in combining these mechanisms. Here is how to assemble them for a complete development workflow:

1. Define your skills to teach your conventions at startup
2. Create slash commands for your frequent actions
3. Configure hooks for mandatory automatic checks
4. Let subagents parallelize tasks involving multiple files
5. Integrate MCP servers to connect your external tools

A typical enterprise workflow uses 5 to 8 skills, 10 to 15 custom commands, and 3 to 4 hooks. This configuration reduces development time by 40% internal measurements on React and Node.js 22 projects.

If you are getting started, begin with installing and first launching Claude Code, then follow the guide on your first conversations before configuring advanced commands.

To master these concepts in real-world conditions, the Claude Code training from SFEIR offers a full day of hands-on labs. You will create your own commands, skills, and hooks on a concrete project, and leave with a reusable configuration kit.

The AI-Augmented Developer 2-day training covers advanced subagent orchestration and MCP integration in production architectures. To go deeper into multi-agent workflows, the AI-Augmented Developer -- Advanced 1-day training details hook strategies for CI/CD and large-scale subagent coordination.

Key takeaway: combine skills (conventions), commands (actions), hooks (automation) and subagents (parallelization) for a workflow up to significant.

How to debug and optimize your custom commands?

Debugging custom commands starts with verifying the file location and syntax. Check that your file is in .claude/commands/ with the .md extension.

See the FAQ dedicated to commands and skills for answers to the most frequent questions about loading issues.

Here are the most common errors you will encounter:

• File placed in .claude/ instead of .claude/commands/
• Incorrect extension (.txt instead of .md)
• $ARGUMENTS variable misspelled in the prompt
• Prompt exceeding 4,000 tokens (recommended limit: 2,000 tokens)
• Name conflict between project command and personal command
• Unescaped special characters in the prompt

Optimize your prompts by keeping them concise and structured. An effective command prompt contains between 100 and 500 words. Beyond that, split into multiple commands or use a complementary skill.

Concretely, type / in Claude Code to check that your commands are detected in the autocomplete. Test the prompt directly in a conversation to isolate the problem.

Key takeaway: check the location, extension, and size of your command files. Type / to verify detection.

---