Slash commands give you reusable prompts. Skills give you reusable workflows — structured, multi-step sequences that orchestrate several operations in order. The difference is scope: a /commit command writes a commit message. A review-pr skill reads the PR, analyzes the diff, checks for failing CI, reads related issues, posts inline review comments, and summarizes findings.
Skills are how you encode complex engineering processes into something Claude can execute reliably, repeatedly.
What a skill actually is
In Claude Code, a skill is a structured workflow that Claude executes using the Skill tool. Each skill has a name, a description, and a sequence of steps. Claude follows the steps, using its built-in tools (Read, Bash, Write, etc.) and any MCP servers you've configured to complete each one.
The key difference from a slash command: a skill can branch, loop, and adapt based on intermediate results. It's not just a prompt expanded once — it's a process Claude works through.
Creating skills
Skills are defined in .claude/skills/ at your project root, or in ~/.claude/skills/ for user-level skills that apply across all projects. Like commands, they're Markdown files — but with a more structured format.
Here's a review-pr.md skill:
# Review Pull Request
## Description
Comprehensive code review of a GitHub pull request, including diff analysis, CI check status, and inline comments.
## Steps
1. **Fetch PR information**
- Use the GitHub MCP server to get PR #$ARGUMENTS details
- Read the full diff
- Note the PR title, description, and linked issues
2. **Analyze changed files**
- For each changed file, read the current version in the codebase
- Understand the context around the changes
- Identify potential issues: bugs, security problems, missing error handling, N+1 queries
3. **Check CI status**
- Read the check runs for this PR
- If any checks are failing, look at the failure output
4. **Post review**
- Post inline comments on specific lines where issues exist
- Write a review summary covering: overall quality, critical issues, suggestions
- Submit the review with an appropriate verdict: approve, request-changes, or comment
5. **Report**
- Output a brief summary of what you found and what you posted
Skills can reference $ARGUMENTS (everything passed when the skill is invoked) and can access all the tools and MCP servers available in your session.
Skills vs slash commands: the practical distinction
Think of it this way:
Slash command — a prompt template. It's text that becomes your message to Claude. Claude then figures out how to handle it.
Skill — a structured procedure. Claude follows defined steps in order, with the ability to adapt based on what each step returns.
A /review-pr slash command says: "Here's a prompt about reviewing a PR."
A review-pr skill says: "Step 1: fetch the PR. Step 2: analyze the diff. Step 3: check CI. Step 4: post comments. Step 5: summarize."
For simple, well-defined tasks, a slash command is sufficient and simpler. For complex workflows with multiple distinct phases, a skill gives you more control over the process.
Real-world skill examples
add-feature.md — implement a feature from a specification:
# Add Feature
## Description
Implement a new feature from a specification, following project conventions.
## Steps
1. **Understand the spec**
- Read $ARGUMENTS as the feature description or ticket number
- If it's a GitHub issue number, fetch it via the MCP server
- Clarify anything ambiguous before writing code
2. **Orient to the codebase**
- Read CLAUDE.md for project conventions
- Identify which existing files are relevant (services, controllers, schemas)
- Read the most relevant existing implementations as reference
3. **Plan the implementation**
- List the files that need to be created or modified
- Identify the order of operations (schema first, then service, then controller, then tests)
- Note any migration steps if the database changes
4. **Implement**
- Write the code following existing patterns
- After each file, run TypeScript type-checking to catch errors early
- Don't move on to the next file if the current one has type errors
5. **Write tests**
- Write unit tests for the new service logic
- Write integration tests for the new API endpoints
- Run all tests and fix any failures
6. **Commit**
- Run `git diff` to review all changes
- Write a conventional commit message
- Commit
refactor-module.md — refactor a file to a new pattern:
# Refactor Module
## Description
Refactor a file to use a specified pattern or convention.
## Steps
1. **Read the target file**
- Read $ARGUMENTS (the file to refactor)
- Understand its current structure and dependencies
2. **Identify what needs to change**
- List the specific changes required to match the target pattern
- Check for any callers that might need updating
3. **Make changes**
- Refactor the file
- Run TypeScript compiler on the file after changes
4. **Update callers if needed**
- Search for imports of this file
- Update any callers affected by interface changes
- Run type-checking again
5. **Run tests**
- Run existing tests for this module
- Fix any failures caused by the refactor
6. **Summarize**
- List all files changed and what changed in each
debug-error.md — systematic error investigation:
# Debug Error
## Description
Systematically trace and fix an error from a stack trace or error message.
## Steps
1. **Parse the error**
- Read the error message and stack trace from $ARGUMENTS
- Identify the file and line number where the error originates
2. **Read the relevant code**
- Read the file that's throwing
- Read 5-10 lines of context around the error line
- Note the function signature, inputs, and the specific line that fails
3. **Trace the call stack**
- Read the calling function(s)
- Trace backwards until you find where the invalid state is introduced
4. **Check recent changes**
- Run `git log --oneline -20` on the files involved
- If a recent commit is suspicious, read the diff
5. **Identify root cause**
- State the root cause clearly
- Explain why it's happening
6. **Propose and implement fix**
- Propose the fix
- Ask for confirmation before implementing
- Implement after confirmation
- Write a regression test that would have caught this
- Run tests to verify the fix
Invoking skills
You invoke a skill by name in your Claude Code session:
[Skill: review-pr 142]
Or you can ask Claude to use a skill:
Use the review-pr skill for PR #142
Claude Code's built-in Task tool can also invoke skills when a parent agent needs a subagent to execute a structured workflow. This is the bridge to multi-agent patterns — a parent agent can delegate complex tasks to subagents using defined skills, ensuring each subagent follows the same process.
Skills across a team
Like slash commands, skills in .claude/skills/ are committed to your repository. This makes them team-wide standards: everyone using Claude Code in the repo gets the same add-feature skill, the same debug-error workflow, the same review-pr process.
This has an interesting effect on code quality: you're not just standardizing Claude's behavior, you're encoding your team's engineering practices into executable form. The "how do we approach debugging" conversation becomes a documented skill that Claude follows. The "what does a good PR review include" question becomes a step-by-step skill anyone can invoke.
New developers get your team's standards applied automatically. Experienced developers get consistency without having to remember every step.
When skills are overkill
Not every workflow needs a skill. If you're doing something once, a regular prompt works fine. If it has two steps, a slash command with a detailed prompt is probably sufficient.
Skills add value when:
- The workflow has 4+ distinct phases
- The order matters and phases can't be collapsed
- You need to adapt based on intermediate results (check CI status before posting review)
- Multiple people on the team need to execute the same workflow consistently
The overhead of writing and maintaining a skill file isn't worth it for simple tasks. Save skills for the workflows that are genuinely complex and genuinely repeated.
The next lesson covers hooks — the mechanism for automatically running scripts before or after Claude uses a tool. Hooks work at a different layer than skills: they're reactions to Claude's actions, not orchestrated sequences Claude follows intentionally.