diff --git a/docs/README.skills.md b/docs/README.skills.md
index b66b3bd76..9975ced6a 100644
--- a/docs/README.skills.md
+++ b/docs/README.skills.md
@@ -174,7 +174,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
| [gen-specs-as-issues](../skills/gen-specs-as-issues/SKILL.md)
`gh skills install github/awesome-copilot gen-specs-as-issues` | This workflow guides you through a systematic approach to identify missing features, prioritize them, and create detailed specifications for implementation. | None |
| [generate-custom-instructions-from-codebase](../skills/generate-custom-instructions-from-codebase/SKILL.md)
`gh skills install github/awesome-copilot generate-custom-instructions-from-codebase` | Migration and code evolution instructions generator for GitHub Copilot. Analyzes differences between two project versions (branches, commits, or releases) to create precise instructions allowing Copilot to maintain consistency during technology migrations, major refactoring, or framework version upgrades. | None |
| [geofeed-tuner](../skills/geofeed-tuner/SKILL.md)
`gh skills install github/awesome-copilot geofeed-tuner` | Use this skill whenever the user mentions IP geolocation feeds, RFC 8805, geofeeds, or wants help creating, tuning, validating, or publishing a self-published IP geolocation feed in CSV format. Intended user audience is a network operator, ISP, mobile carrier, cloud provider, hosting company, IXP, or satellite provider asking about IP geolocation accuracy, or geofeed authoring best practices. Helps create, refine, and improve CSV-format IP geolocation feeds with opinionated recommendations beyond RFC 8805 compliance. Do NOT use for private or internal IP address management — applies only to publicly routable IP addresses. | `assets/example`
`assets/iso3166-1.json`
`assets/iso3166-2.json`
`assets/small-territories.json`
`references/rfc8805.txt`
`references/snippets-python3.md`
`scripts/templates` |
-| [gh-cli](../skills/gh-cli/SKILL.md)
`gh skills install github/awesome-copilot gh-cli` | GitHub CLI (gh) comprehensive reference for repositories, issues, pull requests, Actions, projects, releases, gists, codespaces, organizations, extensions, and all GitHub operations from the command line. | None |
+| [gh-cli](../skills/gh-cli/SKILL.md)
`gh skills install github/awesome-copilot gh-cli` | Use when running GitHub CLI (gh) commands — auth, repos, issues, PRs, Actions/workflows, releases, projects, gists, codespaces, rulesets, or any `gh api` REST/GraphQL call from the command line. | `reference` |
| [git-commit](../skills/git-commit/SKILL.md)
`gh skills install github/awesome-copilot git-commit` | Execute git commit with conventional commit message analysis, intelligent staging, and message generation. Use when user asks to commit changes, create a git commit, or mentions "/commit". Supports: (1) Auto-detecting type and scope from changes, (2) Generating conventional commit messages from diff, (3) Interactive commit with optional type/scope/description overrides, (4) Intelligent file staging for logical grouping | None |
| [git-flow-branch-creator](../skills/git-flow-branch-creator/SKILL.md)
`gh skills install github/awesome-copilot git-flow-branch-creator` | Intelligent Git Flow branch creator that analyzes git status/diff and creates appropriate branches following the nvie Git Flow branching model. | None |
| [github-copilot-starter](../skills/github-copilot-starter/SKILL.md)
`gh skills install github/awesome-copilot github-copilot-starter` | Set up complete GitHub Copilot configuration for a new project based on technology stack | None |
diff --git a/skills/gh-cli/SKILL.md b/skills/gh-cli/SKILL.md
index 6756f0b5d..17fd1990d 100644
--- a/skills/gh-cli/SKILL.md
+++ b/skills/gh-cli/SKILL.md
@@ -1,2187 +1,90 @@
---
name: gh-cli
-description: GitHub CLI (gh) comprehensive reference for repositories, issues, pull requests, Actions, projects, releases, gists, codespaces, organizations, extensions, and all GitHub operations from the command line.
+description: Use when running GitHub CLI (gh) commands — auth, repos, issues, PRs, Actions/workflows, releases, projects, gists, codespaces, rulesets, or any `gh api` REST/GraphQL call from the command line.
---
# GitHub CLI (gh)
-Comprehensive reference for GitHub CLI (gh) - work seamlessly with GitHub from the command line.
+Comprehensive reference for `gh`, loaded on demand.
-**Version:** 2.85.0 (current as of January 2026)
+**Rule:** read the router below, then open only the reference file(s) the task needs. Don't load all of them preemptively.
-## Prerequisites
+## How to use this skill
-### Installation
+1. Identify the command group from the task (e.g. "open a PR" → `pr`, "trigger a workflow" → `actions`).
+2. Read that one file from `reference/` — each is self-contained with flags and examples.
+3. Fall back to `gh --help` for rarely used flags not documented here.
-```bash
-# macOS
-brew install gh
-
-# Linux
-curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
-echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
-sudo apt update
-sudo apt install gh
-
-# Windows
-winget install --id GitHub.cli
-
-# Verify installation
-gh --version
-```
-
-### Authentication
-
-```bash
-# Interactive login (default: github.com)
-gh auth login
-
-# Login with specific hostname
-gh auth login --hostname enterprise.internal
-
-# Login with token
-gh auth login --with-token < mytoken.txt
-
-# Check authentication status
-gh auth status
-
-# Switch accounts
-gh auth switch --hostname github.com --user username
-
-# Logout
-gh auth logout --hostname github.com --user username
-```
-
-### Setup Git Integration
-
-```bash
-# Configure git to use gh as credential helper
-gh auth setup-git
-
-# View active token
-gh auth token
-
-# Refresh authentication scopes
-gh auth refresh --scopes write:org,read:public_key
-```
-
-## CLI Structure
-
-```
-gh # Root command
-├── auth # Authentication
-│ ├── login
-│ ├── logout
-│ ├── refresh
-│ ├── setup-git
-│ ├── status
-│ ├── switch
-│ └── token
-├── browse # Open in browser
-├── codespace # GitHub Codespaces
-│ ├── code
-│ ├── cp
-│ ├── create
-│ ├── delete
-│ ├── edit
-│ ├── jupyter
-│ ├── list
-│ ├── logs
-│ ├── ports
-│ ├── rebuild
-│ ├── ssh
-│ ├── stop
-│ └── view
-├── gist # Gists
-│ ├── clone
-│ ├── create
-│ ├── delete
-│ ├── edit
-│ ├── list
-│ ├── rename
-│ └── view
-├── issue # Issues
-│ ├── create
-│ ├── list
-│ ├── status
-│ ├── close
-│ ├── comment
-│ ├── delete
-│ ├── develop
-│ ├── edit
-│ ├── lock
-│ ├── pin
-│ ├── reopen
-│ ├── transfer
-│ ├── unlock
-│ └── view
-├── org # Organizations
-│ └── list
-├── pr # Pull Requests
-│ ├── create
-│ ├── list
-│ ├── status
-│ ├── checkout
-│ ├── checks
-│ ├── close
-│ ├── comment
-│ ├── diff
-│ ├── edit
-│ ├── lock
-│ ├── merge
-│ ├── ready
-│ ├── reopen
-│ ├── revert
-│ ├── review
-│ ├── unlock
-│ ├── update-branch
-│ └── view
-├── project # Projects
-│ ├── close
-│ ├── copy
-│ ├── create
-│ ├── delete
-│ ├── edit
-│ ├── field-create
-│ ├── field-delete
-│ ├── field-list
-│ ├── item-add
-│ ├── item-archive
-│ ├── item-create
-│ ├── item-delete
-│ ├── item-edit
-│ ├── item-list
-│ ├── link
-│ ├── list
-│ ├── mark-template
-│ ├── unlink
-│ └── view
-├── release # Releases
-│ ├── create
-│ ├── list
-│ ├── delete
-│ ├── delete-asset
-│ ├── download
-│ ├── edit
-│ ├── upload
-│ ├── verify
-│ ├── verify-asset
-│ └── view
-├── repo # Repositories
-│ ├── create
-│ ├── list
-│ ├── archive
-│ ├── autolink
-│ ├── clone
-│ ├── delete
-│ ├── deploy-key
-│ ├── edit
-│ ├── fork
-│ ├── gitignore
-│ ├── license
-│ ├── rename
-│ ├── set-default
-│ ├── sync
-│ ├── unarchive
-│ └── view
-├── cache # Actions caches
-│ ├── delete
-│ └── list
-├── run # Workflow runs
-│ ├── cancel
-│ ├── delete
-│ ├── download
-│ ├── list
-│ ├── rerun
-│ ├── view
-│ └── watch
-├── workflow # Workflows
-│ ├── disable
-│ ├── enable
-│ ├── list
-│ ├── run
-│ └── view
-├── agent-task # Agent tasks
-├── alias # Command aliases
-│ ├── delete
-│ ├── import
-│ ├── list
-│ └── set
-├── api # API requests
-├── attestation # Artifact attestations
-│ ├── download
-│ ├── trusted-root
-│ └── verify
-├── completion # Shell completion
-├── config # Configuration
-│ ├── clear-cache
-│ ├── get
-│ ├── list
-│ └── set
-├── extension # Extensions
-│ ├── browse
-│ ├── create
-│ ├── exec
-│ ├── install
-│ ├── list
-│ ├── remove
-│ ├── search
-│ └── upgrade
-├── gpg-key # GPG keys
-│ ├── add
-│ ├── delete
-│ └── list
-├── label # Labels
-│ ├── clone
-│ ├── create
-│ ├── delete
-│ ├── edit
-│ └── list
-├── preview # Preview features
-├── ruleset # Rulesets
-│ ├── check
-│ ├── list
-│ └── view
-├── search # Search
-│ ├── code
-│ ├── commits
-│ ├── issues
-│ ├── prs
-│ └── repos
-├── secret # Secrets
-│ ├── delete
-│ ├── list
-│ └── set
-├── ssh-key # SSH keys
-│ ├── add
-│ ├── delete
-│ └── list
-├── status # Status overview
-└── variable # Variables
- ├── delete
- ├── get
- ├── list
- └── set
-```
-
-## Configuration
-
-### Global Configuration
-
-```bash
-# List all configuration
-gh config list
-
-# Get specific configuration value
-gh config list git_protocol
-gh config get editor
-
-# Set configuration value
-gh config set editor vim
-gh config set git_protocol ssh
-gh config set prompt disabled
-gh config set pager "less -R"
-
-# Clear configuration cache
-gh config clear-cache
-```
-
-### Environment Variables
-
-```bash
-# GitHub token (for automation)
-export GH_TOKEN=ghp_xxxxxxxxxxxx
-
-# GitHub hostname
-export GH_HOST=github.com
-
-# Disable prompts
-export GH_PROMPT_DISABLED=true
-
-# Custom editor
-export GH_EDITOR=vim
-
-# Custom pager
-export GH_PAGER=less
-
-# HTTP timeout
-export GH_TIMEOUT=30
-
-# Custom repository (override default)
-export GH_REPO=owner/repo
-
-# Custom git protocol
-export GH_ENTERPRISE_HOSTNAME=hostname
-```
-
-## Authentication (gh auth)
-
-### Login
-
-```bash
-# Interactive login
-gh auth login
-
-# Web-based authentication
-gh auth login --web
-
-# With clipboard for OAuth code
-gh auth login --web --clipboard
-
-# With specific git protocol
-gh auth login --git-protocol ssh
-
-# With custom hostname (GitHub Enterprise)
-gh auth login --hostname enterprise.internal
-
-# Login with token from stdin
-gh auth login --with-token < token.txt
-
-# Insecure storage (plain text)
-gh auth login --insecure-storage
-```
-
-### Status
-
-```bash
-# Show all authentication status
-gh auth status
-
-# Show active account only
-gh auth status --active
-
-# Show specific hostname
-gh auth status --hostname github.com
-
-# Show token in output
-gh auth status --show-token
-
-# JSON output
-gh auth status --json hosts
-
-# Filter with jq
-gh auth status --json hosts --jq '.hosts | add'
-```
-
-### Switch Accounts
-
-```bash
-# Interactive switch
-gh auth switch
-
-# Switch to specific user/host
-gh auth switch --hostname github.com --user monalisa
-```
-
-### Token
-
-```bash
-# Print authentication token
-gh auth token
-
-# Token for specific host/user
-gh auth token --hostname github.com --user monalisa
-```
-
-### Refresh
-
-```bash
-# Refresh credentials
-gh auth refresh
-
-# Add scopes
-gh auth refresh --scopes write:org,read:public_key
-
-# Remove scopes
-gh auth refresh --remove-scopes delete_repo
-
-# Reset to default scopes
-gh auth refresh --reset-scopes
-
-# With clipboard
-gh auth refresh --clipboard
-```
-
-### Setup Git
-
-```bash
-# Setup git credential helper
-gh auth setup-git
-
-# Setup for specific host
-gh auth setup-git --hostname enterprise.internal
-
-# Force setup even if host not known
-gh auth setup-git --hostname enterprise.internal --force
-```
-
-## Browse (gh browse)
-
-```bash
-# Open repository in browser
-gh browse
-
-# Open specific path
-gh browse script/
-gh browse main.go:312
-
-# Open issue or PR
-gh browse 123
-
-# Open commit
-gh browse 77507cd94ccafcf568f8560cfecde965fcfa63
-
-# Open with specific branch
-gh browse main.go --branch bug-fix
-
-# Open different repository
-gh browse --repo owner/repo
-
-# Open specific pages
-gh browse --actions # Actions tab
-gh browse --projects # Projects tab
-gh browse --releases # Releases tab
-gh browse --settings # Settings page
-gh browse --wiki # Wiki page
-
-# Print URL instead of opening
-gh browse --no-browser
-```
-
-## Repositories (gh repo)
-
-### Create Repository
-
-```bash
-# Create new repository
-gh repo create my-repo
-
-# Create with description
-gh repo create my-repo --description "My awesome project"
-
-# Create public repository
-gh repo create my-repo --public
-
-# Create private repository
-gh repo create my-repo --private
-
-# Create with homepage
-gh repo create my-repo --homepage https://example.com
-
-# Create with license
-gh repo create my-repo --license mit
-
-# Create with gitignore
-gh repo create my-repo --gitignore python
-
-# Initialize as template repository
-gh repo create my-repo --template
-
-# Create repository in organization
-gh repo create org/my-repo
-
-# Create without cloning locally
-gh repo create my-repo --source=.
-
-# Disable issues
-gh repo create my-repo --disable-issues
-
-# Disable wiki
-gh repo create my-repo --disable-wiki
-```
-
-### Clone Repository
-
-```bash
-# Clone repository
-gh repo clone owner/repo
-
-# Clone to specific directory
-gh repo clone owner/repo my-directory
-
-# Clone with different branch
-gh repo clone owner/repo --branch develop
-```
-
-### List Repositories
-
-```bash
-# List all repositories
-gh repo list
-
-# List repositories for owner
-gh repo list owner
-
-# Limit results
-gh repo list --limit 50
-
-# Public repositories only
-gh repo list --public
-
-# Source repositories only (not forks)
-gh repo list --source
-
-# JSON output
-gh repo list --json name,visibility,owner
-
-# Table output
-gh repo list --limit 100 | tail -n +2
-
-# Filter with jq
-gh repo list --json name --jq '.[].name'
-```
-
-### View Repository
-
-```bash
-# View repository details
-gh repo view
-
-# View specific repository
-gh repo view owner/repo
-
-# JSON output
-gh repo view --json name,description,defaultBranchRef
-
-# View in browser
-gh repo view --web
-```
-
-### Edit Repository
-
-```bash
-# Edit description
-gh repo edit --description "New description"
-
-# Set homepage
-gh repo edit --homepage https://example.com
-
-# Change visibility
-gh repo edit --visibility private
-gh repo edit --visibility public
-
-# Enable/disable features
-gh repo edit --enable-issues
-gh repo edit --disable-issues
-gh repo edit --enable-wiki
-gh repo edit --disable-wiki
-gh repo edit --enable-projects
-gh repo edit --disable-projects
-
-# Set default branch
-gh repo edit --default-branch main
-
-# Rename repository
-gh repo rename new-name
-
-# Archive repository
-gh repo archive
-gh repo unarchive
-```
-
-### Delete Repository
-
-```bash
-# Delete repository
-gh repo delete owner/repo
-
-# Confirm without prompt
-gh repo delete owner/repo --yes
-```
-
-### Fork Repository
-
-```bash
-# Fork repository
-gh repo fork owner/repo
-
-# Fork to organization
-gh repo fork owner/repo --org org-name
-
-# Clone after forking
-gh repo fork owner/repo --clone
-
-# Remote name for fork
-gh repo fork owner/repo --remote-name upstream
-```
-
-### Sync Fork
-
-```bash
-# Sync fork with upstream
-gh repo sync
-
-# Sync specific branch
-gh repo sync --branch feature
-
-# Force sync
-gh repo sync --force
-```
-
-### Set Default Repository
-
-```bash
-# Set default repository for current directory
-gh repo set-default
-
-# Set default explicitly
-gh repo set-default owner/repo
-
-# Unset default
-gh repo set-default --unset
-```
-
-### Repository Autolinks
-
-```bash
-# List autolinks
-gh repo autolink list
-
-# Add autolink
-gh repo autolink add \
- --key-prefix JIRA- \
- --url-template https://jira.example.com/browse/
-
-# Delete autolink
-gh repo autolink delete 12345
-```
-
-### Repository Deploy Keys
-
-```bash
-# List deploy keys
-gh repo deploy-key list
-
-# Add deploy key
-gh repo deploy-key add ~/.ssh/id_rsa.pub \
- --title "Production server" \
- --read-only
-
-# Delete deploy key
-gh repo deploy-key delete 12345
-```
-
-### Gitignore and License
-
-```bash
-# View gitignore template
-gh repo gitignore
-
-# View license template
-gh repo license mit
-
-# License with full name
-gh repo license mit --fullname "John Doe"
-```
-
-## Issues (gh issue)
-
-### Create Issue
-
-```bash
-# Create issue interactively
-gh issue create
-
-# Create with title
-gh issue create --title "Bug: Login not working"
-
-# Create with title and body
-gh issue create \
- --title "Bug: Login not working" \
- --body "Steps to reproduce..."
-
-# Create with body from file
-gh issue create --body-file issue.md
-
-# Create with labels
-gh issue create --title "Fix bug" --labels bug,high-priority
-
-# Create with assignees
-gh issue create --title "Fix bug" --assignee user1,user2
-
-# Create in specific repository
-gh issue create --repo owner/repo --title "Issue title"
-
-# Create issue from web
-gh issue create --web
-```
-
-### List Issues
-
-```bash
-# List all open issues
-gh issue list
-
-# List all issues (including closed)
-gh issue list --state all
-
-# List closed issues
-gh issue list --state closed
-
-# Limit results
-gh issue list --limit 50
-
-# Filter by assignee
-gh issue list --assignee username
-gh issue list --assignee @me
-
-# Filter by labels
-gh issue list --labels bug,enhancement
-
-# Filter by milestone
-gh issue list --milestone "v1.0"
-
-# Search/filter
-gh issue list --search "is:open is:issue label:bug"
-
-# JSON output
-gh issue list --json number,title,state,author
-
-# Table view
-gh issue list --json number,title,labels --jq '.[] | [.number, .title, .labels[].name] | @tsv'
-
-# Show comments count
-gh issue list --json number,title,comments --jq '.[] | [.number, .title, .comments]'
-
-# Sort by
-gh issue list --sort created --order desc
-```
-
-### View Issue
-
-```bash
-# View issue
-gh issue view 123
-
-# View with comments
-gh issue view 123 --comments
-
-# View in browser
-gh issue view 123 --web
-
-# JSON output
-gh issue view 123 --json title,body,state,labels,comments
-
-# View specific fields
-gh issue view 123 --json title --jq '.title'
-```
-
-### Edit Issue
-
-```bash
-# Edit interactively
-gh issue edit 123
-
-# Edit title
-gh issue edit 123 --title "New title"
-
-# Edit body
-gh issue edit 123 --body "New description"
-
-# Add labels
-gh issue edit 123 --add-label bug,high-priority
-
-# Remove labels
-gh issue edit 123 --remove-label stale
-
-# Add assignees
-gh issue edit 123 --add-assignee user1,user2
-
-# Remove assignees
-gh issue edit 123 --remove-assignee user1
-
-# Set milestone
-gh issue edit 123 --milestone "v1.0"
-```
-
-### Close/Reopen Issue
-
-```bash
-# Close issue
-gh issue close 123
-
-# Close with comment
-gh issue close 123 --comment "Fixed in PR #456"
-
-# Reopen issue
-gh issue reopen 123
-```
-
-### Comment on Issue
-
-```bash
-# Add comment
-gh issue comment 123 --body "This looks good!"
-
-# Edit comment
-gh issue comment 123 --edit 456789 --body "Updated comment"
-
-# Delete comment
-gh issue comment 123 --delete 456789
-```
-
-### Issue Status
-
-```bash
-# Show issue status summary
-gh issue status
-
-# Status for specific repository
-gh issue status --repo owner/repo
-```
-
-### Pin/Unpin Issues
-
-```bash
-# Pin issue (pinned to repo dashboard)
-gh issue pin 123
-
-# Unpin issue
-gh issue unpin 123
-```
-
-### Lock/Unlock Issue
-
-```bash
-# Lock conversation
-gh issue lock 123
-
-# Lock with reason
-gh issue lock 123 --reason off-topic
-
-# Unlock
-gh issue unlock 123
-```
-
-### Transfer Issue
-
-```bash
-# Transfer to another repository
-gh issue transfer 123 --repo owner/new-repo
-```
-
-### Delete Issue
-
-```bash
-# Delete issue
-gh issue delete 123
-
-# Confirm without prompt
-gh issue delete 123 --yes
-```
-
-### Develop Issue (Draft PR)
-
-```bash
-# Create draft PR from issue
-gh issue develop 123
-
-# Create in specific branch
-gh issue develop 123 --branch fix/issue-123
-
-# Create with base branch
-gh issue develop 123 --base main
-```
-
-## Pull Requests (gh pr)
-
-### Create Pull Request
-
-```bash
-# Create PR interactively
-gh pr create
-
-# Create with title
-gh pr create --title "Feature: Add new functionality"
-
-# Create with title and body
-gh pr create \
- --title "Feature: Add new functionality" \
- --body "This PR adds..."
-
-# Fill body from template
-gh pr create --body-file .github/PULL_REQUEST_TEMPLATE.md
-
-# Set base branch
-gh pr create --base main
-
-# Set head branch (default: current branch)
-gh pr create --head feature-branch
-
-# Create draft PR
-gh pr create --draft
-
-# Add assignees
-gh pr create --assignee user1,user2
-
-# Add reviewers
-gh pr create --reviewer user1,user2
-
-# Add labels
-gh pr create --labels enhancement,feature
-
-# Link to issue
-gh pr create --issue 123
-
-# Create in specific repository
-gh pr create --repo owner/repo
-
-# Open in browser after creation
-gh pr create --web
-```
-
-### List Pull Requests
-
-```bash
-# List open PRs
-gh pr list
-
-# List all PRs
-gh pr list --state all
-
-# List merged PRs
-gh pr list --state merged
-
-# List closed (not merged) PRs
-gh pr list --state closed
-
-# Filter by head branch
-gh pr list --head feature-branch
-
-# Filter by base branch
-gh pr list --base main
-
-# Filter by author
-gh pr list --author username
-gh pr list --author @me
-
-# Filter by assignee
-gh pr list --assignee username
-
-# Filter by labels
-gh pr list --labels bug,enhancement
-
-# Limit results
-gh pr list --limit 50
-
-# Search
-gh pr list --search "is:open is:pr label:review-required"
-
-# JSON output
-gh pr list --json number,title,state,author,headRefName
-
-# Show check status
-gh pr list --json number,title,statusCheckRollup --jq '.[] | [.number, .title, .statusCheckRollup[]?.status]'
-
-# Sort by
-gh pr list --sort created --order desc
-```
-
-### View Pull Request
-
-```bash
-# View PR
-gh pr view 123
-
-# View with comments
-gh pr view 123 --comments
-
-# View in browser
-gh pr view 123 --web
-
-# JSON output
-gh pr view 123 --json title,body,state,author,commits,files
-
-# View diff
-gh pr view 123 --json files --jq '.files[].path'
-
-# View with jq query
-gh pr view 123 --json title,state --jq '"\(.title): \(.state)"'
-```
-
-### Checkout Pull Request
-
-```bash
-# Checkout PR branch
-gh pr checkout 123
-
-# Checkout with specific branch name
-gh pr checkout 123 --branch name-123
-
-# Force checkout
-gh pr checkout 123 --force
-```
-
-### Diff Pull Request
-
-```bash
-# View PR diff
-gh pr diff 123
-
-# View diff with color
-gh pr diff 123 --color always
-
-# Output to file
-gh pr diff 123 > pr-123.patch
-
-# View diff of specific files
-gh pr diff 123 --name-only
-```
-
-### Merge Pull Request
-
-```bash
-# Merge PR
-gh pr merge 123
-
-# Merge with specific method
-gh pr merge 123 --merge
-gh pr merge 123 --squash
-gh pr merge 123 --rebase
-
-# Delete branch after merge
-gh pr merge 123 --delete-branch
-
-# Merge with comment
-gh pr merge 123 --subject "Merge PR #123" --body "Merging feature"
-
-# Merge draft PR
-gh pr merge 123 --admin
-
-# Force merge (skip checks)
-gh pr merge 123 --admin
-```
-
-### Close Pull Request
-
-```bash
-# Close PR (as draft, not merge)
-gh pr close 123
-
-# Close with comment
-gh pr close 123 --comment "Closing due to..."
-```
-
-### Reopen Pull Request
-
-```bash
-# Reopen closed PR
-gh pr reopen 123
-```
-
-### Edit Pull Request
-
-```bash
-# Edit interactively
-gh pr edit 123
-
-# Edit title
-gh pr edit 123 --title "New title"
-
-# Edit body
-gh pr edit 123 --body "New description"
-
-# Add labels
-gh pr edit 123 --add-label bug,enhancement
-
-# Remove labels
-gh pr edit 123 --remove-label stale
-
-# Add assignees
-gh pr edit 123 --add-assignee user1,user2
-
-# Remove assignees
-gh pr edit 123 --remove-assignee user1
-
-# Add reviewers
-gh pr edit 123 --add-reviewer user1,user2
-
-# Remove reviewers
-gh pr edit 123 --remove-reviewer user1
-
-# Mark as ready for review
-gh pr edit 123 --ready
-```
-
-### Ready for Review
-
-```bash
-# Mark draft PR as ready
-gh pr ready 123
-```
-
-### Pull Request Checks
-
-```bash
-# View PR checks
-gh pr checks 123
-
-# Watch checks in real-time
-gh pr checks 123 --watch
-
-# Watch interval (seconds)
-gh pr checks 123 --watch --interval 5
-```
-
-### Comment on Pull Request
-
-```bash
-# Add comment
-gh pr comment 123 --body "Looks good!"
-
-# Comment on specific line
-gh pr comment 123 --body "Fix this" \
- --repo owner/repo \
- --head-owner owner --head-branch feature
-
-# Edit comment
-gh pr comment 123 --edit 456789 --body "Updated"
-
-# Delete comment
-gh pr comment 123 --delete 456789
-```
-
-### Review Pull Request
-
-```bash
-# Review PR (opens editor)
-gh pr review 123
-
-# Approve PR
-gh pr review 123 --approve --body "LGTM!"
-
-# Request changes
-gh pr review 123 --request-changes \
- --body "Please fix these issues"
-
-# Comment on PR
-gh pr review 123 --comment --body "Some thoughts..."
-
-# Dismiss review
-gh pr review 123 --dismiss
-```
-
-### Update Branch
-
-```bash
-# Update PR branch with latest base branch
-gh pr update-branch 123
-
-# Force update
-gh pr update-branch 123 --force
-
-# Use merge strategy
-gh pr update-branch 123 --merge
-```
-
-### Lock/Unlock Pull Request
-
-```bash
-# Lock PR conversation
-gh pr lock 123
-
-# Lock with reason
-gh pr lock 123 --reason off-topic
-
-# Unlock
-gh pr unlock 123
-```
-
-### Revert Pull Request
-
-```bash
-# Revert merged PR
-gh pr revert 123
-
-# Revert with specific branch name
-gh pr revert 123 --branch revert-pr-123
-```
-
-### Pull Request Status
-
-```bash
-# Show PR status summary
-gh pr status
-
-# Status for specific repository
-gh pr status --repo owner/repo
-```
-
-## GitHub Actions
-
-### Workflow Runs (gh run)
-
-```bash
-# List workflow runs
-gh run list
-
-# List for specific workflow
-gh run list --workflow "ci.yml"
-
-# List for specific branch
-gh run list --branch main
-
-# Limit results
-gh run list --limit 20
-
-# JSON output
-gh run list --json databaseId,status,conclusion,headBranch
-
-# View run details
-gh run view 123456789
-
-# View run with verbose logs
-gh run view 123456789 --log
-
-# View specific job
-gh run view 123456789 --job 987654321
-
-# View in browser
-gh run view 123456789 --web
-
-# Watch run in real-time
-gh run watch 123456789
-
-# Watch with interval
-gh run watch 123456789 --interval 5
-
-# Rerun failed run
-gh run rerun 123456789
-
-# Rerun specific job
-gh run rerun 123456789 --job 987654321
-
-# Cancel run
-gh run cancel 123456789
-
-# Delete run
-gh run delete 123456789
-
-# Download run artifacts
-gh run download 123456789
-
-# Download specific artifact
-gh run download 123456789 --name build
-
-# Download to directory
-gh run download 123456789 --dir ./artifacts
-```
-
-### Workflows (gh workflow)
-
-```bash
-# List workflows
-gh workflow list
-
-# View workflow details
-gh workflow view ci.yml
-
-# View workflow YAML
-gh workflow view ci.yml --yaml
-
-# View in browser
-gh workflow view ci.yml --web
-
-# Enable workflow
-gh workflow enable ci.yml
-
-# Disable workflow
-gh workflow disable ci.yml
-
-# Run workflow manually
-gh workflow run ci.yml
-
-# Run with inputs
-gh workflow run ci.yml \
- --raw-field \
- version="1.0.0" \
- environment="production"
-
-# Run from specific branch
-gh workflow run ci.yml --ref develop
-```
-
-### Action Caches (gh cache)
-
-```bash
-# List caches
-gh cache list
-
-# List for specific branch
-gh cache list --branch main
-
-# List with limit
-gh cache list --limit 50
-
-# Delete cache
-gh cache delete 123456789
-
-# Delete all caches
-gh cache delete --all
-```
-
-### Action Secrets (gh secret)
-
-```bash
-# List secrets
-gh secret list
-
-# Set secret (prompts for value)
-gh secret set MY_SECRET
-
-# Set secret from environment
-echo "$MY_SECRET" | gh secret set MY_SECRET
-
-# Set secret for specific environment
-gh secret set MY_SECRET --env production
-
-# Set secret for organization
-gh secret set MY_SECRET --org orgname
-
-# Delete secret
-gh secret delete MY_SECRET
-
-# Delete from environment
-gh secret delete MY_SECRET --env production
-```
-
-### Action Variables (gh variable)
-
-```bash
-# List variables
-gh variable list
-
-# Set variable
-gh variable set MY_VAR "some-value"
-
-# Set variable for environment
-gh variable set MY_VAR "value" --env production
-
-# Set variable for organization
-gh variable set MY_VAR "value" --org orgname
-
-# Get variable value
-gh variable get MY_VAR
-
-# Delete variable
-gh variable delete MY_VAR
-
-# Delete from environment
-gh variable delete MY_VAR --env production
-```
-
-## Projects (gh project)
-
-```bash
-# List projects
-gh project list
-
-# List for owner
-gh project list --owner owner
-
-# Open projects
-gh project list --open
-
-# View project
-gh project view 123
-
-# View project items
-gh project view 123 --format json
-
-# Create project
-gh project create --title "My Project"
-
-# Create in organization
-gh project create --title "Project" --org orgname
-
-# Create with readme
-gh project create --title "Project" --readme "Description here"
-
-# Edit project
-gh project edit 123 --title "New Title"
-
-# Delete project
-gh project delete 123
-
-# Close project
-gh project close 123
-
-# Copy project
-gh project copy 123 --owner target-owner --title "Copy"
-
-# Mark template
-gh project mark-template 123
-
-# List fields
-gh project field-list 123
-
-# Create field
-gh project field-create 123 --title "Status" --datatype single_select
-
-# Delete field
-gh project field-delete 123 --id 456
-
-# List items
-gh project item-list 123
-
-# Create item
-gh project item-create 123 --title "New item"
-
-# Add item to project
-gh project item-add 123 --owner-owner --repo repo --issue 456
-
-# Edit item
-gh project item-edit 123 --id 456 --title "Updated title"
-
-# Delete item
-gh project item-delete 123 --id 456
-
-# Archive item
-gh project item-archive 123 --id 456
-
-# Link items
-gh project link 123 --id 456 --link-id 789
-
-# Unlink items
-gh project unlink 123 --id 456 --link-id 789
-
-# View project in browser
-gh project view 123 --web
-```
-
-## Releases (gh release)
-
-```bash
-# List releases
-gh release list
-
-# View latest release
-gh release view
-
-# View specific release
-gh release view v1.0.0
-
-# View in browser
-gh release view v1.0.0 --web
-
-# Create release
-gh release create v1.0.0 \
- --notes "Release notes here"
-
-# Create release with notes from file
-gh release create v1.0.0 --notes-file notes.md
-
-# Create release with target
-gh release create v1.0.0 --target main
-
-# Create release as draft
-gh release create v1.0.0 --draft
-
-# Create pre-release
-gh release create v1.0.0 --prerelease
-
-# Create release with title
-gh release create v1.0.0 --title "Version 1.0.0"
-
-# Upload asset to release
-gh release upload v1.0.0 ./file.tar.gz
-
-# Upload multiple assets
-gh release upload v1.0.0 ./file1.tar.gz ./file2.tar.gz
-
-# Upload with label (casing sensitive)
-gh release upload v1.0.0 ./file.tar.gz --casing
-
-# Delete release
-gh release delete v1.0.0
-
-# Delete with cleanup tag
-gh release delete v1.0.0 --yes
-
-# Delete specific asset
-gh release delete-asset v1.0.0 file.tar.gz
-
-# Download release assets
-gh release download v1.0.0
-
-# Download specific asset
-gh release download v1.0.0 --pattern "*.tar.gz"
-
-# Download to directory
-gh release download v1.0.0 --dir ./downloads
-
-# Download archive (zip/tar)
-gh release download v1.0.0 --archive zip
-
-# Edit release
-gh release edit v1.0.0 --notes "Updated notes"
-
-# Verify release signature
-gh release verify v1.0.0
-
-# Verify specific asset
-gh release verify-asset v1.0.0 file.tar.gz
-```
-
-## Gists (gh gist)
-
-```bash
-# List gists
-gh gist list
-
-# List all gists (including private)
-gh gist list --public
-
-# Limit results
-gh gist list --limit 20
-
-# View gist
-gh gist view abc123
-
-# View gist files
-gh gist view abc123 --files
-
-# Create gist
-gh gist create script.py
-
-# Create gist with description
-gh gist create script.py --desc "My script"
-
-# Create public gist
-gh gist create script.py --public
-
-# Create multi-file gist
-gh gist create file1.py file2.py
-
-# Create from stdin
-echo "print('hello')" | gh gist create
-
-# Edit gist
-gh gist edit abc123
-
-# Delete gist
-gh gist delete abc123
-
-# Rename gist file
-gh gist rename abc123 --filename old.py new.py
-
-# Clone gist
-gh gist clone abc123
-
-# Clone to directory
-gh gist clone abc123 my-directory
-```
-
-## Codespaces (gh codespace)
-
-```bash
-# List codespaces
-gh codespace list
-
-# Create codespace
-gh codespace create
-
-# Create with specific repository
-gh codespace create --repo owner/repo
-
-# Create with branch
-gh codespace create --branch develop
-
-# Create with specific machine
-gh codespace create --machine premiumLinux
-
-# View codespace details
-gh codespace view
-
-# SSH into codespace
-gh codespace ssh
-
-# SSH with specific command
-gh codespace ssh --command "cd /workspaces && ls"
-
-# Open codespace in browser
-gh codespace code
-
-# Open in VS Code
-gh codespace code --codec
-
-# Open with specific path
-gh codespace code --path /workspaces/repo
-
-# Stop codespace
-gh codespace stop
-
-# Delete codespace
-gh codespace delete
-
-# View logs
-gh codespace logs
-
---tail 100
-
-# View ports
-gh codespace ports
-
-# Forward port
-gh codespace cp 8080:8080
-
-# Rebuild codespace
-gh codespace rebuild
-
-# Edit codespace
-gh codespace edit --machine standardLinux
-
-# Jupyter support
-gh codespace jupyter
-
-# Copy files to/from codespace
-gh codespace cp file.txt :/workspaces/file.txt
-gh codespace cp :/workspaces/file.txt ./file.txt
-```
-
-## Organizations (gh org)
-
-```bash
-# List organizations
-gh org list
-
-# List for user
-gh org list --user username
-
-# JSON output
-gh org list --json login,name,description
-
-# View organization
-gh org view orgname
-
-# View organization members
-gh org view orgname --json members --jq '.members[] | .login'
-```
-
-## Search (gh search)
-
-```bash
-# Search code
-gh search code "TODO"
-
-# Search in specific repository
-gh search code "TODO" --repo owner/repo
-
-# Search commits
-gh search commits "fix bug"
-
-# Search issues
-gh search issues "label:bug state:open"
-
-# Search PRs
-gh search prs "is:open is:pr review:required"
-
-# Search repositories
-gh search repos "stars:>1000 language:python"
-
-# Limit results
-gh search repos "topic:api" --limit 50
-
-# JSON output
-gh search repos "stars:>100" --json name,description,stargazers
-
-# Order results
-gh search repos "language:rust" --order desc --sort stars
-
-# Search with extensions
-gh search code "import" --extension py
-
-# Web search (open in browser)
-gh search prs "is:open" --web
-```
-
-## Labels (gh label)
-
-```bash
-# List labels
-gh label list
-
-# Create label
-gh label create bug --color "d73a4a" --description "Something isn't working"
-
-# Create with hex color
-gh label create enhancement --color "#a2eeef"
-
-# Edit label
-gh label edit bug --name "bug-report" --color "ff0000"
-
-# Delete label
-gh label delete bug
-
-# Clone labels from repository
-gh label clone owner/repo
-
-# Clone to specific repository
-gh label clone owner/repo --repo target/repo
-```
-
-## SSH Keys (gh ssh-key)
-
-```bash
-# List SSH keys
-gh ssh-key list
-
-# Add SSH key
-gh ssh-key add ~/.ssh/id_rsa.pub --title "My laptop"
-
-# Add key with type
-gh ssh-key add ~/.ssh/id_ed25519.pub --type "authentication"
-
-# Delete SSH key
-gh ssh-key delete 12345
-
-# Delete by title
-gh ssh-key delete --title "My laptop"
-```
-
-## GPG Keys (gh gpg-key)
-
-```bash
-# List GPG keys
-gh gpg-key list
-
-# Add GPG key
-gh gpg-key add ~/.ssh/id_rsa.pub
-
-# Delete GPG key
-gh gpg-key delete 12345
-
-# Delete by key ID
-gh gpg-key delete ABCD1234
-```
-
-## Status (gh status)
-
-```bash
-# Show status overview
-gh status
-
-# Status for specific repositories
-gh status --repo owner/repo
-
-# JSON output
-gh status --json
-```
-
-## Configuration (gh config)
-
-```bash
-# List all config
-gh config list
-
-# Get specific value
-gh config get editor
-
-# Set value
-gh config set editor vim
-
-# Set git protocol
-gh config set git_protocol ssh
-
-# Clear cache
-gh config clear-cache
-
-# Set prompt behavior
-gh config set prompt disabled
-gh config set prompt enabled
-```
-
-## Extensions (gh extension)
-
-```bash
-# List installed extensions
-gh extension list
-
-# Search extensions
-gh extension search github
-
-# Install extension
-gh extension install owner/extension-repo
-
-# Install from branch
-gh extension install owner/extension-repo --branch develop
-
-# Upgrade extension
-gh extension upgrade extension-name
-
-# Remove extension
-gh extension remove extension-name
-
-# Create new extension
-gh extension create my-extension
-
-# Browse extensions
-gh extension browse
-
-# Execute extension command
-gh extension exec my-extension --arg value
-```
-
-## Aliases (gh alias)
-
-```bash
-# List aliases
-gh alias list
-
-# Set alias
-gh alias set prview 'pr view --web'
-
-# Set shell alias
-gh alias set co 'pr checkout' --shell
-
-# Delete alias
-gh alias delete prview
-
-# Import aliases
-gh alias import ./aliases.sh
-```
-
-## API Requests (gh api)
-
-```bash
-# Make API request
-gh api /user
-
-# Request with method
-gh api --method POST /repos/owner/repo/issues \
- --field title="Issue title" \
- --field body="Issue body"
-
-# Request with headers
-gh api /user \
- --header "Accept: application/vnd.github.v3+json"
-
-# Request with pagination
-gh api /user/repos --paginate
-
-# Raw output (no formatting)
-gh api /user --raw
-
-# Include headers in output
-gh api /user --include
-
-# Silent mode (no progress output)
-gh api /user --silent
-
-# Input from file
-gh api --input request.json
-
-# jq query on response
-gh api /user --jq '.login'
-
-# Field from response
-gh api /repos/owner/repo --jq '.stargazers_count'
-
-# GitHub Enterprise
-gh api /user --hostname enterprise.internal
-
-# GraphQL query
-gh api graphql \
- -f query='
- {
- viewer {
- login
- repositories(first: 5) {
- nodes {
- name
- }
- }
- }
- }'
-```
-
-## Rulesets (gh ruleset)
-
-```bash
-# List rulesets
-gh ruleset list
-
-# View ruleset
-gh ruleset view 123
-
-# Check ruleset
-gh ruleset check --branch feature
-
-# Check specific repository
-gh ruleset check --repo owner/repo --branch main
-```
-
-## Attestations (gh attestation)
-
-```bash
-# Download attestation
-gh attestation download owner/repo \
- --artifact-id 123456
-
-# Verify attestation
-gh attestation verify owner/repo
-
-# Get trusted root
-gh attestation trusted-root
-```
-
-## Completion (gh completion)
-
-```bash
-# Generate shell completion
-gh completion -s bash > ~/.gh-complete.bash
-gh completion -s zsh > ~/.gh-complete.zsh
-gh completion -s fish > ~/.gh-complete.fish
-gh completion -s powershell > ~/.gh-complete.ps1
-
-# Shell-specific instructions
-gh completion --shell=bash
-gh completion --shell=zsh
-```
-
-## Preview (gh preview)
-
-```bash
-# List preview features
-gh preview
-
-# Run preview script
-gh preview prompter
-```
-
-## Agent Tasks (gh agent-task)
+## Quick start
```bash
-# List agent tasks
-gh agent-task list
+# Install (macOS / Windows / Debian-based Linux)
+brew install gh # macOS
+winget install --id GitHub.cli # Windows
+sudo apt install gh # Debian/Ubuntu (after adding the GH apt repo)
-# View agent task
-gh agent-task view 123
+# Authenticate
+gh auth login # interactive
+gh auth status # verify
+gh auth setup-git # use gh as git credential helper
-# Create agent task
-gh agent-task create --description "My task"
+# Everyday commands — full flags and variants live in reference/
+gh repo clone owner/repo # → reference/repo.md
+gh issue create --title "..." --body "..." # → reference/issue.md
+gh pr create --fill # → reference/pr.md
+gh pr checks --watch # → reference/pr.md
+gh run watch --exit-status # → reference/actions.md
+gh api /user --jq '.login' # → reference/api.md
```
-## Global Flags
-
-| Flag | Description |
-| -------------------------- | -------------------------------------- |
-| `--help` / `-h` | Show help for command |
-| `--version` | Show gh version |
-| `--repo [HOST/]OWNER/REPO` | Select another repository |
-| `--hostname HOST` | GitHub hostname |
-| `--jq EXPRESSION` | Filter JSON output |
-| `--json FIELDS` | Output JSON with specified fields |
-| `--template STRING` | Format JSON using Go template |
-| `--web` | Open in browser |
-| `--paginate` | Make additional API calls |
-| `--verbose` | Show verbose output |
-| `--debug` | Show debug output |
-| `--timeout SECONDS` | Maximum API request duration |
-| `--cache CACHE` | Cache control (default, force, bypass) |
-
-## Output Formatting
-
-### JSON Output
-
-```bash
-# Basic JSON
-gh repo view --json name,description
-
-# Nested fields
-gh repo view --json owner,name --jq '.owner.login + "/" + .name'
-
-# Array operations
-gh pr list --json number,title --jq '.[] | select(.number > 100)'
-
-# Complex queries
-gh issue list --json number,title,labels \
- --jq '.[] | {number, title: .title, tags: [.labels[].name]}'
-```
-
-### Template Output
-
-```bash
-# Custom template
-gh repo view \
- --template '{{.name}}: {{.description}}'
-
-# Multiline template
-gh pr view 123 \
- --template 'Title: {{.title}}
-Author: {{.author.login}}
-State: {{.state}}
-'
-```
-
-## Common Workflows
-
-### Create PR from Issue
-
-```bash
-# Create branch from issue
-gh issue develop 123 --branch feature/issue-123
-
-# Make changes, commit, push
-git add .
-git commit -m "Fix issue #123"
-git push
-
-# Create PR linking to issue
-gh pr create --title "Fix #123" --body "Closes #123"
-```
-
-### Bulk Operations
-
-```bash
-# Close multiple issues
-gh issue list --search "label:stale" \
- --json number \
- --jq '.[].number' | \
- xargs -I {} gh issue close {} --comment "Closing as stale"
-
-# Add label to multiple PRs
-gh pr list --search "review:required" \
- --json number \
- --jq '.[].number' | \
- xargs -I {} gh pr edit {} --add-label needs-review
-```
-
-### Repository Setup Workflow
-
-```bash
-# Create repository with initial setup
-gh repo create my-project --public \
- --description "My awesome project" \
- --clone \
- --gitignore python \
- --license mit
-
-cd my-project
-
-# Set up branches
-git checkout -b develop
-git push -u origin develop
-
-# Create labels
-gh label create bug --color "d73a4a" --description "Bug report"
-gh label create enhancement --color "a2eeef" --description "Feature request"
-gh label create documentation --color "0075ca" --description "Documentation"
-```
-
-### CI/CD Workflow
-
-```bash
-# Run workflow and wait
-RUN_ID=$(gh workflow run ci.yml --ref main --jq '.databaseId')
-
-# Watch the run
-gh run watch "$RUN_ID"
-
-# Download artifacts on completion
-gh run download "$RUN_ID" --dir ./artifacts
-```
-
-### Fork Sync Workflow
-
-```bash
-# Fork repository
-gh repo fork original/repo --clone
-
-cd repo
-
-# Add upstream remote
-git remote add upstream https://github.com/original/repo.git
-
-# Sync fork
-gh repo sync
-
-# Or manual sync
-git fetch upstream
-git checkout main
-git merge upstream/main
-git push origin main
-```
-
-## Environment Setup
-
-### Shell Integration
-
-```bash
-# Add to ~/.bashrc or ~/.zshrc
-eval "$(gh completion -s bash)" # or zsh/fish
-
-# Create useful aliases
-alias gs='gh status'
-alias gpr='gh pr view --web'
-alias gir='gh issue view --web'
-alias gco='gh pr checkout'
-```
-
-### Git Configuration
+For scripts / CI, two env vars cover most cases:
```bash
-# Use gh as credential helper
-gh auth setup-git
-
-# Set gh as default for repo operations
-git config --global credential.helper 'gh !gh auth setup-git'
-
-# Or manually
-git config --global credential.helper github
+export GH_TOKEN=$(gh auth token) # avoid interactive auth
+export GH_PROMPT_DISABLED=true # prevent any hidden prompts
```
-## Best Practices
+## Reference index
-1. **Authentication**: Use environment variables for automation
+| File | Covers |
+|------|--------|
+| [reference/auth.md](reference/auth.md) | `gh auth` — install, login, tokens, multi-account, `setup-git`, env vars (`GH_TOKEN`, `GH_HOST`, …) |
+| [reference/repo.md](reference/repo.md) | `gh repo` — create, clone, list, view, edit, fork, sync, autolinks, deploy keys |
+| [reference/issue.md](reference/issue.md) | `gh issue` — create, list, view, edit, close, comment, pin, lock, transfer, `issue develop` |
+| [reference/pr.md](reference/pr.md) | `gh pr` — create, list, view, checkout, diff, merge, review, checks, edit, ready, update-branch, revert |
+| [reference/actions.md](reference/actions.md) | `gh run`, `gh workflow`, `gh cache`, `gh secret`, `gh variable` |
+| [reference/api.md](reference/api.md) | `gh api` — REST, GraphQL, pagination, `-f`/`-F` fields, jq patterns |
+| [reference/projects.md](reference/projects.md) | `gh project` — Projects v2 boards, fields, items |
+| [reference/release.md](reference/release.md) | `gh release` — create, edit, upload/download assets, generate notes |
+| [reference/formatting.md](reference/formatting.md) | `--json` / `--jq` / `--template` — discover fields, common jq patterns, Go templates |
+| [reference/workflows.md](reference/workflows.md) | End-to-end recipes — ship a PR, bulk label, sync fork, wait-for-workflow, auto-merge |
+| [reference/misc.md](reference/misc.md) | `browse`, `gist`, `codespace`, `org`, `search`, `label`, `ssh-key`, `gpg-key`, `status`, `config`, `extension`, `alias`, `ruleset`, `attestation`, `completion`, `preview`, `agent-task` + global flags |
- ```bash
- export GH_TOKEN=$(gh auth token)
- ```
+## Quick routing by task
-2. **Default Repository**: Set default to avoid repetition
+- **"How do I log in / switch accounts / set a token for CI?"** → `reference/auth.md`
+- **"Create / clone / fork / sync a repo"** → `reference/repo.md`
+- **"Open / close / comment on an issue"** → `reference/issue.md`
+- **"Create / review / merge / check status of a PR"** → `reference/pr.md`
+- **"Trigger / watch / rerun a workflow; manage secrets or caches"** → `reference/actions.md`
+- **"Hit a GitHub REST or GraphQL endpoint"** → `reference/api.md`
+- **"Manage a Projects v2 board / items / fields"** → `reference/projects.md`
+- **"Cut a release / upload or download assets"** → `reference/release.md`
+- **"Extract structured output / filter with jq / format with Go template"** → `reference/formatting.md`
+- **"Chain multiple `gh` commands into a workflow"** → `reference/workflows.md`
+- **"Anything not listed above"** → `reference/misc.md` (+ `gh --help`)
- ```bash
- gh repo set-default owner/repo
- ```
+## Prereqs
-3. **JSON Parsing**: Use jq for complex data extraction
+- `gh` 2.85.0+ (`brew install gh` / `winget install GitHub.cli` / apt). See `reference/auth.md` for install + first login.
+- For scripts, export `GH_TOKEN=$(gh auth token)` and `GH_PROMPT_DISABLED=true` to avoid prompts.
- ```bash
- gh pr list --json number,title --jq '.[] | select(.title | contains("fix"))'
- ```
+## Global flags present on most commands
-4. **Pagination**: Use --paginate for large result sets
-
- ```bash
- gh issue list --state all --paginate
- ```
-
-5. **Caching**: Use cache control for frequently accessed data
- ```bash
- gh api /user --cache force
- ```
-
-## Getting Help
-
-```bash
-# General help
-gh --help
-
-# Command help
-gh pr --help
-gh issue create --help
-
-# Help topics
-gh help formatting
-gh help environment
-gh help exit-codes
-gh help accessibility
-```
+`-R, --repo OWNER/REPO` · `--hostname HOST` · `--json FIELDS` · `--jq EXPR` · `--template STR` · `--paginate` · `--web` · `--verbose` · `--cache DUR`
## References
-- Official Manual: https://cli.github.com/manual/
-- GitHub Docs: https://docs.github.com/en/github-cli
+- Official manual: https://cli.github.com/manual/
- REST API: https://docs.github.com/en/rest
- GraphQL API: https://docs.github.com/en/graphql
diff --git a/skills/gh-cli/reference/actions.md b/skills/gh-cli/reference/actions.md
new file mode 100644
index 000000000..43d13d6b1
--- /dev/null
+++ b/skills/gh-cli/reference/actions.md
@@ -0,0 +1,113 @@
+# gh Actions — workflows, runs, caches, secrets, variables
+
+## Workflow runs (gh run)
+
+```bash
+gh run list # recent runs
+gh run list --workflow ci.yml
+gh run list --branch main
+gh run list --user @me
+gh run list --status failure # in_progress|success|failure|cancelled|...
+gh run list --event push
+gh run list --limit 20
+gh run list --json databaseId,name,status,conclusion,headBranch,displayTitle
+
+gh run view 123456789 # details
+gh run view 123456789 --log # full logs
+gh run view 123456789 --log-failed # only failed step logs
+gh run view 123456789 --job 987654321 # specific job
+gh run view 123456789 --web
+
+gh run watch 123456789 # follow until done
+gh run watch 123456789 --interval 5 --exit-status # non-zero exit on failure
+
+gh run rerun 123456789 # rerun all
+gh run rerun 123456789 --failed # only failed jobs
+gh run rerun 123456789 --job 987654321
+
+gh run cancel 123456789
+gh run delete 123456789
+
+gh run download 123456789 # all artifacts to ./
+gh run download 123456789 --name build # specific artifact
+gh run download 123456789 --dir ./artifacts
+gh run download 123456789 --pattern "*.log"
+```
+
+## Workflows (gh workflow)
+
+```bash
+gh workflow list # all workflows
+gh workflow list --all # include disabled
+gh workflow view ci.yml
+gh workflow view ci.yml --yaml # print definition
+gh workflow view ci.yml --web
+
+gh workflow enable ci.yml
+gh workflow disable ci.yml
+
+gh workflow run ci.yml # manual dispatch (workflow_dispatch)
+gh workflow run ci.yml --ref develop
+gh workflow run ci.yml \
+ --field version=1.0.0 \
+ --field environment=production
+gh workflow run ci.yml --json < inputs.json # stdin inputs
+```
+
+## Caches (gh cache)
+
+```bash
+gh cache list
+gh cache list --branch main --limit 50
+gh cache list --sort last_accessed_at --order desc
+gh cache list --json id,key,sizeInBytes,ref
+
+gh cache delete 123456789
+gh cache delete --all
+gh cache delete --key "npm-cache-key"
+```
+
+## Secrets (gh secret)
+
+```bash
+gh secret list
+gh secret list --env production
+gh secret list --app actions # actions|codespaces|dependabot
+
+gh secret set MY_SECRET # prompt for value
+echo "$MY_SECRET" | gh secret set MY_SECRET # from stdin
+gh secret set MY_SECRET --body "value"
+gh secret set MY_SECRET --env production
+gh secret set MY_SECRET --org my-org --visibility all # all|private|selected
+gh secret set MY_SECRET --org my-org --visibility selected --repos repo1,repo2
+gh secret set -f secrets.env # bulk from dotenv
+
+gh secret delete MY_SECRET
+gh secret delete MY_SECRET --env production
+```
+
+## Variables (gh variable)
+
+```bash
+gh variable list
+gh variable list --env production
+
+gh variable set MY_VAR --body "value"
+gh variable set MY_VAR --env production --body "value"
+gh variable set MY_VAR --org my-org --visibility selected --repos repo1,repo2
+gh variable set -f vars.env # bulk from dotenv
+
+gh variable get MY_VAR
+gh variable delete MY_VAR
+gh variable delete MY_VAR --env production
+```
+
+## Common pattern: run workflow and wait
+
+```bash
+gh workflow run ci.yml --ref main
+sleep 3 # let the run register
+RUN_ID=$(gh run list --workflow ci.yml --limit 1 --json databaseId --jq '.[0].databaseId')
+gh run watch "$RUN_ID" --exit-status
+gh run download "$RUN_ID" --dir ./artifacts
+```
diff --git a/skills/gh-cli/reference/api.md b/skills/gh-cli/reference/api.md
new file mode 100644
index 000000000..329cc8690
--- /dev/null
+++ b/skills/gh-cli/reference/api.md
@@ -0,0 +1,136 @@
+# gh api — REST, GraphQL, and jq patterns
+
+`gh api` handles auth, pagination, and hostname routing automatically — prefer it over raw `curl` for GitHub calls.
+
+## REST basics
+
+```bash
+gh api /user # GET, authenticated user
+gh api repos/owner/repo # leading slash optional
+gh api repos/owner/repo/issues --paginate # follow all pages
+gh api /rate_limit
+
+gh api --method POST /repos/owner/repo/issues \
+ --field title="Issue title" \
+ --field body="Body"
+
+gh api --method PATCH /repos/owner/repo/issues/123 \
+ --field state=closed \
+ --field state_reason=completed
+
+gh api --method DELETE /repos/owner/repo/labels/stale
+```
+
+## Field types
+
+```bash
+--field key=value # string (also coerces true/false/null/numbers)
+-f key=value # short form, same as --field
+--raw-field key=value # force string (never coerce)
+-F key=value # short form of --raw-field
+
+# Nested / array fields
+gh api --method POST /repos/owner/repo/issues \
+ -f title="Issue" \
+ -f 'labels[]=bug' -f 'labels[]=high-priority' \
+ -f 'assignees[]=monalisa'
+```
+
+## Headers / body / input
+
+```bash
+gh api /user --header "Accept: application/vnd.github+json"
+gh api /user --header "X-GitHub-Api-Version: 2022-11-28"
+gh api --method POST /repos/owner/repo/issues --input issue.json # full body from file
+gh api --method POST /repos/owner/repo/issues --input - # stdin
+```
+
+## Pagination
+
+```bash
+gh api /repos/owner/repo/issues --paginate # concatenate arrays
+gh api /repos/owner/repo/issues --paginate --slurp # wrap pages in an array
+gh api /repos/owner/repo/issues -F per_page=100 --paginate
+```
+
+## Output control
+
+```bash
+gh api /user --jq '.login' # filter with jq
+gh api /user --jq '{login, id, name}'
+gh api /repos/owner/repo --jq '.stargazers_count'
+gh api /user --template '{{.login}} ({{.id}})' # Go template
+
+gh api /user --include # show response headers
+gh api /user --silent # suppress body
+gh api /user --verbose # full request/response
+gh api /user --cache 1h # client-side cache
+```
+
+## Hostname / Enterprise
+
+```bash
+gh api /user --hostname enterprise.internal
+GH_HOST=enterprise.internal gh api /user
+```
+
+## GraphQL
+
+```bash
+gh api graphql -f query='
+ { viewer { login repositories(first: 5) { nodes { name } } } }
+'
+
+# With variables
+gh api graphql \
+ -F owner=monalisa -F repo=hello-world \
+ -f query='
+ query ($owner: String!, $repo: String!) {
+ repository(owner: $owner, name: $repo) {
+ issues(first: 5, states: OPEN) { nodes { number title } }
+ }
+ }'
+
+# GraphQL pagination
+gh api graphql --paginate \
+ -F owner=monalisa -F repo=hello-world \
+ -f query='
+ query ($owner: String!, $repo: String!, $endCursor: String) {
+ repository(owner: $owner, name: $repo) {
+ issues(first: 100, after: $endCursor) {
+ pageInfo { hasNextPage endCursor }
+ nodes { number title }
+ }
+ }
+ }'
+```
+
+## Common jq patterns
+
+```bash
+# Array → TSV
+gh pr list --json number,title,author \
+ --jq '.[] | [.number, .title, .author.login] | @tsv'
+
+# Filter
+gh issue list --json number,title,labels \
+ --jq '.[] | select(.labels | map(.name) | index("bug"))'
+
+# Count by field
+gh pr list --state all --limit 500 --json state \
+ --jq 'group_by(.state) | map({state: .[0].state, count: length})'
+
+# Extract nested IDs
+gh run list --json databaseId,conclusion \
+ --jq '.[] | select(.conclusion=="failure") | .databaseId'
+
+# Combine fields
+gh repo view --json owner,name --jq '"\(.owner.login)/\(.name)"'
+```
+
+## Headers from response (rate limit, etc.)
+
+```bash
+gh api /rate_limit --jq '.rate'
+gh api /user --include 2>&1 | grep -i x-ratelimit # inspect headers
+```
diff --git a/skills/gh-cli/reference/auth.md b/skills/gh-cli/reference/auth.md
new file mode 100644
index 000000000..a82b7fa43
--- /dev/null
+++ b/skills/gh-cli/reference/auth.md
@@ -0,0 +1,97 @@
+# gh auth — Authentication
+
+Covers login, token management, account switching, git credential setup, and environment variables for automation.
+
+## Install
+
+```bash
+# macOS
+brew install gh
+
+# Linux (Debian/Ubuntu)
+curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
+sudo apt update && sudo apt install gh
+
+# Windows
+winget install --id GitHub.cli
+
+gh --version
+```
+
+## Login
+
+```bash
+gh auth login # interactive
+gh auth login --web # web-based OAuth
+gh auth login --web --clipboard # copy OAuth code to clipboard
+gh auth login --git-protocol ssh # force SSH protocol
+gh auth login --hostname enterprise.internal # GitHub Enterprise
+gh auth login --with-token < token.txt # non-interactive with token
+gh auth login --insecure-storage # plaintext token storage
+```
+
+## Status
+
+```bash
+gh auth status # all accounts
+gh auth status --active # active account only
+gh auth status --hostname github.com # specific host
+gh auth status --show-token # reveal token
+gh auth status --json hosts --jq '.hosts | add'
+```
+
+## Switch accounts
+
+```bash
+gh auth switch # interactive
+gh auth switch --hostname github.com --user monalisa # explicit
+```
+
+## Token
+
+```bash
+gh auth token # print active token
+gh auth token --hostname github.com --user monalisa # specific account
+```
+
+## Refresh / adjust scopes
+
+```bash
+gh auth refresh
+gh auth refresh --scopes write:org,read:public_key # add scopes
+gh auth refresh --remove-scopes delete_repo # remove scopes
+gh auth refresh --reset-scopes # back to defaults
+gh auth refresh --clipboard
+```
+
+## Logout
+
+```bash
+gh auth logout --hostname github.com --user username
+```
+
+## Setup git credential helper
+
+```bash
+gh auth setup-git # current host
+gh auth setup-git --hostname enterprise.internal # specific host
+gh auth setup-git --hostname enterprise.internal --force
+```
+
+## Environment variables (for automation)
+
+| Variable | Purpose |
+|----------|---------|
+| `GH_TOKEN` | Auth token (preferred for CI) |
+| `GH_HOST` | Default hostname |
+| `GH_ENTERPRISE_TOKEN` | Enterprise-specific token |
+| `GH_PROMPT_DISABLED` | Disable interactive prompts |
+| `GH_EDITOR` | Editor for multi-line inputs |
+| `GH_PAGER` | Pager (e.g., `less`, empty to disable) |
+| `GH_REPO` | Override default `owner/repo` |
+| `GH_TIMEOUT` | HTTP request timeout (seconds) |
+
+```bash
+export GH_TOKEN=$(gh auth token) # common pattern in scripts
+```
diff --git a/skills/gh-cli/reference/formatting.md b/skills/gh-cli/reference/formatting.md
new file mode 100644
index 000000000..204b26ef0
--- /dev/null
+++ b/skills/gh-cli/reference/formatting.md
@@ -0,0 +1,90 @@
+# Output formatting — `--json`, `--jq`, `--template`
+
+Most `gh` list/view commands support structured output. Use these instead of scraping text.
+
+## Global flags
+
+| Flag | Purpose |
+|------|---------|
+| `--json FIELDS` | Output JSON with selected fields (comma-separated). Use `--json` with no value to see available fields. |
+| `--jq EXPR` | Apply a jq expression to the JSON response |
+| `--template STR` | Format the JSON with a Go text/template |
+| `--paginate` | Follow pagination (REST & `gh api`) |
+
+## Discover available fields
+
+```bash
+gh pr list --json # lists the field names you can request
+gh issue view 123 --json # same, for a single issue
+gh run list --json
+```
+
+## JSON examples
+
+```bash
+gh repo view --json name,description,defaultBranchRef
+gh pr list --json number,title,author,headRefName --limit 100
+gh issue list --json number,title,labels --limit 200
+```
+
+## jq patterns
+
+```bash
+# Single field extraction
+gh repo view --json name --jq '.name'
+gh auth status --json hosts --jq '.hosts | keys'
+
+# Array → TSV (good for xargs / column)
+gh pr list --json number,title,author \
+ --jq '.[] | [.number, .title, .author.login] | @tsv'
+
+# Filter by label
+gh issue list --json number,title,labels \
+ --jq '.[] | select(.labels | map(.name) | index("bug")) | {number, title}'
+
+# Status check rollup
+gh pr view 123 --json statusCheckRollup \
+ --jq '.statusCheckRollup[] | {name, status, conclusion}'
+
+# Group/aggregate
+gh pr list --state all --limit 500 --json state \
+ --jq 'group_by(.state) | map({state: .[0].state, count: length})'
+
+# Numeric comparison
+gh repo list --json name,stargazerCount \
+ --jq '.[] | select(.stargazerCount > 100) | .name'
+```
+
+## Go templates
+
+Use when the shell doesn't have jq, or you want direct text output without quoting.
+
+```bash
+gh repo view --template '{{.name}}: {{.description}}{{"\n"}}'
+
+gh pr view 123 --template '
+Title: {{.title}}
+Author: {{.author.login}}
+State: {{.state}}
+URL: {{.url}}
+'
+
+# Loop over an array
+gh pr list --template '{{range .}}#{{.number}} {{.title}} ({{.author.login}}){{"\n"}}{{end}}'
+
+# Conditional
+gh pr list --template '{{range .}}{{if .isDraft}}[DRAFT] {{end}}#{{.number}} {{.title}}{{"\n"}}{{end}}'
+```
+
+Template helpers built into `gh`: `autocolor`, `color`, `hyperlink`, `join`, `pluck`, `tablerow`, `tablerender`, `timeago`, `timefmt`, `truncate`.
+
+```bash
+gh pr list --template \
+ '{{range .}}{{tablerow (printf "#%v" .number) .title .author.login}}{{end}}{{tablerender}}'
+```
+
+## When to use which
+
+- `--jq` — filtering, shaping, aggregation; requires JSON output.
+- `--template` — clean human-readable text without jq installed.
+- Raw JSON (no jq/template) — piping into another tool like `python -m json.tool` or another `jq` invocation.
diff --git a/skills/gh-cli/reference/issue.md b/skills/gh-cli/reference/issue.md
new file mode 100644
index 000000000..d7cf76f4e
--- /dev/null
+++ b/skills/gh-cli/reference/issue.md
@@ -0,0 +1,98 @@
+# gh issue — Issues
+
+Create, list, view, edit, close/reopen, comment, pin, lock, transfer, delete issues. Plus `gh issue develop` to branch off an issue.
+
+## Create
+
+```bash
+gh issue create # interactive
+gh issue create --title "Bug: Login" --body "Repro..."
+gh issue create --body-file issue.md
+gh issue create --title "Fix bug" --label bug,high-priority
+gh issue create --title "Fix bug" --assignee user1,user2
+gh issue create --title "..." --milestone "v1.0" --project "Roadmap"
+gh issue create --repo owner/repo --title "..."
+gh issue create --web # open form in browser
+```
+
+## List
+
+```bash
+gh issue list # open
+gh issue list --state all # open + closed
+gh issue list --state closed
+gh issue list --limit 50
+gh issue list --assignee @me # mine
+gh issue list --assignee username
+gh issue list --label bug,enhancement
+gh issue list --milestone "v1.0"
+gh issue list --search "is:open label:bug no:assignee"
+gh issue list --sort created --order desc
+gh issue list --json number,title,state,author
+gh issue list --json number,title,labels \
+ --jq '.[] | [.number, .title, (.labels | map(.name) | join(","))] | @tsv'
+```
+
+## View
+
+```bash
+gh issue view 123
+gh issue view 123 --comments
+gh issue view 123 --web
+gh issue view 123 --json title,body,state,labels,comments
+gh issue view 123 --json title --jq '.title'
+```
+
+## Edit
+
+```bash
+gh issue edit 123 # interactive
+gh issue edit 123 --title "New title"
+gh issue edit 123 --body "New description"
+gh issue edit 123 --body-file desc.md
+gh issue edit 123 --add-label bug --remove-label stale
+gh issue edit 123 --add-assignee user1 --remove-assignee user2
+gh issue edit 123 --milestone "v1.0"
+```
+
+## Close / reopen
+
+```bash
+gh issue close 123
+gh issue close 123 --comment "Fixed in PR #456" --reason completed
+gh issue reopen 123
+```
+
+## Comment
+
+```bash
+gh issue comment 123 --body "Looks good!"
+gh issue comment 123 --body-file reply.md
+gh issue comment 123 --edit-last --body "Updated"
+```
+
+## Status summary
+
+```bash
+gh issue status # mine + assigned + mentioned
+gh issue status --repo owner/repo
+```
+
+## Pin / lock / transfer / delete
+
+```bash
+gh issue pin 123
+gh issue unpin 123
+gh issue lock 123 --reason off-topic # resolved|off-topic|too heated|spam
+gh issue unlock 123
+gh issue transfer 123 owner/new-repo
+gh issue delete 123 --yes
+```
+
+## Develop (branch + draft PR from an issue)
+
+```bash
+gh issue develop 123 # create linked branch
+gh issue develop 123 --branch fix/issue-123
+gh issue develop 123 --base main --checkout
+```
diff --git a/skills/gh-cli/reference/misc.md b/skills/gh-cli/reference/misc.md
new file mode 100644
index 000000000..79865353c
--- /dev/null
+++ b/skills/gh-cli/reference/misc.md
@@ -0,0 +1,219 @@
+# gh — other commands
+
+Less-frequently used subcommands: browse, gist, codespace, org, search, label, ssh-key, gpg-key, status, config, extension, alias, ruleset, attestation, completion, preview, agent-task.
+
+## Browse (gh browse)
+
+```bash
+gh browse # current repo on github.com
+gh browse script/ # path
+gh browse main.go:312 # file at line
+gh browse 123 # issue/PR
+gh browse 77507cd # commit
+gh browse main.go --branch bug-fix
+gh browse --repo owner/repo
+gh browse --releases # also: --actions --projects --settings --wiki
+gh browse --no-browser # just print URL
+```
+
+## Gists (gh gist)
+
+```bash
+gh gist list --limit 20 --public
+gh gist view abc123
+gh gist view abc123 --files
+
+gh gist create script.py # private
+gh gist create script.py --public --desc "My script"
+gh gist create file1.py file2.py # multi-file
+echo "print('hi')" | gh gist create - # from stdin
+
+gh gist edit abc123
+gh gist rename abc123 old.py new.py
+gh gist clone abc123 my-dir
+gh gist delete abc123
+```
+
+## Codespaces (gh codespace)
+
+```bash
+gh codespace list
+gh codespace create --repo owner/repo --branch develop --machine standardLinux
+gh codespace view
+gh codespace ssh
+gh codespace ssh --command "ls /workspaces"
+gh codespace code # open desktop VS Code
+gh codespace code --web # open in browser
+gh codespace cp file.txt remote:/workspaces/file.txt
+gh codespace cp remote:/workspaces/file.txt ./file.txt
+gh codespace ports # list forwarded ports
+gh codespace ports forward 8080:8080
+gh codespace logs
+gh codespace stop
+gh codespace rebuild
+gh codespace edit --machine premiumLinux
+gh codespace delete
+gh codespace jupyter # Jupyter over SSH
+```
+
+## Organizations (gh org)
+
+```bash
+gh org list # your memberships
+gh org list --json login,name,description
+```
+
+(For org-level operations like members or teams, use `gh api` — e.g. `gh api orgs/my-org/members --paginate`.)
+
+## Search (gh search)
+
+```bash
+gh search code "TODO" --repo owner/repo
+gh search code "import" --extension py --language python
+gh search commits "fix bug" --author monalisa
+gh search issues "label:bug state:open"
+gh search prs "is:open review:required author:@me"
+gh search repos "stars:>1000 language:python"
+gh search repos "topic:cli" --limit 50 --sort stars --order desc
+gh search repos "stars:>100" --json name,description,stargazersCount
+gh search prs "is:open" --web
+```
+
+## Labels (gh label)
+
+```bash
+gh label list
+gh label list --limit 100 --json name,color,description
+gh label create bug --color d73a4a --description "Something isn't working"
+gh label create enhancement --color "#a2eeef"
+gh label edit bug --name bug-report --color ff0000
+gh label delete bug --yes
+gh label clone owner/repo # copy labels into current repo
+gh label clone owner/repo --force # overwrite existing
+```
+
+## SSH keys (gh ssh-key)
+
+```bash
+gh ssh-key list
+gh ssh-key add ~/.ssh/id_ed25519.pub --title "My laptop"
+gh ssh-key add ~/.ssh/id_ed25519.pub --type signing # authentication|signing
+gh ssh-key delete 12345
+```
+
+## GPG keys (gh gpg-key)
+
+```bash
+gh gpg-key list
+gh gpg-key add ~/key.asc
+gh gpg-key delete 12345
+```
+
+## Status (gh status)
+
+```bash
+gh status # assigned/mentioned across your repos
+gh status --org my-org
+gh status --exclude owner/repo1,owner/repo2
+```
+
+## Configuration (gh config)
+
+```bash
+gh config list
+gh config get editor
+gh config set editor vim
+gh config set git_protocol ssh # or https
+gh config set prompt disabled # or enabled
+gh config set pager "less -R"
+gh config clear-cache
+```
+
+## Extensions (gh extension)
+
+```bash
+gh extension list
+gh extension search
+gh extension browse # TUI catalog
+gh extension install owner/gh-my-ext
+gh extension install . --force # from local path
+gh extension upgrade
+gh extension upgrade --all
+gh extension remove
+gh extension create # scaffold a new extension
+gh extension exec --
+```
+
+## Aliases (gh alias)
+
+```bash
+gh alias list
+gh alias set prview 'pr view --web'
+gh alias set co 'pr checkout'
+gh alias set bugs 'issue list --label=bug'
+gh alias set --shell igrep 'gh issue list --label="$1" | grep "$2"'
+gh alias import aliases.yml # bulk
+gh alias import - # from stdin
+gh alias delete prview
+```
+
+## Rulesets (gh ruleset)
+
+```bash
+gh ruleset list # repo rulesets
+gh ruleset list --parents # include org-level
+gh ruleset view 123
+gh ruleset check --branch feature # which rules apply to a branch
+gh ruleset check --repo owner/repo --branch main
+```
+
+## Attestations (gh attestation)
+
+```bash
+gh attestation verify ./artifact.tar.gz --owner my-org # verify by owner
+gh attestation verify ./artifact.tar.gz --repo owner/repo
+gh attestation download owner/repo --artifact-digest sha256:...
+gh attestation trusted-root # print Sigstore trusted root
+```
+
+## Completion (gh completion)
+
+```bash
+gh completion -s bash > ~/.gh-complete.bash
+gh completion -s zsh > ~/.gh-complete.zsh
+gh completion -s fish > ~/.config/fish/completions/gh.fish
+gh completion -s powershell > ~/.gh-complete.ps1
+```
+
+Typical `~/.zshrc` hook:
+```bash
+eval "$(gh completion -s zsh)"
+```
+
+## Preview (gh preview)
+
+```bash
+gh preview # list preview features
+gh preview # run a preview
+```
+
+## Agent tasks (gh agent-task)
+
+```bash
+gh agent-task list
+gh agent-task view 123
+gh agent-task create --description "..."
+```
+
+## Global flags cheat sheet
+
+| Flag | Purpose |
+|------|---------|
+| `-R, --repo [HOST/]OWNER/REPO` | Target a specific repo |
+| `--hostname HOST` | Use a different GitHub host (Enterprise) |
+| `--jq EXPR` / `--json FIELDS` / `--template STR` | See `formatting.md` |
+| `--web` | Open in browser (supported by most commands) |
+| `--paginate` | Follow pagination (REST/API) |
+| `--verbose` / `--debug` | Diagnostic output |
+| `--cache DURATION` | Client-side cache (e.g. `1h`, `force`, `bypass`) |
+| `--timeout SECONDS` | HTTP timeout |
diff --git a/skills/gh-cli/reference/pr.md b/skills/gh-cli/reference/pr.md
new file mode 100644
index 000000000..72337a17b
--- /dev/null
+++ b/skills/gh-cli/reference/pr.md
@@ -0,0 +1,153 @@
+# gh pr — Pull Requests
+
+Create, list, view, checkout, diff, merge, close, reopen, edit, review, comment, update branch, lock, revert. Plus `gh pr checks` and `gh pr status`.
+
+## Create
+
+```bash
+gh pr create # interactive
+gh pr create --title "feat: X" --body "..."
+gh pr create --body-file .github/PULL_REQUEST_TEMPLATE.md
+gh pr create --base main --head feature-branch
+gh pr create --draft
+gh pr create --assignee user1,user2 --reviewer user3
+gh pr create --label enhancement,feature
+gh pr create --fill # use commit info for title/body
+gh pr create --fill-first # only first commit
+gh pr create --repo owner/repo
+gh pr create --web # open form in browser
+```
+
+## List
+
+```bash
+gh pr list # open
+gh pr list --state all # all states
+gh pr list --state merged
+gh pr list --state closed # closed but not merged
+gh pr list --head feature-branch --base main
+gh pr list --author @me
+gh pr list --assignee username
+gh pr list --label bug,enhancement
+gh pr list --limit 50
+gh pr list --search "is:open review-requested:@me"
+gh pr list --json number,title,state,author,headRefName
+gh pr list --json number,title,statusCheckRollup \
+ --jq '.[] | [.number, .title, (.statusCheckRollup | map(.conclusion) | unique | join(","))] | @tsv'
+```
+
+## View
+
+```bash
+gh pr view 123 # defaults to current branch's PR
+gh pr view # auto-detect from branch
+gh pr view 123 --comments
+gh pr view 123 --web
+gh pr view 123 --json title,body,state,author,commits,files,reviews
+```
+
+## Checkout
+
+```bash
+gh pr checkout 123
+gh pr checkout 123 --branch custom-name
+gh pr checkout 123 --force # discard local changes
+gh pr checkout 123 --detach # detached HEAD
+```
+
+## Diff
+
+```bash
+gh pr diff 123
+gh pr diff 123 --color always
+gh pr diff 123 --name-only # file list only
+gh pr diff 123 --patch > pr-123.patch
+```
+
+## Merge
+
+```bash
+gh pr merge 123 # interactive
+gh pr merge 123 --merge # merge commit
+gh pr merge 123 --squash
+gh pr merge 123 --rebase
+gh pr merge 123 --delete-branch
+gh pr merge 123 --auto # enable auto-merge
+gh pr merge 123 --subject "..." --body "..."
+gh pr merge 123 --admin # bypass required checks
+```
+
+## Close / reopen
+
+```bash
+gh pr close 123
+gh pr close 123 --comment "Superseded by #456" --delete-branch
+gh pr reopen 123
+```
+
+## Edit
+
+```bash
+gh pr edit 123 --title "New title" --body "New desc"
+gh pr edit 123 --add-label bug --remove-label stale
+gh pr edit 123 --add-assignee user1 --remove-assignee user2
+gh pr edit 123 --add-reviewer user3 --remove-reviewer user4
+gh pr edit 123 --base main # change target branch
+```
+
+## Ready for review
+
+```bash
+gh pr ready 123 # mark draft ready
+gh pr ready 123 --undo # back to draft
+```
+
+## Checks
+
+```bash
+gh pr checks 123 # status table
+gh pr checks 123 --watch # re-render until done
+gh pr checks 123 --watch --interval 5
+gh pr checks 123 --required # only required checks
+gh pr checks 123 --json name,status,conclusion,link
+```
+
+## Comment
+
+```bash
+gh pr comment 123 --body "Looks good!"
+gh pr comment 123 --body-file reply.md
+gh pr comment 123 --edit-last --body "Updated"
+```
+
+## Review
+
+```bash
+gh pr review 123 # editor opens
+gh pr review 123 --approve --body "LGTM"
+gh pr review 123 --request-changes --body "Please fix..."
+gh pr review 123 --comment --body "Some thoughts..."
+```
+
+## Update branch (sync with base)
+
+```bash
+gh pr update-branch 123 # merge base into PR branch
+gh pr update-branch 123 --rebase # rebase instead
+```
+
+## Lock / revert
+
+```bash
+gh pr lock 123 --reason off-topic
+gh pr unlock 123
+gh pr revert 123 # open PR to revert a merged PR
+gh pr revert 123 --branch revert-pr-123
+```
+
+## Status summary
+
+```bash
+gh pr status # mine + assigned + review-requested
+gh pr status --repo owner/repo
+```
diff --git a/skills/gh-cli/reference/projects.md b/skills/gh-cli/reference/projects.md
new file mode 100644
index 000000000..5d2a2cb6a
--- /dev/null
+++ b/skills/gh-cli/reference/projects.md
@@ -0,0 +1,82 @@
+# gh project — GitHub Projects (v2)
+
+Manage Projects v2 boards, fields, and items. Most commands need `--owner` (user or org).
+
+## Project CRUD
+
+```bash
+gh project list # your projects
+gh project list --owner my-org
+gh project list --closed
+gh project list --format json
+
+gh project view 123 # project by number
+gh project view 123 --owner my-org
+gh project view 123 --web
+gh project view 123 --format json
+
+gh project create --title "My Project" --owner @me
+gh project create --title "Roadmap" --owner my-org
+gh project edit 123 --owner my-org --title "New Title" --description "..."
+gh project edit 123 --owner my-org --readme "Markdown readme"
+gh project edit 123 --owner my-org --visibility PUBLIC # PUBLIC|PRIVATE
+
+gh project close 123 --owner my-org
+gh project close 123 --owner my-org --undo
+gh project copy 123 --source-owner my-org --target-owner my-org --title "Copy"
+gh project delete 123 --owner my-org
+gh project mark-template 123 --owner my-org
+gh project link 123 --owner my-org --repo my-org/my-repo # link to repo
+gh project unlink 123 --owner my-org --repo my-org/my-repo
+```
+
+## Fields
+
+```bash
+gh project field-list 123 --owner my-org
+gh project field-list 123 --owner my-org --format json
+
+gh project field-create 123 --owner my-org \
+ --name "Priority" --data-type SINGLE_SELECT \
+ --single-select-options "High,Medium,Low"
+
+gh project field-create 123 --owner my-org \
+ --name "Effort" --data-type NUMBER
+
+# Data types: TEXT | SINGLE_SELECT | DATE | NUMBER | ITERATION
+
+gh project field-delete --id PVTF_xxx
+```
+
+## Items
+
+```bash
+gh project item-list 123 --owner my-org
+gh project item-list 123 --owner my-org --format json --limit 200
+
+# Add existing issue/PR to project
+gh project item-add 123 --owner my-org \
+ --url https://github.com/my-org/repo/issues/42
+
+# Create a draft (non-issue) item
+gh project item-create 123 --owner my-org \
+ --title "Research: X" --body "Notes..."
+
+gh project item-edit --id PVTI_xxx --field-id PVTF_xxx --text "In review"
+gh project item-edit --id PVTI_xxx --field-id PVTF_xxx --single-select-option-id OPT_xxx
+gh project item-edit --id PVTI_xxx --field-id PVTF_xxx --number 5
+gh project item-edit --id PVTI_xxx --field-id PVTF_xxx --date 2026-06-01
+gh project item-edit --id PVTI_xxx --field-id PVTF_xxx --iteration-id ITER_xxx
+gh project item-edit --id PVTI_xxx --clear # clear field value
+
+gh project item-archive --id PVTI_xxx
+gh project item-archive --id PVTI_xxx --undo
+gh project item-delete 123 --owner my-org --id PVTI_xxx
+```
+
+## Tip — look up field / option IDs
+
+```bash
+gh project field-list 123 --owner my-org --format json \
+ --jq '.fields[] | {id, name, dataType, options: .options}'
+```
diff --git a/skills/gh-cli/reference/release.md b/skills/gh-cli/reference/release.md
new file mode 100644
index 000000000..cb8e88005
--- /dev/null
+++ b/skills/gh-cli/reference/release.md
@@ -0,0 +1,67 @@
+# gh release — Releases & assets
+
+## List / view
+
+```bash
+gh release list # recent releases
+gh release list --limit 50
+gh release list --exclude-drafts --exclude-pre-releases
+gh release list --json tagName,name,publishedAt,isDraft,isPrerelease
+
+gh release view # latest non-draft
+gh release view v1.0.0
+gh release view v1.0.0 --web
+gh release view v1.0.0 --json tagName,name,body,assets
+```
+
+## Create
+
+```bash
+gh release create v1.0.0 # interactive
+gh release create v1.0.0 --notes "Release notes"
+gh release create v1.0.0 --notes-file CHANGELOG.md
+gh release create v1.0.0 --generate-notes # auto from PRs
+gh release create v1.0.0 --title "Version 1.0.0" --target main
+gh release create v1.0.0 --draft
+gh release create v1.0.0 --prerelease
+gh release create v1.0.0 --latest=false # don't mark as latest
+gh release create v1.0.0 --discussion-category Announcements
+
+# With assets in one shot
+gh release create v1.0.0 \
+ --notes-file CHANGELOG.md \
+ ./dist/*.tar.gz ./dist/checksums.txt
+```
+
+## Edit
+
+```bash
+gh release edit v1.0.0 --notes "Updated"
+gh release edit v1.0.0 --draft=false # publish a draft
+gh release edit v1.0.0 --tag v1.0.1 # retag
+gh release edit v1.0.0 --latest # mark as latest
+gh release edit v1.0.0 --prerelease=false
+```
+
+## Assets
+
+```bash
+gh release upload v1.0.0 ./file.tar.gz
+gh release upload v1.0.0 ./a.zip ./b.zip
+gh release upload v1.0.0 ./file.tar.gz#"Release bundle" # display label
+gh release upload v1.0.0 ./file.tar.gz --clobber # overwrite existing
+
+gh release download v1.0.0 # all assets
+gh release download v1.0.0 --pattern "*.tar.gz"
+gh release download v1.0.0 --dir ./downloads
+gh release download v1.0.0 --archive zip # source archive instead
+
+gh release delete-asset v1.0.0 file.tar.gz
+```
+
+## Delete
+
+```bash
+gh release delete v1.0.0 --yes
+gh release delete v1.0.0 --cleanup-tag --yes # also delete git tag
+```
diff --git a/skills/gh-cli/reference/repo.md b/skills/gh-cli/reference/repo.md
new file mode 100644
index 000000000..17b5e0b0e
--- /dev/null
+++ b/skills/gh-cli/reference/repo.md
@@ -0,0 +1,119 @@
+# gh repo — Repositories
+
+Create, clone, list, view, edit, delete, fork, sync repositories. Plus autolinks, deploy keys, gitignore/license templates.
+
+## Create
+
+```bash
+gh repo create my-repo # interactive
+gh repo create my-repo --public # public
+gh repo create my-repo --private # private
+gh repo create my-repo --description "..." \
+ --homepage https://example.com \
+ --license mit --gitignore python
+gh repo create org/my-repo # in org
+gh repo create my-repo --source=. --push # from existing local dir
+gh repo create my-repo --template # mark as template
+gh repo create my-repo --disable-issues --disable-wiki
+```
+
+## Clone
+
+```bash
+gh repo clone owner/repo
+gh repo clone owner/repo my-dir
+gh repo clone owner/repo --branch develop
+gh repo clone owner/repo -- --depth=1 # pass through to git
+```
+
+## List
+
+```bash
+gh repo list # your repos
+gh repo list owner # for user/org
+gh repo list --limit 100
+gh repo list --public # only public
+gh repo list --source # exclude forks
+gh repo list --language go --topic cli # filter
+gh repo list --json name,visibility,owner
+gh repo list --json name --jq '.[].name'
+```
+
+## View
+
+```bash
+gh repo view # current repo
+gh repo view owner/repo
+gh repo view --web # open in browser
+gh repo view --json name,description,defaultBranchRef
+```
+
+## Edit
+
+```bash
+gh repo edit --description "New description"
+gh repo edit --homepage https://example.com
+gh repo edit --visibility private # or public
+gh repo edit --enable-issues --disable-wiki
+gh repo edit --default-branch main
+gh repo edit --add-topic cli --add-topic tooling
+gh repo rename new-name
+gh repo archive # archive
+gh repo unarchive
+```
+
+## Delete
+
+```bash
+gh repo delete owner/repo --yes
+```
+
+## Fork
+
+```bash
+gh repo fork owner/repo
+gh repo fork owner/repo --org my-org
+gh repo fork owner/repo --clone # clone after fork
+gh repo fork owner/repo --remote-name upstream
+```
+
+## Sync fork
+
+```bash
+gh repo sync # sync default branch
+gh repo sync --branch feature # specific branch
+gh repo sync --force # overwrite local divergence
+```
+
+## Default repo (for current directory)
+
+```bash
+gh repo set-default # interactive
+gh repo set-default owner/repo
+gh repo set-default --unset
+```
+
+## Autolinks
+
+```bash
+gh repo autolink list
+gh repo autolink create JIRA- https://jira.example.com/browse/
+gh repo autolink delete 12345
+```
+
+## Deploy keys
+
+```bash
+gh repo deploy-key list
+gh repo deploy-key add ~/.ssh/id_rsa.pub --title "Prod server" --allow-write
+gh repo deploy-key delete 12345
+```
+
+## Gitignore / license templates
+
+```bash
+gh repo gitignore list
+gh repo gitignore view Python
+gh repo license list
+gh repo license view mit
+```
diff --git a/skills/gh-cli/reference/workflows.md b/skills/gh-cli/reference/workflows.md
new file mode 100644
index 000000000..c6b4a811e
--- /dev/null
+++ b/skills/gh-cli/reference/workflows.md
@@ -0,0 +1,120 @@
+# Common workflows — multi-step gh recipes
+
+End-to-end patterns. Each one shows when it's useful and the exact commands.
+
+## Ship a PR end-to-end
+
+```bash
+# Branch off an issue (optional)
+gh issue develop 123 --branch fix/issue-123 --checkout
+
+# ...edit, commit, push...
+git push -u origin fix/issue-123
+
+# Open PR, auto-link the issue
+gh pr create --fill --body "Closes #123"
+
+# Watch CI
+gh pr checks --watch
+
+# Merge when green
+gh pr merge --squash --delete-branch
+```
+
+## Create repo with initial setup
+
+```bash
+gh repo create my-project --public \
+ --description "..." --clone \
+ --gitignore Python --license mit
+cd my-project
+
+git checkout -b develop && git push -u origin develop
+
+gh label create bug --color d73a4a --description "Bug report"
+gh label create enhancement --color a2eeef --description "Feature request"
+gh label create docs --color 0075ca --description "Documentation"
+```
+
+## Fork + keep in sync with upstream
+
+```bash
+gh repo fork original/repo --clone --remote
+cd repo
+gh repo sync # sync default branch
+gh repo sync --branch feature --force # specific branch, overwrite local
+```
+
+## Trigger workflow and wait for it
+
+```bash
+gh workflow run ci.yml --ref main
+sleep 3 # let the run register
+RUN_ID=$(gh run list --workflow ci.yml --limit 1 \
+ --json databaseId --jq '.[0].databaseId')
+gh run watch "$RUN_ID" --exit-status
+gh run download "$RUN_ID" --dir ./artifacts
+```
+
+## Close multiple stale issues
+
+```bash
+gh issue list --label stale --limit 200 \
+ --json number --jq '.[].number' \
+| xargs -I {} gh issue close {} --comment "Closing as stale" --reason "not planned"
+```
+
+## Bulk-label PRs missing review
+
+```bash
+gh pr list --search "is:open review:required" --limit 200 \
+ --json number --jq '.[].number' \
+| xargs -I {} gh pr edit {} --add-label needs-review
+```
+
+## Clone all an org's non-archived repos
+
+```bash
+gh repo list my-org --limit 1000 --no-archived \
+ --json nameWithOwner --jq '.[].nameWithOwner' \
+| xargs -I {} gh repo clone {}
+```
+
+## Watch a PR's checks until green, then auto-merge
+
+```bash
+gh pr checks 123 --watch --interval 10 && \
+ gh pr merge 123 --squash --delete-branch
+# Or enable auto-merge (merges when all required checks pass)
+gh pr merge 123 --squash --auto --delete-branch
+```
+
+## Export release assets for a version
+
+```bash
+gh release download v1.0.0 --dir ./dist --pattern "*.tar.gz"
+gh release view v1.0.0 --json body --jq '.body' > CHANGELOG.md
+```
+
+## Find failed runs and rerun only the failed jobs
+
+```bash
+gh run list --workflow ci.yml --status failure --limit 5 \
+ --json databaseId --jq '.[].databaseId' \
+| xargs -I {} gh run rerun {} --failed
+```
+
+## Who reviewed my PR?
+
+```bash
+gh pr view 123 --json reviews \
+ --jq '.reviews[] | {author: .author.login, state, submittedAt}'
+```
+
+## Scripting tips
+
+- `export GH_TOKEN=$(gh auth token)` before shelling out to tools that expect a `$GH_TOKEN` env var.
+- `export GH_PROMPT_DISABLED=true` to prevent any accidental interactive prompts in CI.
+- `--jq '.[].number'` + `xargs -I {}` is the universal bulk pattern.
+- Always pass `--limit` when iterating — defaults are conservative (30 on most list commands).
+- `gh api --paginate --slurp` returns pages as an array when the endpoint returns objects, not arrays.