Learn how to build custom slash commands inside Claude Code — from your very first skill to writing production-grade instructions that make the agent output exactly what you want.

Part 1: Beginner Guide — Your First Slash Command Skill

You've seen people type /audit or /review in Claude Code and get a full structured output. Here's exactly how to build your own from scratch.

What Is a Skill?

A Skill is a saved set of instructions that Claude Code reads and follows when you trigger it with a slash command.

One folder. One file. That's it.

When you type /your-skill-name, Claude loads the instructions and executes them — every time, consistently, without you re-explaining anything.

Prerequisites

  • Claude Code installed and working
  • A project folder open in your terminal
  • Basic comfort with creating files and folders (that's all you need)

Step 1: Create the Skills Folder

Inside your project root, create this folder structure:

mkdir -p .claude/skills

This is where all your skills live. Claude Code automatically scans this directory.

Two places you can store skills:

  • .claude/skills/ — Project-specific (lives in your repo, can be committed to git)
  • ~/.claude/skills/ — Personal/global (works across every project on your machine)

Start with project-specific. You can always move it later.

Step 2: Create Your Skill Folder

Each skill gets its own folder. Let's build a simple code review skill:

mkdir -p .claude/skills/review

Your structure now looks like:

.claude/
└── skills/
    └── review/

Step 3: Create SKILL.md

Inside your skill folder, create a file called SKILL.md. This is the only required file.

touch .claude/skills/review/SKILL.md

Now open it and add your instructions:

---
name: review
description: Run a full code review on the current file or project. Triggers on "/review".
---

# Code Review

## Instructions

1. Scan the target file(s) for:
   - Bugs and logic errors
   - Security vulnerabilities
   - Performance issues
   - Code style inconsistencies

2. For each issue found, provide:
   - The file and line number
   - What the problem is (one sentence)
   - A suggested fix (code snippet)

3. End with a summary:
   - Total issues found
   - Severity breakdown (critical / warning / suggestion)
   - Overall code health rating (1-10)

## Output Format

Return the review as a structured markdown report with clear headings.

Step 4: Test Your Skill

Open Claude Code in your project and type:

/review

Claude reads your SKILL.md, follows the instructions, and outputs a full structured code review.

That's it. One folder, one file, one slash command.

Understanding the SKILL.md Structure

3 Starter Skills You Can Build Right Now

1. /audit — Security Audit

---
name: audit
description: Scan for security vulnerabilities. Triggers on "/audit".
---

# Security Audit

## Instructions
Scan every file for:
- Exposed API keys and hardcoded secrets
- Open endpoints without authentication
- SQL injection vulnerabilities
- Insecure dependencies

Output a full security report with severity levels.

2. /readme — Auto-Generate README

---
name: readme
description: Generate a project README. Triggers on "/readme".
---

# README Generator

## Instructions
1. Analyze the project structure and codebase
2. Identify the tech stack, main features, and setup steps
3. Generate a clean, professional README.md with:
   - Project title and description
   - Tech stack
   - Installation instructions
   - Usage examples
   - Folder structure overview

3. /changelog — Auto-Generate Changelog

---
name: changelog
description: Generate a changelog from recent git commits. Triggers on "/changelog".
---

# Changelog Generator

## Instructions
1. Read the last 20 git commits
2. Group changes by type (features, fixes, refactors)
3. Write a clean, human-readable changelog entry
4. Use conventional commit format

Common Beginner Mistakes

Don't do these:

  • ❌ Naming the file anything other than SKILL.md — it must be exact
  • ❌ Putting the file directly in .claude/skills/ without a subfolder
  • ❌ Writing vague instructions like "review my code" — be specific about what to look for and how to output it
  • ❌ Forgetting the YAML frontmatter (the --- block at the top) — Claude needs this to identify the skill

Folder Structure Recap

your-project/
└── .claude/
    └── skills/
        ├── review/
        │   └── SKILL.md
        ├── audit/
        │   └── SKILL.md
        └── readme/
            └── SKILL.md

Each skill = one folder + one SKILL.md. Simple as that.

Part 2: Advanced Guide — Optimizing Skills for Agent Performance

You know how to create a skill. Now let's make it exceptional.

This section is about writing skills that produce consistent, high-quality output every single time — and structuring them so Claude uses minimal tokens while delivering maximum results.

The Problem With Basic Skills

Most people write skills like a wish list: "Do this, then this, then this."

The result? Claude interprets your instructions differently each time. The output is inconsistent. Sometimes great, sometimes garbage.

The fix: Treat your SKILL.md like a contract, not a conversation.

Principle 1: Constraint-Based Instructions

Don't tell Claude what to do. Tell Claude what the output must look like.

❌ Weak (Behavior-Based)

## Instructions
Review the code and find bugs. Tell me what's wrong and how to fix it.

✅ Strong (Constraint-Based)

## Instructions
For every issue found, output EXACTLY this structure:

**[SEVERITY]** `filename:line` — One-sentence description

// suggested fix here


Severity levels: CRITICAL | WARNING | INFO
Maximum 3 sentences per issue. No preamble. No summary unless explicitly requested.

Why this works: You're defining the shape of the output, not the thought process. Claude has less room to hallucinate or deviate.

Principle 2: Progressive Disclosure Architecture

This is the single biggest unlock for advanced skills.

This means you should keep SKILL.md lean and offload heavy content into supporting files.

Optimal Folder Structure for Advanced Skills

my-skill/
├── SKILL.md              # Core instructions only (keep under 2000 tokens)
├── templates/
│   └── output-template.md   # The exact format you want Claude to copy
├── examples/
│   ├── good-output.md       # What a perfect result looks like
│   └── bad-output.md        # What to avoid (surprisingly effective)
├── scripts/
│   └── helper.sh            # Executable scripts (never enters context window)
└── references/
    └── api-patterns.md      # Deep docs loaded only when relevant

Key insight: Files in scripts/ are executed, not read. They never consume tokens in the context window. Use them for data gathering, formatting, or any computation.

Principle 3: Few-Shot Examples Beat Long Instructions

Showing Claude one perfect example is worth 10 paragraphs of explanation.

The Pattern

## Examples

### Input
User says: "Review the auth module"

### Expected Output
**[CRITICAL]** `src/auth/login.ts:47` — Password comparison uses timing-unsafe equality check

// Use crypto.timingSafeEqual instead of ===

import { timingSafeEqual } from 'crypto';


**[WARNING]** `src/auth/session.ts:12` — Session token has no expiry

// Add 24h expiry to session config

const SESSION_TTL = 86400;


**Summary:** 2 issues found (1 critical, 1 warning) | Health: 6/10

Pro tip: Include a "bad output" example too. Claude learns fast from what not to do:

### Bad Output (DO NOT do this)
"I found some issues with the code. The login function could be improved
by using a more secure comparison method. Also, sessions should probably
have an expiry..."

Why this is bad: Too vague, no structure, no actionable fixes.

Principle 4: Write the Description Like a Trigger

The description field in your YAML frontmatter is the most important line in the entire skill.