Building Custom Slash Commands and Agents

Claude Code becomes dramatically more powerful when you create custom slash commands and agents tailored to your project. Instead of typing the same complex prompts repeatedly, you define reusable commands that encode your team's workflows, coding standards, and automation patterns. With the skills system and custom subagents, you can build a library of specialized tools that any team member can invoke.

What You Will Learn

• How to create custom slash commands in .claude/commands/
• The skills system and SKILL.md frontmatter
• Building custom subagents in .claude/agents/
• Agent frontmatter fields (model, description, tools, hooks)
• Real-world examples of production agents

---

Custom Slash Commands

Slash commands are the simplest way to create reusable prompts. Place a Markdown file in your project's .claude/commands/ directory, and it becomes available as a /command in Claude Code.

Basic Command Structure

.claude/
└── commands/
    ├── review.md
    ├── test-file.md
    └── deploy-check.md

Each file's name (without the .md extension) becomes the command name. The file content becomes the prompt that Claude receives when you invoke the command.

Example: Code Review Command

Create .claude/commands/review.md:

Review the staged git changes for the following:

1. Bug risks: null pointer errors, race conditions, unhandled errors
2. Security: SQL injection, XSS, exposed secrets, insecure dependencies
3. Performance: N+1 queries, unnecessary re-renders, missing indexes
4. Style: naming conventions, dead code, missing types

Format your review as a markdown checklist with severity levels (critical/warning/info).
Run the test suite after your review to verify nothing is broken.

Now you can type /review in Claude Code and it executes this detailed prompt every time.

Commands with Arguments

Slash commands accept arguments using the $ARGUMENTS placeholder:

Create .claude/commands/test-file.md:

Write comprehensive unit tests for the file: $ARGUMENTS

Follow these rules:
- Use the existing test framework (check package.json for jest/vitest)
- Include edge cases, error handling, and boundary conditions
- Mock external dependencies
- Aim for at least 90% branch coverage
- Run the tests to verify they pass

Usage: /test-file src/services/UserService.ts

The Skills System

Skills are the evolution of slash commands. A skill is a directory under .claude/skills/ containing a SKILL.md file with YAML frontmatter that tells Claude when and how to use it.

.claude/
└── skills/
    └── review/
        └── SKILL.md

SKILL.md Frontmatter

---
name: review
description: "Perform a thorough code review on staged changes"
trigger: "when the user asks for a code review or mentions reviewing changes"
---

Review the staged git changes with focus on:
...

The key advantage of skills over plain commands is the trigger field. Claude can automatically invoke a skill when it recognizes a matching request, even without an explicit /command invocation.

Your existing .claude/commands/ files continue to work alongside skills. A file at .claude/commands/review.md and a skill at .claude/skills/review/SKILL.md both create the /review command.

Custom Subagents

While slash commands provide reusable prompts, custom subagents provide reusable agents with their own configuration, tools, and behavior. Place agent definitions in .claude/agents/:

.claude/
└── agents/
    ├── course-builder.md
    ├── blog-post-builder.md
    └── code-reviewer.md

Agent Frontmatter

Agent files use YAML frontmatter to configure the subagent:

---
description: "Builds new course content with lessons, quizzes, and exams"
model: claude-opus-4-6
tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
  - WebSearch
maxTurns: 50
color: purple
---

You are a course-building agent. Your job is to create complete course
content following the project's content structure.

## Rules
1. Always check for duplicate content before creating new courses
2. Follow the MDX format in existing courses
3. Include quizzes for every lesson
4. Create a final exam with at least 22 questions
5. Validate all MDX compiles correctly
6. Run the courses test suite after creating content

Frontmatter Fields Reference

