github

What this skill does

# GitHub Skill

This skill provides complete GitHub repository management capabilities using MCP GitHub tools.

## Core Concepts

1. **Skill**: Meaningful combinations of multiple tool calls, encapsulated as independent Python scripts
2. **Basic Tools**: Single function calls for atomic operations via `run_github_ops.py`

---

## I. Strategy: Skills vs Tools (Read First)

### 1. Skill-First Strategy

Always prioritize **Skill Scripts** over atomic tools. Skills encapsulate best practices and error handling.

| Goal                      | Recommended Skill         | Why?                                             |
| :------------------------ | :------------------------ | :----------------------------------------------- |
| **Multi-file Edits**      | `file_editor.py batch`    | Atomic commit; prevents partial updates          |
| **Content Investigation** | `github_detective.py`     | Unified interface for all investigation tasks    |
| **GitFlow Operations**    | `gitflow_manager.py`      | Enforces naming conventions and correct workflow |
| **PR + Label Management** | `pr_manager.py update`    | Handles labels atomically with PR updates        |
| **Issue + Label**         | `issue_manager.py update` | Handles labels atomically with issue updates     |
| **CI/CD Setup**           | `workflow_builder.py`     | Full automated pipeline (branch → PR → merge)    |
| **Release Preparation**   | `release_manager.py`      | Automates version bump, changelog, and merge     |
| **Project Config**        | `config_generator.py`     | Standardized templates and configurations        |

### 2. When to Use Basic Tools

Only use `run_github_ops.py` when:
1. **Unique Filtering**: Need specific API filters not exposed by skills
2. **One-off Read**: Quick check of file SHA or content
3. **Custom Operations**: Operations not covered by any skill

### 3. GitHub Domain Coverage

This skill covers the following GitHub task categories:

| Category               | Covered By                                       |
| :--------------------- | :----------------------------------------------- |
| File CRUD              | `file_editor.py`, basic file tools               |
| Issue Management       | `issue_manager.py`                               |
| PR Management          | `pr_manager.py`                                  |
| Label Management       | `issue_manager.py`, `pr_manager.py` (integrated) |
| Branch Management      | `gitflow_manager.py`, basic branch tools         |
| Commit Investigation   | `github_detective.py`                            |
| PR Investigation       | `github_detective.py`                            |
| Repository Exploration | `github_detective.py`                            |
| CI/CD Workflows        | `workflow_builder.py`                            |
| Release Management     | `release_manager.py`                             |
| Config Generation      | `config_generator.py`                            |

### 4. Command Line Safety

> [!WARNING]
> **Shell Escaping**: When passing complex strings (JSON, Python code, multi-line text) in command line arguments, be extremely careful with shell escaping.
> Ensure quotes are matched and special characters (like `$`) are handled correctly to prevent execution errors.


---

## II. Skills (High-Level Scripts)

### 1. File Editing

**File**: `file_editor.py`

**Use Cases**:
- Create new files in a repository
- Edit/overwrite existing files
- Apply search-and-replace fixes to a single file
- Push multiple files in a single commit (atomic batch operations)

**Typical Task Examples**:
- Create a README.md file
- Update configuration files
- Fix a typo or bug in a specific file

> [!Note]
> **Check Default Branch**: Before editing or creating files, ALWAYS check the default branch name (e.g., using `github_detective.py explore` or `list_branches`) unless you are explicitly targeting a specific feature branch.

**Usage**:
```bash
# Usage:
#   python file_editor.py <command> <owner> <repo> [options]
# Commands:
#   batch       Push multiple files in a single commit
#
# edit options:
#   --path <filepath>         File path (required)
#   --content <text>          Content string
#   --content-file <path>     Content from local file
#   --content-base64 <b64>    Content (base64 encoded)
#   --message <text>          Commit message (required)
#   --branch <name>           Target branch
# apply_fix options:
#   --path <filepath>         File path (required)
#   --pattern <text>          Text pattern to find (required)
#   --replacement <text>      Replacement text (required)
#   --message <text>          Commit message (required)
#   --branch <name>           Target branch
#
# batch options:
#   --files <json>            JSON array string
#   --files-file <path>       Path to JSON file containing files array
#   --files-base64 <b64>      Base64 encoded JSON array
#   --message <text>          Commit message (required)
#   --branch <name>           Target branch
#
# Examples:
#
python file_editor.py edit owner repo --path "docs/README.md" --content "# Documentation\n\nUpdated content." --message "Update README"
python file_editor.py batch owner repo --files '[{"path": "test.txt", "content": "test"}]' --message "Add files"
python file_editor.py edit owner repo --path "version.txt" --content "1.0.0" --message "Update version"
```

---

### 2. Issue Management

**File**: `issue_manager.py`

**Use Cases**:
- Create new issues with labels and checklists
- Create sub-issues linked to a parent issue
- Update issue title, body, state, and labels
- Close/reopen issues with state reasons
- List issues with filters
- Batch close/reopen issues

**Typical Task Examples**:
- Create a bug report issue
- Create sub-issues linked to a tracking issue
- Close an issue as completed and add "wontfix" label
- Add or remove labels from an existing issue

**Usage**:
```bash
# Usage:
#   python issue_manager.py <command> <owner> <repo> [options]
# Commands:
#   create      Create a new issue (optionally as sub-issue)
#   update      Update an existing issue (title, body, state, labels)
#   list        List issues with filters
#   close       Batch close issues (requires filter)
#   reopen      Batch reopen issues (requires query)
# create options:
#   --title <text>        Issue title (required)
#   --body <text>         Issue body/description
#   --labels <csv>        Comma-separated labels
#   --checklist <csv>     Comma-separated checklist items
#   --assignees <csv>     Comma-separated assignees
#   --parent <n>          Parent issue number to link as sub-issue
#
# update options:
#   --number <n>          Issue number (required)
#   --title <text>        New title
#   --body <text>         New body
#   --state <state>       New state: open/closed
#   --state-reason <r>    Reason: completed/not_planned/reopened
#   --add-labels <csv>    Labels to add
#   --remove-labels <csv> Labels to remove
#   --assignees <csv>     Comma-separated assignees to set
#   --milestone <n>       Milestone number
#
# list options:
#   --state <state>       Filter: open/closed/all (default: open)
#   --labels <csv>        Filter by labels
#   --limit <n>           Maximum results (default: 30)
#
# Output: Issue number and database ID are printed (e.g., "Created issue #52 (ID: 3753519439)")
#
# Examples:
python issue_manager.py create owner repo --title "Bug Report" --body "Description" --labels "bug,priority-high"
python issue_manager.py create owner repo --title "Sub-task 1" --body "Details" --parent 51
python issue_manager.py update owner repo --number 42 --state closed --state-reason completed --add-labels "wontfix"
python issue_manager.py list owner repo --state open --labels "bug"
```

---

### 3. Pull Request Management

**File**: `pr_manager.py`

**Use Cases**:
- Create PRs from branches
- Create and immediately merge PRs
- Merge PRs with different strategies (merge/squash/rebase)
- Close PRs without merging
- Update PR details including labels