Skills — Step-by-Step Guide

What Skills Are For

A skill is a reusable, documented workflow. Use one when:

• You run the same multi-step process repeatedly (deploy, release, PR review)
• You want Claude to follow a strict procedure without deviation
• You want team members to have consistent workflows
• The task involves project-specific knowledge Claude shouldn’t have to rediscover each time

Step 1: Understand the File Structure

.claude/
└── skills/
    └── <skill-name>/
        └── SKILL.md          ← required
        └── <any other files> ← optional supporting files

The folder name becomes the slash command. A folder named deploy → /deploy.

User-level skills (work in every project):

~/.claude/skills/<skill-name>/SKILL.md

Step 2: Your First Skill

Create .claude/skills/check/SKILL.md:

---
title: "Check"
description: "Run lint and tests and report results"
---

# Check

Run the full quality check:

1. Run: `npm run lint`
2. Run: `npm test`
3. Report any failures clearly

If everything passes, confirm with a green summary.
If anything fails, show the exact error and suggest a fix.

Now type /check in a session. Claude runs lint and tests and reports back.

Step 3: Add Arguments

$ARGUMENTS receives everything after the slash command name.

.claude/skills/deploy/SKILL.md:

---
title: "Deploy"
description: "Deploy to an environment: staging or production"
---

# Deploy to $ARGUMENTS

Steps:
1. Validate environment: $ARGUMENTS must be "staging" or "production"
2. Run: `npm run test` — abort if tests fail
3. Run: `npm run build`
4. Run: `npm run deploy:$ARGUMENTS`
5. Run: `npm run smoke-test:$ARGUMENTS`
6. Report deployment URL and status

Usage: /deploy staging  or  /deploy production

Invoke:

/deploy staging
/deploy production

Step 4: Dynamic Shell Context

Use $(command) to inject live information:

.claude/skills/analyze-errors/SKILL.md:

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

# Analyze Errors

Current time: $(date)
App version: $(cat package.json | jq -r '.version')
Last 100 log lines:
$(tail -100 /var/log/myapp/app.log 2>/dev/null || echo "No log file found")

Analyze the above for:
- Errors and exceptions
- Performance warnings
- Unusual patterns

For each issue found:
1. Describe the problem
2. Identify the likely cause
3. Suggest a fix

Step 5: Require Approval

For risky or irreversible operations:

---
title: "Release"
description: "Tag and release a new version to npm"
require-approval: true
---

# Release

Version to release: $ARGUMENTS

Steps:
1. Confirm version format (must be semver: X.Y.Z)
2. Run: `npm run test` — abort if any test fails
3. Run: `npm run build`
4. Run: `npm version $ARGUMENTS`
5. Run: `git push && git push --tags`
6. Run: `npm publish`
7. Create GitHub release with changelog

require-approval: true means Claude asks the user to confirm before running the skill.

Step 6: Supporting Files

Skills can include helper scripts alongside SKILL.md:

.claude/skills/deploy/
├── SKILL.md
├── pre-deploy-checks.sh
├── post-deploy-verify.sh
└── rollback.sh

Reference them in SKILL.md:

---
title: "Deploy"
---

# Deploy

1. Run pre-deploy checks: `bash .claude/skills/deploy/pre-deploy-checks.sh $ARGUMENTS`
2. Run: `npm run deploy:$ARGUMENTS`
3. Run verification: `bash .claude/skills/deploy/post-deploy-verify.sh $ARGUMENTS`

If verification fails, run rollback:
`bash .claude/skills/deploy/rollback.sh $ARGUMENTS`

Step 7: Disable Auto-Invocation

By default, Claude may invoke a skill automatically when the task seems to match. To prevent this and require explicit /skill-name invocation:

---
title: "Nuke Database"
description: "Drop and recreate the local development database"
disable-model-invocation: true
require-approval: true
---

# Nuke Database

WARNING: This deletes all local data.

1. Run: `npm run db:drop`
2. Run: `npm run db:create`
3. Run: `npm run db:migrate`
4. Run: `npm run db:seed`

Real-World Skill Examples

PR Workflow

.claude/skills/open-pr/SKILL.md:

---
title: "Open PR"
description: "Commit, push, and open a pull request for current changes"
---

# Open PR

PR title: $ARGUMENTS

Steps:
1. Run: `git status` — confirm changes exist
2. Run: `npm run lint` — fix any issues
3. Run: `npm test` — abort if tests fail
4. Stage all changes: `git add -A`
5. Commit: `git commit -m "$ARGUMENTS"`
6. Push: `git push -u origin HEAD`
7. Create PR: `gh pr create --title "$ARGUMENTS" --body "$(cat .github/PULL_REQUEST_TEMPLATE.md 2>/dev/null || echo 'Auto-generated PR')"`
8. Print the PR URL

Feature Scaffold

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

---
title: "New Feature"
description: "Scaffold a new feature with tests, implementation, and docs"
---

# New Feature: $ARGUMENTS

## Planning
First, read:
- `src/` — understand existing patterns
- `src/__tests__/` — understand test conventions
- `CLAUDE.md` — check for specific requirements

## Steps
1. Create branch: `git checkout -b feature/$ARGUMENTS`
2. Write tests first in `src/__tests__/$ARGUMENTS.test.ts`
3. Implement in `src/$ARGUMENTS.ts`
4. Export from barrel: add to `src/index.ts`
5. Run: `npm test` — all tests must pass
6. Run: `npm run lint` — must be clean
7. Commit: `git commit -m "feat: $ARGUMENTS"`

## Conventions
- TypeScript, named exports only
- Each function must have a corresponding test
- Use existing patterns from `src/utils/`

Hotfix

.claude/skills/hotfix/SKILL.md:

---
title: "Hotfix"
description: "Apply an emergency fix directly to main"
require-approval: true
---

# Hotfix: $ARGUMENTS

EMERGENCY FIX — bypasses normal feature branch workflow.

1. Confirm we are on main: `git branch --show-current`
2. Pull latest: `git pull origin main`
3. Create hotfix branch: `git checkout -b hotfix/$ARGUMENTS`
4. Fix the issue described: $ARGUMENTS
5. Run: `npm run test:critical` — fast critical path tests
6. Commit with hotfix prefix: `git commit -m "hotfix: $ARGUMENTS"`
7. Push: `git push -u origin HEAD`
8. Open PR marked urgent: `gh pr create --label urgent --title "hotfix: $ARGUMENTS"`
9. Print the PR URL for immediate review

Post-fix: notify team via Slack (if mcp__slack configured).

Debugging a Skill

If a skill isn’t working as expected:

1. Run it manually and observe what Claude does: /my-skill
2. Check if the skill is being found: /help (skill should appear in the list)
3. Verify the SKILL.md frontmatter has both title and description
4. Use --verbose to see full tool call details
5. Test supporting scripts independently: bash .claude/skills/deploy/pre-checks.sh staging

🧠 Quick Recall

• Trick: “Frontmatter sells it, body tells it.”

👨‍🏫 Teach It

• Show: build /release-notes from git log, live, in 5 minutes.
• They’ll trip on: one skill trying to do three jobs — one job per skill.

---

Learning path: ⬅ 20-skills.md · Index · ➡ 22-skills-real-examples.md