Claude Code Skills: Teach Claude Your Workflow (2026 Guide)

mkdir -p ~/.claude/skills/commit-helper

---
name: commit-helper
description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
---

# Commit Message Generator

## Instructions

1. Run `git diff --staged` to see changes
2. Generate a commit message with:
   - Summary under 50 characters (imperative mood)
   - Blank line
   - Detailed description of what and why
   - List of affected components

## Format

```text
[type]: [summary]

[detailed description]

Affected: [components]

**Step 3: Restart and test**

Restart Claude Code to load the new Skill. Then test it:

Claude should ask to use the `commit-helper` Skill, then follow your format exactly.

## SKILL.md Structure

Every Skill needs a `SKILL.md` file with two parts: YAML metadata and Markdown instructions.

```yaml
---
name: your-skill-name
description: What it does and when to use it
allowed-tools: Read, Grep, Glob  # Optional: restrict tools
model: claude-sonnet-4-20250514  # Optional: specific model
---

# Your Skill Name

## Instructions
Step-by-step guidance for Claude.

## Examples
Concrete examples showing the Skill in action.

my-skill/
├── SKILL.md          # Overview and navigation
├── reference.md      # Detailed API docs (loaded when needed)
├── examples.md       # Usage examples (loaded when needed)
└── scripts/
    └── helper.py     # Utility script (executed, not loaded)

## Overview

[Essential instructions here]

## Additional Resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

## Utility Scripts

To validate input, run:
```bash
python scripts/helper.py input.txt

**Key insight:** Scripts in your Skill directory can be executed without loading their contents into context. Only the output consumes tokens. This is powerful for:

- Complex validation logic
- Data processing that's more reliable as code
- Operations that benefit from consistency

Keep `SKILL.md` under 500 lines. If you need more, split into separate files.

## Restrict Tool Access

Use `allowed-tools` to limit what Claude can do when a Skill is active:

```yaml
---
name: safe-reader
description: Read files without making changes. Use for read-only file access.
allowed-tools: Read, Grep, Glob
---

# Safe File Reader

This Skill provides read-only file access.

## Instructions
1. Use Read to view file contents
2. Use Grep to search within files
3. Use Glob to find files by pattern

---
name: pr-review
description: Reviews pull requests for code quality, security, and best practices. Use when reviewing PRs or code changes.
---

# PR Review

## Checklist

1. **Correctness** — Does the code do what it's supposed to?
2. **Security** — Any vulnerabilities? Input validation? Auth checks?
3. **Performance** — Any obvious bottlenecks? N+1 queries?
4. **Maintainability** — Is the code readable? Well-structured?
5. **Tests** — Are there tests? Do they cover edge cases?

## Output Format

### Summary
[One paragraph overview]

### Issues Found
- 🔴 Critical: [blocking issues]
- 🟡 Suggestions: [improvements]
- 🟢 Nitpicks: [minor things]

### Verdict
[Approve / Request Changes / Comment]

---
name: db-queries
description: Write database queries following our patterns. Use when writing SQL or database operations.
allowed-tools: Read, Bash(psql:*)
---

# Database Queries

## Our Schema

See [schema.md](schema.md) for table definitions.

## Conventions

- Always use parameterized queries
- Include LIMIT on SELECT statements
- Use transactions for multi-step operations
- Log slow queries (>100ms)

## Common Patterns

### Pagination
```sql
SELECT * FROM users
ORDER BY created_at DESC
LIMIT $1 OFFSET $2

UPDATE records
SET deleted_at = NOW()
WHERE id = $1

### Code Explainer Skill

```yaml
---
name: code-explainer
description: Explains code with visual diagrams and analogies. Use when explaining how code works or teaching about a codebase.
---

# Code Explainer

When explaining code, always include:

1. **Start with an analogy** — Compare to something from everyday life
2. **Draw a diagram** — Use ASCII art to show flow or structure
3. **Walk through step-by-step** — Explain what happens
4. **Highlight gotchas** — Common mistakes or misconceptions

Keep explanations conversational. For complex concepts, use multiple analogies.

# Bad
description: Helps with documents

# Good
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs or when the user mentions forms or document extraction.

~/.claude/skills/my-skill/SKILL.md     # Personal
.claude/skills/my-skill/SKILL.md        # Project