gh-helper

What this skill does

# GitHub CLI Helper Agent

## Overview

Complete GitHub operations via `gh` CLI and GitHub API. This skill replaces GitHub MCP server functionality, providing CLI/API equivalents for all operations.

## MCP Tool Equivalents Reference

| MCP Tool                     | CLI/API Equivalent                                                 |
| ---------------------------- | ------------------------------------------------------------------ |
| `create_or_update_file`      | `gh api -X PUT /repos/{owner}/{repo}/contents/{path}`              |
| `search_repositories`        | `gh search repos <query>`                                          |
| `create_repository`          | `gh repo create <name>`                                            |
| `get_file_contents`          | `gh api /repos/{owner}/{repo}/contents/{path}`                     |
| `push_files`                 | `git add && git commit && git push`                                |
| `create_issue`               | `gh issue create`                                                  |
| `create_pull_request`        | `gh pr create`                                                     |
| `fork_repository`            | `gh repo fork`                                                     |
| `create_branch`              | `gh api -X POST /repos/{owner}/{repo}/git/refs`                    |
| `list_commits`               | `gh api /repos/{owner}/{repo}/commits`                             |
| `list_issues`                | `gh issue list`                                                    |
| `update_issue`               | `gh issue edit`                                                    |
| `add_issue_comment`          | `gh issue comment`                                                 |
| `search_code`                | `gh search code <query>`                                           |
| `search_issues`              | `gh search issues <query>`                                         |
| `search_users`               | `gh api /search/users?q=<query>`                                   |
| `get_issue`                  | `gh issue view <number>`                                           |
| `get_pull_request`           | `gh pr view <number>`                                              |
| `list_pull_requests`         | `gh pr list`                                                       |
| `create_pull_request_review` | `gh pr review`                                                     |
| `merge_pull_request`         | `gh pr merge`                                                      |
| `get_pull_request_files`     | `gh api /repos/{owner}/{repo}/pulls/{number}/files`                |
| `get_pull_request_status`    | `gh pr checks`                                                     |
| `update_pull_request_branch` | `gh api -X PUT /repos/{owner}/{repo}/pulls/{number}/update-branch` |
| `get_pull_request_comments`  | `gh api /repos/{owner}/{repo}/pulls/{number}/comments`             |
| `get_pull_request_reviews`   | `gh api /repos/{owner}/{repo}/pulls/{number}/reviews`              |

## Auto-Approved Commands

Safe read-only commands:

- `gh repo view`, `gh repo list`
- `gh issue list`, `gh issue view`
- `gh pr list`, `gh pr view`, `gh pr diff`, `gh pr checks`
- `gh run list`, `gh run view`, `gh run watch`
- `gh workflow list`, `gh workflow view`
- `gh release list`, `gh release view`
- `gh search repos`, `gh search code`, `gh search issues`
- `gh status`

---

## Repository Operations

### Search Repositories

```bash
# Basic search
gh search repos "kubernetes operator"

# With filters
gh search repos "react" --language typescript --stars ">1000"
gh search repos "cli tool" --owner hashicorp
gh search repos "mcp server" --topic model-context-protocol

# JSON output for parsing
gh search repos "query" --json fullName,description,stargazersCount
```

### Create Repository

```bash
# Interactive creation
gh repo create

# Create with options
gh repo create my-repo --public --description "My project"
gh repo create my-repo --private --clone

# Create from template
gh repo create my-repo --template owner/template-repo

# Create org repo
gh repo create my-org/my-repo --public
```

### Fork Repository

```bash
# Fork to your account
gh repo fork owner/repo

# Fork and clone
gh repo fork owner/repo --clone

# Fork to organization
gh repo fork owner/repo --org my-org

# Fork with custom name
gh repo fork owner/repo --fork-name my-fork
```

### Get File Contents

```bash
# Get file content via API (returns base64)
gh api /repos/{owner}/{repo}/contents/{path} | jq -r '.content' | base64 -d

# Get file from specific branch
gh api /repos/{owner}/{repo}/contents/{path}?ref=branch-name

# Get directory listing
gh api /repos/{owner}/{repo}/contents/{path}

# Get raw file content
gh api /repos/{owner}/{repo}/contents/{path} -H "Accept: application/vnd.github.raw"
```

### Create or Update File

```bash
# Create new file
gh api -X PUT /repos/{owner}/{repo}/contents/{path} \
  -f message="Add new file" \
  -f content="$(echo 'file content' | base64)" \
  -f branch="main"

# Update existing file (requires SHA)
SHA=$(gh api /repos/{owner}/{repo}/contents/{path} | jq -r '.sha')
gh api -X PUT /repos/{owner}/{repo}/contents/{path} \
  -f message="Update file" \
  -f content="$(echo 'new content' | base64)" \
  -f sha="$SHA" \
  -f branch="main"
```

### Push Multiple Files

Use git commands for pushing multiple files:

```bash
# Stage and commit multiple files
git add file1.txt file2.txt
git commit -m "Add multiple files"
git push origin branch-name

# Or use a single commit for all changes
git add .
git commit -m "Update files"
git push
```

### Create Branch

```bash
# Via git (local)
git checkout -b new-branch
git push -u origin new-branch

# Via API (remote, from default branch)
SHA=$(gh api /repos/{owner}/{repo}/git/refs/heads/main | jq -r '.object.sha')
gh api -X POST /repos/{owner}/{repo}/git/refs \
  -f ref="refs/heads/new-branch" \
  -f sha="$SHA"

# From specific branch
SHA=$(gh api /repos/{owner}/{repo}/git/refs/heads/source-branch | jq -r '.object.sha')
gh api -X POST /repos/{owner}/{repo}/git/refs \
  -f ref="refs/heads/new-branch" \
  -f sha="$SHA"
```

### List Commits

```bash
# List commits via CLI
git log --oneline -20

# List commits via API
gh api /repos/{owner}/{repo}/commits

# With filters
gh api "/repos/{owner}/{repo}/commits?sha=branch&per_page=10"
gh api "/repos/{owner}/{repo}/commits?author=username"
gh api "/repos/{owner}/{repo}/commits?since=2024-01-01T00:00:00Z"

# JSON output
gh api /repos/{owner}/{repo}/commits --jq '.[].commit.message'
```

---

## Issue Operations

### List Issues

```bash
# List open issues
gh issue list

# With filters
gh issue list --state open
gh issue list --state closed
gh issue list --state all
gh issue list --assignee @me
gh issue list --assignee username
gh issue list --author @me
gh issue list --label bug
gh issue list --label "bug,priority:high"
gh issue list --milestone "v1.0"

# Search with query
gh issue list --search "is:open label:bug"

# JSON output
gh issue list --json number,title,state,labels
```

### Get Issue Details

```bash
# View issue
gh issue view 123

# View in web browser
gh issue view 123 --web

# JSON output
gh issue view 123 --json number,title,body,state,labels,assignees,comments

# Get comments
gh issue view 123 --comments
```

### Create Issue

```bash
# Interactive
gh issue create

# With options
gh issue create --title "Bug report" --body "Description"
gh issue create --title "Feature" --label enhancement --assignee @me
gh issue create --title "Bug" --milestone "v1.0" --project "Board"

# From file
gh issue create --title "Issue" --body-file issue-body.md

# Open in editor
gh issue create --title "Issue" --editor
```

### Update Issue

```bash
# Edit title
gh issue edit 123 --title "New title"

# Edit body
gh issue edit 123 --body "New description"
gh issue edit 123 --body-file updated.md

# Modify labels
gh issue edit 123 --add-lab