Build markdown-based playbooks that Claude follows on demand
Skills are reusable instructions packaged as markdown files. When Claude invokes a skill, it reads the SKILL.md file and follows its instructions — like giving Claude a playbook for a specific task.
| Feature | Skills | Hooks | Plugins |
|---|---|---|---|
| Format | Markdown (SKILL.md) | JSON config + scripts | Directory with manifest |
| Trigger | Claude decides or slash command | Automatic lifecycle events | Package of skills/hooks/MCP/etc. |
| Purpose | Domain knowledge + instructions | Deterministic automation | Distributable extensions |
Create a SKILL.md file with YAML frontmatter:
Full access
Unlock all 14 lessons, templates, and resources for Claude Code Mastery. Free.
---
description: Review code changes for security vulnerabilities
invocation: slash
command: /security-review
---
# Security Review
Review the current staged changes for:
1. SQL injection vulnerabilities
2. XSS risks
3. Hardcoded secrets or credentials
4. Insecure dependencies
5. Authentication/authorization issues
## Process
1. Run `git diff --staged` to see changes
2. Analyze each file for the above categories
3. Output findings in this format:
### Findings
| Severity | File | Line | Issue | Recommendation |
|----------|------|------|-------|----------------|
If no issues found, confirm the code passes security review.
---
invocation: auto | slash | manual
command: /my-command # For slash invocation
description: "When to invoke" # For auto invocation
tools: # Restrict available tools
- Read
- Grep
- Glob
disallowedTools: # Block specific tools
- Bash
- Edit
arguments: # Skill parameters
- name: target
description: "File or directory to review"
required: true
- name: format
description: "Output format (table|list)"
required: false
default: table
---
Q: What are the three invocation modes for skills, and when would you use each?
description field. Best for skills that should activate whenever a matching task comes up./command you type manually. Best for on-demand workflows you trigger explicitly.Provide domain knowledge that Claude uses during work:
---
description: Project architecture and conventions
invocation: auto
---
# Architecture Guide
## Directory Structure
- `src/api/` — API routes (Express)
- `src/services/` — Business logic
- `src/models/` — Database models (Prisma)
## Naming Conventions
- Files: kebab-case
- Classes: PascalCase
- Functions: camelCase
- Constants: UPPER_SNAKE_CASE
## Error Handling
Always use the AppError class from `src/utils/errors.ts`.
Never throw raw Error objects.
Step-by-step instructions for completing a workflow:
---
description: Create a new API endpoint
invocation: slash
command: /new-endpoint
arguments:
- name: name
description: Endpoint name (e.g., users)
required: true
---
# Create New API Endpoint: {{name}}
1. Create `src/api/{{name}}.ts` with Express router
2. Create `src/services/{{name}}-service.ts` with business logic
3. Create `src/models/{{name}}.prisma` schema
4. Add route to `src/api/index.ts`
5. Create `src/tests/{{name}}.test.ts`
6. Run `pnpm test` to verify
7. Run `pnpm lint` to check
Q: How do skill arguments work? What happens when you type /new-endpoint users?
The argument users is passed to the skill and replaces {{name}} throughout the markdown. So Claude will create src/api/users.ts, src/services/users-service.ts, etc. Arguments can be required: true (must provide) or required: false with a default value.
Limit what tools a skill can use for safety:
---
tools:
- Read
- Grep
- Glob
---
This skill can only read files — it can't edit, write, or run commands.
Pro Tip: Use tool restrictions to create "safe" review skills that can analyze code but never modify it.
Skills can include shell commands that inject dynamic data:
---
description: Review recent changes
invocation: slash
command: /review-recent
---
# Review Recent Changes
## Recent Commits
```bash
git log --oneline -10
git status --short
Review the above and provide a summary of recent activity.
## Subagent Execution
Skills can specify that they should run in a subagent (isolated context):
```yaml
---
description: Deep security audit
invocation: slash
command: /audit
subagent: true
model: opus
---
# Security Audit
Perform a comprehensive security audit of this codebase...
When subagent: true, the skill runs in an isolated context window, keeping the main session clean.
Fill in the blanks:
.claude/___/ (project) or ~/.claude/___/ (user)___: true in frontmatter/ in the ___.claude/skills/ or ~/.claude/skills/subagent: true/ in the prompt.claude/
└── skills/
├── deploy.md
├── review.md
└── new-feature.md
~/.claude/skills/
├── my-workflow.md
└── personal-helpers.md
Fill in the blanks:
auto, ___, manualtools: [Read, Grep, ___]{{___}} template syntaxslashGlob{{name}} (the argument name).claude/skills/ directory in your projectreview.md:
---
description: Review staged changes
invocation: slash
command: /review
tools:
- Read
- Grep
- Glob
---
Review `git diff --staged` for quality and style issues.
List any concerns in a markdown table.
/reviewReflection: How does the tool restriction affect what Claude can do during the review?
Scenario: Your team has a complex deployment process with 12 steps that must be followed in order. Developers keep forgetting steps. How would you solve this with skills?
Create a task skill with all 12 steps:
---
description: Deploy to production
invocation: slash
command: /deploy
---
# Production Deployment
Follow these steps in order:
1. Run `pnpm typecheck`
2. Run `pnpm lint`
3. Run `pnpm test`
4. Check `git status` is clean
5. Merge to main: `git checkout main && git pull && git merge -`
6. Tag release: `git tag v$(date +%Y%m%d.%H%M)`
7. Push: `git push origin main --tags`
8. Build: `pnpm build`
9. Deploy: `pnpm deploy:prod`
10. Run smoke tests: `pnpm test:smoke`
11. Verify health endpoint: `curl https://api.example.com/health`
12. Notify team in Slack
Stop and report if any step fails.
Now anyone can type /deploy and Claude follows the exact process every time.
| Concept | One-Liner |
|---|---|
| What skills are | Markdown instruction files (SKILL.md) with frontmatter |
| Three modes | auto (Claude decides), slash (you type), manual (explicit) |
| Reference skills | Provide domain knowledge (architecture, conventions) |
| Task skills | Step-by-step workflows (deploy, review, create endpoint) |
| Tool restrictions | tools: field limits what the skill can do |
| Subagent mode | subagent: true runs in isolated context |
| Placement | .claude/skills/ (project) or ~/.claude/skills/ (user) |
| Arguments | {{name}} template syntax in skill body |
Next up: Subagents — Parallel Workers → — Spawn isolated Claude instances for focused tasks.