Custom slash commands are one of the most underutilized features in Claude Code. Most developers know about CLAUDE.md — they write their project rules there and call it done. But skills (the system that powers custom commands) let you go further: package entire workflows into a single /command, reuse them across every project, and invoke multi-step processes with one word.
This guide covers how the skills system works in 2026, how to write effective SKILL.md files, and the patterns that are worth building.
How the Skills System Works
In Claude Code, custom slash commands are implemented as skills. When you type /my-command, Claude Code looks for a matching skill file, loads its instructions as a system prompt, and executes accordingly.
Skills live in two places:
- Project-scoped:
.claude/skills/in your project root — only available in that project - Global:
~/.claude/skills/in your home directory — available in every project
Each skill is either a single markdown file or a directory:
.claude/skills/
review.md # simple skill as a single file
deploy/ # complex skill as a directory
SKILL.md # required entry point
checklist.md # supporting reference
examples/ # example outputsThe directory format is more flexible. For anything beyond a simple prompt, use the directory structure.
SKILL.md Structure
Every skill starts with a SKILL.md file. The structure has two parts:
---
name: review
description: Review code for correctness, security issues, and style violations.
Use before committing or opening a pull request.
---
Review the code in the current session for the following issues:
1. Logic errors and edge cases the tests might miss
2. Security vulnerabilities (injection, insecure defaults, exposed secrets)
3. Performance problems (N+1 queries, unnecessary allocations, blocking calls)
4. Style violations based on the project's CLAUDE.md rules
Output your findings as a structured list organized by severity: Critical,
Warning, Info. For each issue, include the file and line number, a one-line
description, and a suggested fix.
If you find no issues, say so explicitly. Do not pad the output.The frontmatter name field determines the slash command. name: review becomes /review.
The description field does double duty: it shows in the / autocomplete list, and it tells Claude when to invoke this skill autonomously (more on that in a moment).
Two Invocation Patterns
Skills can be invoked in two ways, and designing for both opens up different use cases.
User-invoked commands are what most people think of. You type /review and Claude runs the skill. These are best for workflows you consciously initiate: code reviews, deployment checklists, report generation, test scaffolding.
Autonomous invocation happens when Claude decides on its own to load a skill. This is governed by the description field. If Claude is working on a task and determines that a skill’s description matches what it needs, it can invoke the skill without being asked.
This means well-written descriptions serve as routing rules for your agent. A skill with the description “Use when writing database migrations to check for backward compatibility” will get called automatically when Claude writes migrations — but only if the description clearly signals the right trigger.
For autonomous invocation to work reliably, descriptions need to be specific and action-oriented. “Helps with code” is useless. “Reviews API endpoint handlers for authentication and authorization gaps before committing” is useful.
Commands vs Skills: The Practical Distinction
Both are implemented the same way under the hood, but they serve different design goals.
Commands are deterministic, user-initiated workflows. The output is predictable because you control when they run. Good examples: /standup (generates a standup summary from recent commits), /changelog (formats commit history into a changelog), /pr-description (writes a pull request description from staged changes).
Knowledge skills are context Claude carries. They aren’t typically invoked directly — they get loaded when Claude needs reference material. A skill describing your internal API conventions, your database schema patterns, or your team’s testing philosophy falls here.
A practical rule: if you would type the command, it is a command. If you want Claude to consult it without being reminded, it is a knowledge skill.
Writing Effective Skill Instructions
The most common mistake is writing skills like prompts in a conversation. Skills are instructions, not requests.
Weak:
Can you please help me review this code? I'd like you to look for any problems
you find and let me know what you think.Strong:
Review all modified files in the current session.
For each file:
- Check for null pointer dereferences and unhandled error returns
- Verify that external inputs are validated before use
- Confirm that any new dependencies are pinned to specific versions
Output a numbered list. If a file has no issues, skip it.
End with a one-line summary: either "No issues found" or "N issues found across M files."The strong version tells Claude exactly what to check, how to structure the output, and what to do in the edge case of clean code. There is no ambiguity to resolve.
Three rules for instruction quality:
- Use imperative verbs. “Review”, “Output”, “Check”, “Skip” — not “could you”, “please”, “would you mind.”
- Specify the output format explicitly. If you want a numbered list, say numbered list. If you want JSON, show the schema.
- Handle the edge cases. What should Claude do if there is nothing to review? If the task cannot be completed? Silence on edge cases leads to improvised responses.
Progressive Disclosure with Directories
For complex skills, the single-file format gets unwieldy. The directory structure lets you separate concerns:
.claude/skills/
deploy/
SKILL.md # instructions (keep under 400 lines)
pre-deploy.md # checklist Claude reads before deploying
rollback.md # rollback procedure reference
examples/
staging.md # example staging deploy
production.md # example production deployIn SKILL.md, you reference the supporting files explicitly:
---
name: deploy
description: Run the deployment workflow for this project. Use when deploying to staging or production.
---
Before starting, read `pre-deploy.md` for the current checklist.
For staging deployments:
...
For production deployments:
...
If rollback is needed, follow the procedure in `rollback.md`.This pattern keeps the main SKILL.md short and readable while making the full reference material available when Claude needs it. Claude only reads the supporting files when the instructions direct it to — so you are not burning context on information that might not be relevant.
Scope Strategy: What Goes Global vs Project-Level
Global skills (in ~/.claude/skills/) are for workflows that apply everywhere:
/review— code review against general best practices/explain— explain the current function or file in plain English/test— generate tests for the selected code/standup— generate a standup update from recent git activity
Project-level skills (in .claude/skills/) are for workflows specific to one codebase:
/migrate— run the project’s database migration workflow/seed— seed the development database with test data/deploy-staging— deploy to the project’s staging environment/api-review— check API endpoints against this project’s conventions
When a project-level skill and a global skill share the same name, the project-level skill wins. This lets you override defaults on a per-project basis without touching your global setup.
Practical Skills Worth Building
Based on patterns from the developer community, these skills consistently pay off:
/commit-message
Generates a commit message from staged changes. Reads the diff, follows conventional commits format, and avoids generic messages like “fix bug” or “update code.”
/review
Code review against a specific checklist. Build one for your team’s standards and invoke it before every PR. Consistent, reproducible, fast.
/explain-error
Takes an error message (or the last error in the session) and explains what caused it, where in the code, and how to fix it. Useful when you are in a debugging loop and want a second look.
/generate-tests
Generates test cases for a function or module. Should specify which test framework your project uses and whether to include edge cases and failure paths.
/adr
Architecture Decision Record generator. Takes a decision topic and outputs a formatted ADR document following whatever template your team uses. Good for teams that maintain ADR directories.
What to Avoid
Overlapping skills. If you have /review, /code-review, and /check, you will spend time remembering which one to use. Consolidate.
Skills that do too much. A skill called “do everything” that reviews code, generates docs, runs tests, and opens a PR will produce worse results than four focused skills. Each skill should do one thing well.
Long skills without structure. If your SKILL.md exceeds 500 lines, split it. The first few hundred lines get the most attention. Later sections get skimmed.
Secrets in skills. Skills are stored in plaintext. Do not put API keys, tokens, or credentials in them. Reference environment variables instead.
Getting Started
If you have never built a custom skill before, start with one simple command. Pick a workflow you run manually today — code review, standup generation, changelog formatting — and write a SKILL.md for it.
Keep the first version short: under 200 lines. Use it for a week and note where it falls short. Iterate. The best skills in the community got there through ten rounds of editing, not a perfect first draft.
The .claude/skills/ directory goes in your repository, which means your team shares it. That is the real payoff: everyone on the team gets the same Claude Code workflows without any setup.