Claude Code Skills: Teach AI Your Custom Workflows

Claude Code is one of the most powerful AI coding tools available. But out of the box, it’s generic. It doesn’t know your team’s code review checklist. It doesn’t know your API documentation format. It doesn’t know your commit message conventions.

Every time you explain the same workflow from scratch, you’re wasting tokens and time.

Claude Code Skills fix this. A Skill is a reusable set of instructions — packaged as a simple Markdown file — that teaches Claude exactly how to perform a specific task your way. Once created, Claude auto-detects when a Skill is relevant and applies it without you lifting a finger.

This guide covers everything: what Skills are, how to create them, three practical examples you can copy today, the growing Skills ecosystem, and how Skills fit alongside CLAUDE.md and Hooks in the broader Claude Code configuration system.

What Are Claude Code Skills?

A Skill is a folder containing a SKILL.md file with two parts:

1. YAML frontmatter (between --- markers) that tells Claude when to use the Skill
2. Markdown content with instructions Claude follows when the Skill is invoked

Here’s the simplest possible Skill:

---
name: daily-standup
description: Generate a daily standup summary from git activity
---

Summarize today's git commits into a standup format:
1. What I did yesterday
2. What I'm doing today
3. Any blockers

That’s it. No code. No configuration files. No build steps. Just a Markdown file that teaches Claude a new capability.

Skills follow the Agent Skills open standard, which means they work across multiple AI tools — not just Claude Code. But Claude Code extends the standard with additional features like invocation control, subagent execution, and dynamic context injection.

How Skills Get Triggered

Claude Code uses a progressive disclosure pattern for Skills:

1. At startup: Only the frontmatter (name + description) loads into context — roughly 100 tokens per Skill
2. During conversation: Claude reads the descriptions to decide which Skills are relevant
3. On activation: The full Skill content loads when Claude determines it’s needed

This means you can have dozens of Skills installed without bloating your context window. Claude only loads what it needs, when it needs it.

You can also trigger any Skill manually using its name as a slash command:

/daily-standup

Both approaches work. Claude can auto-detect relevance from your conversation, or you can invoke a Skill directly when you know exactly what you want.

Skills vs. Slash Commands

If you’ve been using Claude Code for a while, you might be familiar with custom slash commands (files in .claude/commands/). Here’s how they relate to Skills:

The key difference: Slash Commands require you to type /command-name every time. Skills can be triggered automatically by Claude when it detects a relevant conversation context — no manual invocation needed.

Custom slash commands still work. A file at .claude/commands/review.md and a skill at .claude/skills/review/SKILL.md both create /review and behave the same way. But Skills add optional features: supporting file directories, frontmatter for invocation control, and automatic triggering. If a Skill and a command share the same name, the Skill takes precedence.

If you’re starting fresh, use Skills. If you have existing commands, they’ll keep working — migrate them when convenient.

When to Use Skills

Skills shine in specific scenarios. Here’s when to reach for them versus other Claude Code features:

Use Skills when you have:

• Repetitive workflows — Code reviews, PR creation, documentation generation, deployment checklists. Any task you do the same way every time.
• Domain expertise — Industry-specific knowledge, company conventions, framework-specific patterns. Things Claude doesn’t know by default.
• Fixed output formats — Standup reports, changelog entries, API documentation, test plans. Any task where the output structure matters.
• Team standards — Coding conventions, architectural patterns, naming rules. Things every team member should follow consistently.

Don’t use Skills for:

• Static project context — Use CLAUDE.md instead. Your tech stack, project structure, and general conventions belong in CLAUDE.md, not in a Skill.
• Guaranteed execution — Use Hooks instead. If a step must always run (like linting after file edits), a Hook guarantees it. Skills are suggestions — Claude decides whether to use them.
• One-off tasks — Just describe them in your prompt. Skills are for patterns you’ll reuse.

Creating Your First Skill

Let’s build a Skill step by step. We’ll create a code review Skill that enforces your team’s review checklist.

Step 1: Create the Skill Directory

Skills can live in two places:

For a code review Skill that applies to all your projects:

mkdir -p ~/.claude/skills/code-review

For a project-specific Skill:

mkdir -p .claude/skills/code-review

Step 2: Write SKILL.md

Create ~/.claude/skills/code-review/SKILL.md:

---
name: code-review
description: Perform a thorough code review following the team checklist. Use when reviewing code changes, pull requests, or when the user asks for a code review.
---

# Code Review Checklist

When reviewing code, evaluate every item in this checklist and provide a structured report.

## Review Process

1. **Read the diff** — Understand what changed and why
2. **Check each category** — Go through every section below
3. **Rate severity** — Flag issues as Critical, Warning, or Suggestion
4. **Summarize** — Provide an overall assessment

## Checklist Categories

### Correctness
- Does the logic handle edge cases?
- Are error paths handled properly?
- Could any input cause unexpected behavior?

### Security
- Is user input validated and sanitized?
- Are there any SQL injection, XSS, or CSRF risks?
- Are secrets hardcoded anywhere?

### Performance
- Are there unnecessary database queries or API calls?
- Could any loop cause O(n^2) or worse performance?
- Are large datasets paginated?

