Claude Code Skill Definition: [skill-name]

A SKILL.md file defines a skill that Claude Code can auto-select based on user intent. Unlike slash commands (invoked explicitly via /command), skills are discovered and triggered automatically when Claude determines they match the user's request.

File Structure

.claude/
└── skills/
    ├── database-migration/       # Skill directory (kebab-case)
    │   ├── SKILL.md              # Entry point (required)
    │   └── schema-reference.txt  # Support file (loaded on demand)
    └── code-reviewer/
        └── SKILL.md

SKILL.md Format

Frontmatter (Required)

---
name: database-migration
description: "Generates database migration files for schema changes. Use when adding, modifying, or removing database tables or columns."
---

Body (Instructions)

The markdown body instructs Claude how to execute the skill once selected.

Example: Complete Skill Definition

---
name: github-pr-review
description: "Reviews GitHub pull requests for code quality, security issues, and adherence to project conventions. Use when the user mentions reviewing a PR, code review, or asks about changes in a pull request."
---

# github-pr-review

Reviews GitHub pull requests and provides structured feedback.

## Required Inputs

Before proceeding, ensure you have:
1. PR number or URL (ask user if not provided)
2. Review focus areas (optional: security, performance, style)

## Execution Steps

### Step 1: Analyze PR Context

Fetch the PR details and understand:
- Files changed and their purposes
- Base branch and target branch
- Related issues or requirements

### Step 2: Review Code Changes

For each changed file:
1. Check for security vulnerabilities
2. Verify error handling
3. Assess test coverage
4. Review naming conventions
5. Identify performance concerns

### Step 3: Generate Review

Create a structured review with:
- Summary of changes
- Critical issues (must fix)
- Suggestions (nice to have)
- Questions for the author

## Example

**Input:** "Review PR #42"

**Output:**

## PR #42 Review: Add user authentication

### Summary
This PR adds JWT-based authentication to the API endpoints.

### Critical Issues
1. **Line 45 in auth.js**: Token expiration not validated before use
2. **Line 89 in middleware.js**: Missing rate limiting on login endpoint

### Suggestions
- Consider adding refresh token rotation
- Add integration tests for the auth flow

### Questions
- Should failed login attempts trigger account lockout?

## Guardrails

- Do NOT approve or merge PRs automatically
- Do NOT modify code in the PR
- Do NOT dismiss existing reviews
- Do NOT share sensitive information found in code

Naming Conventions

| Bad Name | Good Name | Why? | |----------|-----------|------| | github | github-pr-review | "github" is too broad; be specific about the action | | process_data | csv-data-processor | Use hyphens, not underscores; specify the data type | | my-tool | unit-test-generator | Generic names are not discoverable; describe the output | | claude-helper | api-error-analyzer | Avoid reserved words; focus on functionality |

Description Best Practices

Good Description

"Generates database migration files from schema changes. Use when the user needs to add columns, create tables, or modify database structure."

Poor Description

"You can use this to help with database stuff."

What Makes a Good Description

1. Third person voice: "Generates..." not "I generate..."
2. Specific action: "migration files" not "database stuff"
3. Clear trigger: "Use when..." clause
4. Technical keywords: Terms users actually say

Subagent Delegation

For tasks requiring extensive file reading or research, delegate to a subagent to preserve context:

## Step 2: Analyze Codebase

Create a subagent to:
1. Scan the `src/` directory for circular dependencies
2. Identify unused exports
3. Return only a summary, not full file contents

This prevents the main context from being polluted with irrelevant code.

Testing Checklist

Before publishing, verify:

• [ ] Discovery Test: Clear history, ask a vague related question. Does the skill trigger?
• [ ] Argument Test: Omit a required input. Does Claude ask for it?
• [ ] Negative Test: Ask something outside scope. Does the skill stay silent?
• [ ] Edge Case Test: Empty inputs, large inputs, malformed data handled?