Initial commit

skills/pr/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: pr
+description: Automate creating pull requests - fork repos, create branches, commit changes, and submit PRs. Works in current directory or creates new clone. Idempotent and safe to re-run. Keywords - PR, pull request, fork, contribute, upstream.
+allowed-tools: [Bash, Read, Write, Edit, Glob, Grep]
+---
+
+# PR - Pull Request Automation
+
+Automate creating pull requests from start to finish.
+
+## What This Does
+
+1. Fork the repository (if needed)
+2. Clone or use existing local repo
+3. Create feature branch from upstream
+4. Auto-commit your changes
+5. Push and create PR
+
+## Quick Start
+
+**Basic workflow:**
+```bash
+# 1. Fork, clone, and create branch
+bash ~/.claude/skills/pr/scripts/01-fork-and-setup.sh \
+  owner/repo \
+  ~/code \
+  1 \
+  main \
+  my-feature
+
+# 2. Make your changes (use Edit tool)...
+
+# 3. Auto-commit and create PR
+bash ~/.claude/skills/pr/scripts/03-create-pr.sh \
+  main \
+  "PR title" \
+  "PR description"
+```
+
+**Current directory mode:**
+```bash
+cd /path/to/your/repo
+bash ~/.claude/skills/pr/scripts/01-fork-and-setup.sh owner/repo . "" main my-feature
+# Make changes...
+bash ~/.claude/skills/pr/scripts/03-create-pr.sh main "Fix bug"
+```
+
+## Scripts
+
+### `01-fork-and-setup.sh` - Setup repo and branch
+
+```bash
+01-fork-and-setup.sh <repo> [work_dir] [depth] [base_branch] [feature_branch]
+```
+
+**Parameters:**
+- `repo` - Repository to fork (e.g., `owner/repo`)
+- `work_dir` - Where to clone (default: `~/tmp/contribute`, use `.` for current dir)
+- `depth` - Clone depth (default: full, use `1` for 10x faster shallow clone)
+- `base_branch` - Branch to base work on (e.g., `main`)
+- `feature_branch` - Your new branch name (e.g., `fix/bug-123`)
+
+**What it does:**
+- Creates fork if needed (detects existing forks, even with different names)
+- Clones repo or uses existing local copy
+- Sets up `upstream` (original) and `origin` (fork) remotes
+- Creates feature branch from latest upstream
+- **Idempotent** - Safe to re-run multiple times
+
+### `03-create-pr.sh` - Commit and create PR
+
+```bash
+03-create-pr.sh <base_branch> <pr_title> [pr_body] [commit_message]
+```
+
+**Parameters:**
+- `base_branch` - Target branch for PR (e.g., `main`)
+- `pr_title` - PR title
+- `pr_body` - PR description (optional)
+- `commit_message` - Commit message (optional, defaults to PR title)
+
+**What it does:**
+- Auto-commits any uncommitted changes with DCO sign-off
+- Pushes branch to your fork
+- Checks for existing PRs (avoids duplicates)
+- Creates PR to upstream
+- Returns PR URL
+- **Idempotent** - Won't create duplicate PRs
+
+## Examples
+
+### Example 1: Fix bug in upstream repo
+
+```bash
+# User request: "Fix version 2.9 to 2.15 in stolostron/multicluster-global-hub"
+
+# Step 1: Setup
+bash ~/.claude/skills/pr/scripts/01-fork-and-setup.sh \
+  stolostron/multicluster-global-hub \
+  ~/tmp/contribute \
+  1 \
+  main \
+  docs/fix-version
+
+# Step 2: Make changes (using Edit tool to modify files)
+# ... Edit files to change 2.9 to 2.15 ...
+
+# Step 3: Create PR
+bash ~/.claude/skills/pr/scripts/03-create-pr.sh \
+  main \
+  "docs: update version from 2.9 to 2.15" \
+  "Update documentation links to point to 2.15 instead of 2.9"
+```
+
+### Example 2: Work in current directory
+
+```bash
+# User is already in a git repo and wants to work there
+
+cd /path/to/existing/repo
+
+bash ~/.claude/skills/pr/scripts/01-fork-and-setup.sh \
+  owner/repo \
+  . \
+  "" \
+  main \
+  fix/issue-123
+
+# Make changes...
+
+bash ~/.claude/skills/pr/scripts/03-create-pr.sh \
+  main \
+  "Fix issue #123"
+```
+
+### Example 3: Handles fork name mismatches
+
+```bash
+# Scenario: Your fork is named "hub-of-hubs" but upstream is "multicluster-global-hub"
+# The script automatically detects this and handles it
+
+bash ~/.claude/skills/pr/scripts/01-fork-and-setup.sh \
+  stolostron/multicluster-global-hub \
+  ~/code \
+  1 \
+  main \
+  fix/bug
+
+# Output: "Found existing fork with different name: yanmxa/hub-of-hubs"
+# Script uses the correct fork name automatically
+```
+
+## Key Features
+
+✅ **Idempotent** - Safe to re-run, won't duplicate work
+✅ **Smart fork detection** - Finds forks even with different names
+✅ **Auto-fork** - Creates fork if it doesn't exist
+✅ **Auto-commit** - Commits changes with DCO sign-off
+✅ **No duplicates** - Checks for existing PRs before creating
+✅ **Current dir mode** - Can work in existing repos (use `.` as work_dir)
+✅ **Fast clone** - Shallow clone by default (10x faster)
+✅ **Proper remotes** - Sets up upstream (HTTPS) and origin (SSH)
+
+## Performance
+
+**Clone speed with depth=1:**
+| Repository | Full Clone | Shallow (depth=1) | Speedup |
+|------------|------------|-------------------|---------|
+| kubernetes | ~3GB | ~300MB | 10x |
+| Linux kernel | ~4GB | ~400MB | 10x |
+| Typical repo | ~500MB | ~50MB | 10x |
+
+## Prerequisites
+
+- **GitHub CLI (`gh`)** - Must be installed and authenticated
+  ```bash
+  brew install gh
+  gh auth login
+  ```
+
+- **Git** - Configured with name and email
+  ```bash
+  git config --global user.name "Your Name"
+  git config --global user.email "your.email@example.com"
+  ```
+
+- **SSH Keys** - Setup for GitHub (for cloning via SSH)
+
+## Troubleshooting
+
+**Fork already exists**
+→ Script handles automatically, uses existing fork
+
+**Repository already cloned**
+→ Script verifies and updates remotes
+
+**PR already exists**
+→ Script shows existing PR URL instead of creating duplicate
+
+**Fork has different name**
+→ Script detects via GitHub API and uses correct name
+
+**Current directory not a git repo**
+→ Don't use `.` as work_dir, or cd to a git repo first
+
+## Notes
+
+- All commits are signed with DCO (`-s` flag)
+- Uses `git add -u` (only modified/deleted files, not new untracked files)
+- Creates PRs with proper `username:branch` format
+- Handles both HTTPS (upstream) and SSH (origin) remotes
+- Color-coded output for easy reading