--- name: github description: Comprehensive GitHub repository management toolkit. Provides file editing, issue/PR management, GitFlow workflow, release management, commit investigation, CI/CD workflow creation, and configuration file generation via MCP GitHub tools. --- # 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 [options] # Commands: # batch Push multiple files in a single commit # # edit options: # --path File path (required) # --content Content string # --content-file Content from local file # --content-base64 Content (base64 encoded) # --message Commit message (required) # --branch Target branch # apply_fix options: # --path File path (required) # --pattern Text pattern to find (required) # --replacement Replacement text (required) # --message Commit message (required) # --branch Target branch # # batch options: # --files JSON array string # --files-file Path to JSON file containing files array # --files-base64 Base64 encoded JSON array # --message Commit message (required) # --branch 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 [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 Issue title (required) # --body Issue body/description # --labels Comma-separated labels # --checklist Comma-separated checklist items # --assignees Comma-separated assignees # --parent Parent issue number to link as sub-issue # # update options: # --number Issue number (required) # --title New title # --body New body # --state New state: open/closed # --state-reason Reason: completed/not_planned/reopened # --add-labels Labels to add # --remove-labels Labels to remove # --assignees Comma-separated assignees to set # --milestone Milestone number # # list options: # --state Filter: open/closed/all (default: open) # --labels Filter by labels # --limit 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 **Typical Task Examples**: - Create a PR from feature branch to main - Merge a PR with squash strategy - Add "approved" label to a PR > [!TIP] > **Respecting Original Context**: When fixing issues or conflicts in an existing PR, prefer updating and merging the original PR rather than creating a duplicate, unless explicitly instructed otherwise. This preserves the conversation history and context attached to the original PR number. **Usage**: ```bash # Usage: # python pr_manager.py [options] # Commands: # create Create a new PR # merge Merge an existing PR # close Close a PR without merging # update Update PR details (title, body, state, labels) # # create options: # --title PR title (required) # --head Source branch (required) # --base Target branch (required) # --body PR description # --draft Create as draft PR # --merge Merge immediately: squash/merge/rebase # # merge options: # --number PR number (required) # --method Merge method: merge/squash/rebase (default: squash) # --commit-title Custom commit title # --commit-message Custom commit message # # update options: # --number PR number (required) # --title New title # --body New description # --add-labels Labels to add # --remove-labels Labels to remove # # Examples: python pr_manager.py create owner repo --title "Add feature" --head "feature/login" --base "main" python pr_manager.py create owner repo --title "Fix bug" --head "fix" --base "main" --merge squash python pr_manager.py update owner repo --number 42 --add-labels "approved,reviewed" ``` --- ### 4. Comment Manager **File**: `comment_manager.py` **Use Cases**: - Add comments to Issues - Add comments to Pull Requests - Submit PR reviews (comment, approve, request changes) **Typical Task Examples**: - Thank someone for reporting an issue - Add a "LGTM" comment to a PR - Approve a PR with a review comment - Request changes on a PR **Usage**: ```bash # Usage: # python comment_manager.py [options] # Commands: # add Add a comment to an issue or PR # review Submit a PR review # # add options: # --issue Issue number (use this OR --pr) # --pr PR number (use this OR --issue) # --body Comment text (required) # # review options: # --pr PR number (required) # --body Review comment (required) # --event Event: COMMENT/APPROVE/REQUEST_CHANGES (default: COMMENT) # # Examples: python comment_manager.py add owner repo --issue 42 --body "Thanks for reporting!" python comment_manager.py add owner repo --pr 42 --body "LGTM!" python comment_manager.py review owner repo --pr 42 --body "Great work!" --event APPROVE python comment_manager.py review owner repo --pr 42 --body "Please fix..." --event REQUEST_CHANGES ``` --- ### 5. GitHub Detective (Investigation Tools) **File**: `github_detective.py` **Use Cases**: - Explore repository structure (branches, tags, releases, files) - Search commits by message, author, path, or date - Track which commit introduced specific content (searches **Diffs/Patches**, not current Blame) - Search and investigate Pull Requests - Search and investigate Issues **Typical Task Examples**: - List all branches in a repository - Find commits with "fix" in the message - Trace which commit introduced a specific function - Find the PR that introduced authentication - Find issues related to "memory leak" **Usage**: ```bash # Usage: # python github_detective.py [options] # Commands: # explore Explore repository structure # search-commits Search commits by message/author/path # trace-content Find the commit that introduced content # search-prs Search and investigate Pull Requests # search-issues Search and investigate Issues # # explore options: # --show Comma-separated: branches,tags,releases,files # --path Directory path for file listing # --branch Branch for file listing # # search-commits options: # --query Pattern to match in commit messages # --author Filter by author # --path Filter by file path # --branch Branch to search # --since Start date (ISO format: YYYY-MM-DD) # --until End date (ISO format: YYYY-MM-DD) # --limit Maximum results (default: 10) # # trace-content options: # --content Text to search for (required) # --file File to search in (recommended) # --branch Branch to search # --max-commits Maximum commits to scan (default: 10) # --find-branches Find which branches contain the content # # search-prs options: # --query Search PRs by keyword # --number Get specific PR details # --show-files Show files changed (use with --number) # --state Filter: open/closed/all # # search-issues options: # --query Search Issues by keyword # --state Filter: open/closed/all # --limit Maximum results (default: 20) # # Examples: python github_detective.py explore owner repo --show branches,tags python github_detective.py search-commits owner repo --query "fix" --limit 20 python github_detective.py trace-content owner repo --content "def calculate" --file "src/utils.py" python github_detective.py search-prs owner repo --number 42 --show-files python github_detective.py search-issues owner repo --query "bug" --state open ``` --- ### 6. GitFlow Workflow **File**: `gitflow_manager.py` **Use Cases**: - Initialize GitFlow structure (create develop branch from main) - Finish feature/release/hotfix branches (create PR and merge) **Note**: This script handles GitFlow workflow operations. For creating branches, use basic tools. > [!TIP] > **How to Start a Feature/Release**: > GitFlow "start" is simply creating a branch from `develop`. > ```bash > # Start a feature > python run_github_ops.py -c "await github.create_branch('owner', 'repo', 'feature/login', from_branch='develop')" > ``` **Typical Task Examples**: - Initialize GitFlow for a new repository - Finish a feature by merging to develop - Finish a release by merging to main **Usage**: ```bash # Usage: # python gitflow_manager.py [options] # Commands: # init Initialize GitFlow (create develop branch from main) # finish Finish a branch (create PR and merge) # # init options: # (no additional options) # # finish options: # --type Branch type: feature/release/hotfix (required) # --name Branch name without prefix (required) # --target Target branch to merge into (required) # --merge-method Merge method: squash/merge/rebase (default: squash) # # Examples: python gitflow_manager.py init owner repo python gitflow_manager.py finish owner repo --type feature --name "user-auth" --target develop python gitflow_manager.py finish owner repo --type release --name "1.0.0" --target main --merge-method merge ``` --- ### 7. CI/CD Workflow Builder **File**: `workflow_builder.py` **Use Cases**: - Create GitHub Actions workflow files - Generate common CI/CD pipelines (lint, test, scheduled tasks) **IMPORTANT**: These commands are **fully automated pipelines** that create branch, push files, create PR, and merge. Do NOT use when you need manual control over commits. **Typical Task Examples**: - Create a linting workflow for PRs - Add a CI pipeline that runs tests - Create a scheduled health check job **Usage**: ```bash # Usage: # python workflow_builder.py [options] # Commands: # ci-basic Create basic CI workflow (test + build) # lint Create linting workflow with ESLint # scheduled Create scheduled/cron workflow # # ci-basic options: # --trigger Trigger events: push,pull_request (default: push,pull_request) # --branch Branch to run on (default: main) # --node-version Node.js version (default: 18) # # lint options: # --trigger Trigger events (default: push,pull_request) # --branch Branch to run on (default: main) # # scheduled options: # --cron Cron expression (required, e.g., "0 2 * * *") # --script Script to run (required) # --name Workflow name (default: "Nightly Health Check") # # Examples: python workflow_builder.py ci-basic owner repo --trigger "push,pull_request" --branch main python workflow_builder.py lint owner repo --trigger "push,pull_request" --branch main python workflow_builder.py scheduled owner repo --cron "0 2 * * *" --script "npm run health-check" ``` --- ### 8. Release Manager **File**: `release_manager.py` **Use Cases**: - Prepare releases (create release branch + changelog) - Bump version numbers in config files (package.json, Cargo.toml, pyproject.toml) - Generate changelogs from commit history - Finish releases (merge to main) **Typical Task Examples**: - Prepare version 2.1.0 release from develop - Update version in package.json - Generate changelog for the past month - Finish and merge a release **Usage**: ```bash # Usage: # python release_manager.py [options] # Commands: # prepare Prepare a release (create branch + changelog) # bump-version Update version in config file # changelog Generate changelog from commits # finish Finish release (merge to main) # # prepare options: # --version Version number (required, e.g., "2.1.0") # --from Source branch (default: develop) # # bump-version options: # --file Config file: package.json/Cargo.toml/pyproject.toml (required) # --version New version number (required) # --branch Target branch (required) # # changelog options: # --since Start date in ISO format: YYYY-MM-DD (optional) # --until End date in ISO format: YYYY-MM-DD (optional) # --output Output file path (default: CHANGELOG.md) # --branch Target branch (default: main) # # finish options: # --version Version number (required) # --target Target branch (default: main) # --merge-method Merge method: squash/merge/rebase (default: squash) # # Examples: python release_manager.py prepare owner repo --version "2.1.0" --from develop python release_manager.py bump-version owner repo --file "package.json" --version "2.1.0" --branch release/v2.1.0 python release_manager.py changelog owner repo --since "2024-01-01" --output "CHANGELOG.md" python release_manager.py finish owner repo --version "2.1.0" ``` --- ### 9. Config Generator **File**: `config_generator.py` **Use Cases**: - Generate ESLint configuration files - Create Issue templates (bug, feature, maintenance) - Create PR templates **Typical Task Examples**: - Add ESLint config with recommended rules - Standardize issue reporting with templates - Create PR template for code reviews **Usage**: ```bash # Usage: # python config_generator.py [options] # Commands: # eslint Create ESLint configuration # issue-templates Create Issue templates # pr-template Create PR template # # eslint options: # --extends Base config to extend (default: eslint:recommended) # --rules Comma-separated rules: semi,quotes,indent,no-var,prefer-const # --branch Target branch (default: main) # # issue-templates options: # --types Template types: bug,feature,maintenance (default: bug,feature) # --branch Target branch (default: main) # # pr-template options: # --branch Target branch (default: main) # # Examples: python config_generator.py eslint owner repo --extends "eslint:recommended" --rules "semi,quotes" python config_generator.py issue-templates owner repo --types "bug,feature,maintenance" python config_generator.py pr-template owner repo ``` --- ## III. Basic Tools (When to Use Single Functions) Below are the basic tool functions for atomic operations. Use these when skills don't cover your specific need. > [!CAUTION] > 1. **Strictly adhere to the tool list**: Do NOT use any tools or methods not explicitly documented in this section. > 2. **Fragile Arguments**: Do NOT pass multi-line strings or code blocks to `run_github_ops.py`. It uses `eval()`, which is extremely fragile with complex quoting. > 3. **Content Operations**: **ALWAYS** use Skill Scripts (`file_editor.py`, etc.) for content operations. **Note**: Code should be written without line breaks. Do not use multi-line logic or complex scripts. ### How to Run ```bash # Usage: # python run_github_ops.py -c "(args)" # Example: python run_github_ops.py -c "await github.get_file_contents('owner', 'repo', 'README.md', ref='main')" ``` --- ### Branch Tools #### `create_branch(owner, repo, branch, from_branch=None)` Create a new branch in a GitHub repository ```bash python run_github_ops.py -c "await github.create_branch('owner', 'repo', 'feature/new-login', from_branch='main')" ``` #### `list_branches(owner, repo, page=1, per_page=30)` List all branches in a repository. Useful for checking if a branch exists before creating. ```bash python run_github_ops.py -c "await github.list_branches('owner', 'repo')" ``` --- ### File Tools #### `get_file_contents(owner, repo, path, ref=None, sha=None)` Read file content or directory listing. Also returns file SHA needed for updates. ```bash python run_github_ops.py -c "await github.get_file_contents('owner', 'repo', 'src/main.py', ref='develop')" ``` #### `create_or_update_file(owner, repo, path, content, message, branch, sha=None)` Create or update a single file in a GitHub repository. If updating, you must provide the SHA of the file you want to update. Use this tool to create or update a file in a GitHub repository remotely; do not use it for local file operations. ```bash # Create new file: python run_github_ops.py -c "await github.create_or_update_file('owner', 'repo', 'README.md', '# Project', 'Add README', 'main')" # Update existing file (need SHA): python run_github_ops.py -c "await github.create_or_update_file('owner', 'repo', 'README.md', '# Updated', 'Update README', 'main', sha='abc123')" ``` #### `push_files(owner, repo, branch, files, message)` Push multiple files to a GitHub repository in a single commit ```bash python run_github_ops.py -c "await github.push_files('owner', 'repo', 'main', [{'path': 'a.txt', 'content': 'A'}], 'Add files')" ``` --- ### Issue Tools #### `issue_write(owner, repo, title, body=None, labels=None, assignees=None, milestone=None, issue_number=None, state=None, state_reason=None, method=None)` Create a new or update an existing issue in a GitHub repository. ```bash # Create: python run_github_ops.py -c "await github.issue_write('owner', 'repo', 'Bug Report', body='Description', labels=['bug'], method='create')" # Close # fetch issue first to get title python run_github_ops.py -c "await github.issue_write('owner', 'repo', 'Original Title', issue_number=42, state='closed', state_reason='completed', method='update')" ``` #### `issue_read(owner, repo, issue_number, method=None)` Get information about a specific issue in a GitHub repository. ```bash python run_github_ops.py -c "await github.issue_read('owner', 'repo', 42)" ``` #### `add_issue_comment(owner, repo, issue_number, body)` Add a comment to a specific issue in a GitHub repository. Use this tool to add comments to pull requests as well (in this case pass pull request number as issue_number), but only if user is not asking specifically to add review comments. ```bash python run_github_ops.py -c "await github.add_issue_comment('owner', 'repo', 42, 'Thanks for reporting!')" ``` #### `list_issue_types(owner, repo)` List supported issue types for repository owner (organization). ```bash python run_github_ops.py -c "await github.list_issue_types('owner', 'repo')" ``` #### `sub_issue_write(owner, repo, issue_number, title=None, method=None, sub_issue_id=None)` Add a sub-issue to a parent issue in a GitHub repository. ```bash # Create new sub-issue: python run_github_ops.py -c "await github.sub_issue_write('owner', 'repo', 42, title='Sub task')" # Add existing issue as sub-issue: python run_github_ops.py -c "await github.sub_issue_write('owner', 'repo', 42, method='add', sub_issue_id=43)" ``` #### `get_label(owner, repo, name)` Get a specific label from a repository. ```bash python run_github_ops.py -c "await github.get_label('owner', 'repo', 'bug')" ``` --- ### Pull Request Tools #### `create_pull_request(owner, repo, title, head, base, body=None, draft=False, maintainer_can_modify=True)` Create a new pull request in a GitHub repository. ```bash python run_github_ops.py -c "await github.create_pull_request('owner', 'repo', 'Add feature', 'feature-branch', 'main', body='Description', maintainer_can_modify=True)" ``` #### `merge_pull_request(owner, repo, pull_number, merge_method='merge', commit_title=None, commit_message=None)` Merge a pull request in a GitHub repository. ```bash python run_github_ops.py -c "await github.merge_pull_request('owner', 'repo', 42, merge_method='squash')" ``` #### `pull_request_read(owner, repo, pull_number, method=None, per_page=None)` Get information on a specific pull request in GitHub repository. ```bash python run_github_ops.py -c "await github.pull_request_read('owner', 'repo', 42, method='get_files')" ``` #### `update_pull_request(owner, repo, pull_number, title=None, body=None, state=None, labels=None, reviewers=None)` Update an existing pull request in a GitHub repository. ```bash python run_github_ops.py -c "await github.update_pull_request('owner', 'repo', 42, state='closed', labels=['wontfix'])" ``` #### `pull_request_review_write(owner, repo, pullNumber, method=None, body=None, event=None)` Create and/or submit, delete review of a pull request. ```bash python run_github_ops.py -c "await github.pull_request_review_write(owner='owner', repo='repo', pullNumber=42, method='create', body='LGTM! Great implementation.', event='COMMENT')" ``` #### `add_comment_to_pending_review(**kwargs)` Add review comment to the requester's latest pending pull request review. A pending review needs to already exist to call this (check with the user if not sure). ```bash python run_github_ops.py -c "await github.add_comment_to_pending_review(owner='owner', repo='repo', pullNumber=42, body='Fix this', path='file.py', line=10)" ``` #### `update_pull_request_branch(owner, repo, pull_number)` Update the branch of a pull request with the latest changes from the base branch. ```bash python run_github_ops.py -c "await github.update_pull_request_branch('owner', 'repo', 42)" ``` --- ### User & Team Tools #### `get_me()` Get details of the authenticated GitHub user. Use this when a request is about the user's own profile for GitHub. Or when information is missing to build other tool calls. ```bash python run_github_ops.py -c "await github.get_me()" ``` #### `get_teams(org)` Get details of the teams the user is a member of. Limited to organizations accessible with current credentials ```bash python run_github_ops.py -c "await github.get_teams('org-name')" ``` #### `get_team_members(org, team_slug)` Get member usernames of a specific team in an organization. Limited to organizations accessible with current credentials ```bash python run_github_ops.py -c "await github.get_team_members('org-name', 'team-slug')" ``` ---