### Maintainability
- Are functions and variables named clearly?
- Is the code DRY (Don't Repeat Yourself)?
- Would a new team member understand this code?

### Testing
- Are there tests for the new code?
- Do tests cover edge cases and error paths?
- Are tests deterministic (no flaky tests)?

## Output Format

Structure your review as:

### Summary
[One-paragraph overall assessment]

### Critical Issues
[Must fix before merging]

### Warnings
[Should fix, but not blocking]

### Suggestions
[Nice to have improvements]

### Approved?
[YES / NO / YES WITH CONDITIONS]

Step 3: Test the Skill

Open Claude Code and test it both ways:

Auto-triggered — Ask something that matches the description:

Review the changes in src/auth/login.ts

Claude should recognize this as a code review request and automatically apply the Skill’s checklist.

Manually invoked — Use the slash command:

/code-review src/auth/login.ts

Both approaches should produce a structured review following your checklist format.

Step 4: Iterate

Your first version won’t be perfect. Watch how Claude uses the Skill, then refine:

• If Claude misses checklist items, make them more explicit
• If the output format isn’t quite right, add an example
• If the Skill triggers when it shouldn’t, narrow the description
• If it doesn’t trigger when it should, broaden the description

SKILL.md Anatomy

Every SKILL.md file has the same structure: YAML frontmatter for metadata, followed by Markdown content for instructions.

Frontmatter Reference

---
name: my-skill
description: What this skill does and when to use it
disable-model-invocation: true
user-invocable: true
allowed-tools: Read, Grep, Glob
argument-hint: [filename] [format]
model: opus
context: fork
agent: Explore
---

Here’s what each field does:

Content Structure

The Markdown content after the frontmatter is entirely freeform, but effective Skills typically include these sections:

1. Overview — What the Skill does (1-2 sentences)
2. Input Requirements — What Claude needs from the user
3. Step-by-Step Instructions — The actual workflow
4. Output Format — How to structure the result
5. Constraints — What to avoid, edge cases, guardrails

Variable Substitution

Skills support dynamic variables in the content:

Example using arguments:

---
name: fix-issue
description: Fix a GitHub issue by number
disable-model-invocation: true
---

Fix GitHub issue #$ARGUMENTS following our coding standards:

1. Read the issue description with `gh issue view $0`
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit referencing the issue

Running /fix-issue 423 replaces $ARGUMENTS with 423 and $0 with 423.

Dynamic Context Injection

The !`command` syntax runs shell commands before the Skill content is sent to Claude. The command output replaces the placeholder:

---
name: pr-summary
description: Summarize the current pull request
context: fork
agent: Explore
---

## Current PR Context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Task
Provide a concise summary of this pull request highlighting:
1. What changed and why
2. Potential risks
3. Suggested reviewers

When this Skill runs, each !`command` executes immediately. Claude only sees the final rendered content with actual PR data.

Three Practical Skills (Copy-Paste Ready)

Here are three production-ready Skills you can start using today.

Skill 1: Code Review with Checklist

Already covered above in the tutorial. Here’s the file path for quick reference:

~/.claude/skills/code-review/SKILL.md

Skill 2: API Documentation Generator

This Skill generates consistent API documentation from your source code. It reads endpoint handlers and produces standardized docs.

Create ~/.claude/skills/api-docs/SKILL.md:

---
name: api-docs
description: Generate API documentation from source code. Use when the user asks to document an API endpoint, route handler, or controller. Also triggers when creating or updating API reference documentation.
allowed-tools: Read, Grep, Glob
---

# API Documentation Generator

Generate comprehensive API documentation for the specified endpoint(s).

## Process

1. **Find the endpoint** — Locate the route handler, controller, or API function
2. **Analyze the code** — Read the implementation to understand:
   - HTTP method and path
   - Request parameters (path, query, body)
   - Authentication requirements
   - Response format and status codes
   - Error handling
3. **Check for existing docs** — Look for JSDoc, docstrings, or OpenAPI annotations
4. **Generate documentation** — Follow the output format below

## Output Format

For each endpoint, generate:

### `METHOD /path/to/endpoint`

**Description**: One-sentence description of what this endpoint does.

**Authentication**: Required / Optional / None

**Parameters**:

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| id | path | string | Yes | Resource identifier |
| limit | query | integer | No | Max results (default: 20) |

**Request Body** (if applicable):

```json
{
  "field": "type — description"
}

Response 200 OK:

{
  "data": "example response"
}

Error Responses:

Example:

curl -X METHOD https://api.example.com/path \
  -H "Authorization: Bearer TOKEN" \
  -d '{"field": "value"}'

Constraints

• Always include real field names and types from the source code
• Document all possible error responses, not just the happy path
• If authentication middleware is present, always note it
• Use the project’s actual base URL if found in configuration
• Flag any undocumented endpoints as needing attention

### Skill 3: Git Commit Message Standardizer

This Skill enforces [Conventional Commits](https://www.conventionalcommits.org/) format with your team's specific rules.

Create `~/.claude/skills/commit-msg/SKILL.md`:

```yaml
---
name: commit-msg
description: Generate a standardized git commit message following Conventional Commits format. Use when the user asks to commit, create a commit message, or after completing a task that should be committed.
disable-model-invocation: true
---

# Commit Message Generator

Generate a git commit message following our team's Conventional Commits standard.

## Process

1. Run `git diff --staged` to see what's being committed
2. If nothing is staged, run `git diff` and ask the user what to stage
3. Analyze the changes to determine the commit type and scope
4. Generate the commit message following the format below

## Commit Format

():