Skills (Custom Slash Commands)

Skills are reusable, documented workflows stored as markdown files. You invoke them with /skill-name, or Claude invokes them automatically when they match the task.

File Structure

.claude/
└── skills/
    ├── deploy/
    │   ├── SKILL.md          # required — the skill definition
    │   └── deploy.sh         # optional supporting files
    └── review-pr/
        └── SKILL.md

User-level skills (all projects):

~/.claude/
└── skills/
    └── my-reusable-skill/
        └── SKILL.md

Minimal Skill

.claude/skills/deploy/SKILL.md:

---
title: "Deploy to Production"
description: "Run tests and deploy the app to production"
---

# Deploy to Production

1. Run: `npm run test`
2. Run: `npm run build`
3. Run: `npm run deploy:prod`
4. Run: `npm run verify:prod`

If deployment fails, roll back with: `npm run deploy:rollback`

Invoke with:

/deploy

Frontmatter Options

---
title: "Skill Name"              # required — shown in /help
description: "What it does"      # required — used for auto-invocation matching
author: "your-name"              # optional
require-approval: false          # true = ask user before Claude runs it
disable-model-invocation: false  # true = only manual /skill-name, no auto-invoke
---

Arguments

Use $ARGUMENTS in the skill body to receive CLI arguments:

.claude/skills/deploy/SKILL.md:

---
title: "Deploy"
description: "Deploy to a specified environment"
---

# Deploy

Deploy to the environment: $ARGUMENTS

Valid environments: staging, production

Steps:
1. Run: `npm run test`
2. Run: `npm run build`
3. Run: `npm run deploy:$ARGUMENTS`

Invoke with:

/deploy staging
/deploy production

Dynamic Content (Shell Substitution)

---
title: "Analyze Logs"
description: "Analyze recent application logs for errors"
---

# Analyze Logs

Current time: $(date)
Last 50 log lines:
$(tail -50 /var/log/myapp/app.log)

Analyze the above for errors, warnings, and anomalies. Suggest fixes.

Multi-Step Workflow Skill

.claude/skills/new-feature/SKILL.md:

---
title: "New Feature"
description: "Scaffold and implement a new feature end-to-end"
require-approval: true
---

# New Feature Workflow

Feature name: $ARGUMENTS

## Steps

1. **Plan** — Explore relevant existing code, understand patterns
2. **Branch** — Create a git branch: `git checkout -b feature/$ARGUMENTS`
3. **Tests** — Write tests first in `src/__tests__/`
4. **Implement** — Implement in `src/`
5. **Lint** — Run `npm run lint`
6. **Verify** — Run `npm test` — all tests must pass
7. **Commit** — `git commit -m "feat: $ARGUMENTS"`

## Conventions
- Use TypeScript
- Named exports only
- Add to the barrel export in `src/index.ts`

Invoke a Skill

/new-feature user-authentication    # with argument
/deploy production                   # with argument
/code-review                         # bundled skill, no args

View Available Skills

/help    # all skills appear alongside built-in commands

🧠 Quick Recall

• Trick: “A skill is a recipe card — on the shelf until you cook.”
• The frontmatter description is the trigger.

👨‍🏫 Teach It

• Say: skills load on demand — zero cost until invoked.
• They’ll trip on: vague descriptions — the skill exists but never fires.

---

Learning path: ⬅ 19-project-structure.md · Index · ➡ 21-skills-step-by-step.md