Field	Purpose	Example
description	What the agent does	"Builds blog posts"
model	Which Claude model to use	claude-opus-4-6, claude-sonnet-4-6
tools	Allowed tools list	["Read", "Edit", "Bash"]
disallowedTools	Blocked tools	["Bash(rm -rf:*)"]
maxTurns	Maximum conversation turns	50
color	Terminal display color	purple, blue, green
mcpServers	MCP servers to connect	["playwright"]
hooks	Custom hooks for this agent	(hook configuration)
isolation	Run in isolated environment	true
memory	Memory configuration	(memory settings)
effort	Reasoning effort level	high, medium, low

Real-World Agent Examples

Blog Post Builder Agent

---
description: "Creates SEO-optimized blog posts with structured data"
model: claude-sonnet-4-6
tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
  - WebSearch
maxTurns: 30
color: blue
---

You are a blog post builder. Create blog posts following the project's
content structure and SEO guidelines.

## Process
1. Research the topic using WebSearch
2. Check for duplicate/similar content in existing posts
3. Create the MDX content file with proper frontmatter
4. Create the structured-data.json for SEO
5. Validate the MDX compiles
6. Run the blog test suite

Code Reviewer Agent

---
description: "Reviews code changes for bugs, security, and style"
model: claude-sonnet-4-6
tools:
  - Read
  - Grep
  - Glob
  - Bash
disallowedTools:
  - Edit
  - Write
maxTurns: 15
color: yellow
---

You are a read-only code reviewer. Analyze the current git diff and
provide a structured review. You MUST NOT edit any files.

## Review Checklist
1. Security vulnerabilities
2. Performance issues
3. Error handling gaps
4. Type safety concerns
5. Test coverage gaps

Notice this agent has Edit and Write in disallowedTools to enforce that it only reads and reports, never modifies code.

SEO Audit Agent

---
description: "Audits pages for SEO best practices"
model: claude-sonnet-4-6
tools:
  - Read
  - Grep
  - Glob
  - Bash
  - WebSearch
maxTurns: 20
color: green
---

Audit the specified pages for SEO compliance:

1. Check meta titles (50-60 chars) and descriptions (150-160 chars)
2. Verify Open Graph tags and structured data
3. Check heading hierarchy (single H1, logical H2-H6)
4. Verify image alt text and WebP format usage
5. Check internal linking structure
6. Validate canonical URLs
7. Report findings in a structured format with severity levels

Invoking Custom Agents

You can invoke custom agents from within Claude Code:

> /agents/course-builder "Create a Python data structures course with 8 lessons"

Or reference them when asking Claude to delegate:

> "Use the code-reviewer agent to review the changes on this branch,
>  then use the blog-post-builder agent to write a changelog post
>  about the new features."

Plugins: Packaging and Sharing

Plugins bundle commands, agents, MCP servers, and hooks into shareable packages. You can install plugins from the community:

/plugin install @anthropic/code-review

Or create your own plugin by organizing your .claude/ directory into a distributable format. Plugins are in public beta and can be installed with the /plugin command.

Organizing Your Command Library

A mature project might have a structure like this:

.claude/
├── commands/
│   ├── review.md           # Quick code review
│   ├── test-file.md        # Write tests for a file
│   ├── deploy-check.md     # Pre-deployment verification
│   └── explain.md          # Explain a code section
├── agents/
│   ├── course-builder.md   # Full course content builder
│   ├── blog-writer.md      # Blog post creator
│   ├── code-reviewer.md    # Detailed code reviewer
│   └── seo-auditor.md      # SEO audit agent
├── skills/
│   └── fix-lint/
│       └── SKILL.md        # Auto-triggered lint fixer
└── settings.json            # Project-level settings

---

Key Takeaways

• Custom slash commands in .claude/commands/ turn complex prompts into reusable one-word commands
• Skills in .claude/skills/ add automatic triggering based on context matching
• Custom subagents in .claude/agents/ create fully configured specialist agents with their own model, tools, and constraints
• Use disallowedTools to create read-only agents that review without modifying code
• Agent frontmatter supports model selection, tool restrictions, MCP servers, hooks, and isolation
• Plugins package commands, agents, and configuration for sharing across teams and projects
• Build a library of specialized agents that encode your team's workflows and standards