# 1. Create skill directory
mkdir -p ~/.claude/skills/<skill-name>/references

# 2. Create SKILL.md with frontmatter
cat > ~/.claude/skills/<skill-name>/SKILL.md << 'EOF'
---
name: <skill-name>
description: <what it does>. Use when <trigger phrases>. <key capabilities>.
---

# <Skill Title>

<One-line description>

## Quick Start
<Minimal steps to use the skill>

## Core Workflow
<Step-by-step instructions>

## Important Rules
<Critical constraints and requirements>
EOF

# 3. Add helper scripts if value-add
# 4. Add reference files for detailed docs

---
name: skill-name          # lowercase, hyphens, no spaces
description: <desc>       # CRITICAL for discovery (max 1024 chars)
---

<What it does>. Use when <trigger phrases>. <Key capabilities>.

Creates GitHub Pull Requests with automated validation. Use when user wants
to create PR, open pull request, or merge feature. Validates tasks, runs
tests, generates Conventional Commits format.

#!/usr/bin/env python3
"""Script description."""

import json
import sys

def main():
    # Read from stdin or args
    # Process data
    # Output JSON to stdout
    print(json.dumps(result))

if __name__ == "__main__":
    main()

~/.claude/skills/<skill-name>/
├── SKILL.md              # Main skill file (< 500 lines)
├── scripts/              # Optional helper scripts
│   └── helper.py         # Only if value-add
└── references/           # Optional detailed docs
    ├── examples.md       # Extended examples
    └── guide.md          # Deep-dive documentation

SKILL.md (primary)
    ↓ references/ (when needed)
        ↓ external links (rarely)

**ALWAYS** confirm before:
- Modifying files
- Running destructive commands
- Creating external resources (PRs, issues)

# Good: Structured, parseable
python3 script.py | jq '.result'

# Bad: Unstructured text
python3 script.py | grep "Result:"

Handles PR review comments with severity classification. Use when user
wants to resolve PR comments, handle review feedback, or fix review
comments. Fetches via GitHub CLI, classifies by severity, proposes fixes.

# 1. Get PR number
PR=$(gh pr view --json number -q '.number')

# 2. Fetch and classify comments
gh api repos/{owner}/{repo}/pulls/$PR/comments | \
  python3 ~/.claude/skills/github-pr-review/scripts/classify_comments.py

# 3. Process each comment: show → propose → confirm → apply
# 4. Commit: git commit -m "fix(scope): address review - [desc]"
# 5. Reply and push

## Important Rules

- **ALWAYS** confirm before modifying files
- **ALWAYS** verify ALL issues in multi-issue comments
- **NEVER** skip user confirmation for file changes
- Group related changes → single commit