name: "Claude Code Skill Definition" description: "A SKILL.md file that defines a Claude Code skill with metadata, instructions, and examples" path_patterns:

• ".claude/skills/*/SKILL.md"
• ".claude/skills/**/SKILL.md" target_audience: "Claude Code agents auto-selecting skills based on user intent" frequency: "Created once per skill, updated as requirements evolve" quality_criteria:
• name: Kebab-Case Name description: "Skill name must be lowercase with hyphens only (e.g., github-pr-review, unit-test-generator). No underscores, spaces, or reserved words like anthropic, claude, or general."
• name: Third-Person Description description: "Description must be written in third person (e.g., 'Generates...' not 'I generate...'). Under 300 characters. Must clearly state WHAT the skill does and WHEN to use it."
• name: Discoverable Keywords description: "Description must include specific technical terms a user might say (e.g., 'PostgreSQL', 'React components', 'AWS Lambda') to enable reliable auto-selection."
• name: Progressive Disclosure description: "Main SKILL.md file must be under 500 lines. Large reference docs or schemas must be split into separate support files loaded on demand."
• name: Input Handling description: "Must clearly define required inputs before execution begins. Instructions must tell Claude to ask the user for missing inputs rather than guessing."
• name: Output Format description: "Must explicitly state how output should be formatted (e.g., 'Output as a JSON block' or 'Create a markdown file at path X')."
• name: Worked Example description: "Must include at least one Input -> Output example showing the ideal result. Few-shot examples significantly reduce hallucinations."
• name: Guardrails Section description: "Must include a section listing what Claude should NOT do (e.g., 'Do not delete existing comments', 'Do not mock database connections')."
• name: Concrete File References description: "Instructions must use specific file paths, not vague descriptions (e.g., 'Read src/config.json' not 'Read the config file')."
• name: Plan Before Action description: "For complex tasks, instructions must include an analysis/planning step before implementation begins."

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

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?