github-operations - SKILL.md Agent Skill

name: github-operations description: Handles GitHub issues, pull requests, repositories, Actions, releases, and API tasks using MCP-first workflows with gh CLI fallback for advanced operations. license: MIT metadata: author: hack-ops version: "3.0" category: github

GitHub Operations

Manage all GitHub operations using MCP tools (preferred) and GitHub CLI (fallback).

MCP-first: Use MCP tools for issues and PRs — no extra auth, works everywhere. CLI fallback: Use gh CLI for Actions, releases, repos, secrets, and API calls.

Reference Files (Load on Demand)

File	When to Load
`references/mcp-tools.md`	Creating/managing issues and pull requests via MCP
`references/gh-cli.md`	Actions, releases, repos, secrets, API — CLI fallback

MCP Priority Protocol (Mandatory)

Follow this protocol for every GitHub task:

Identify required operation (issue, PR, search, Actions, release, repo admin, etc.)
Check whether an MCP tool exists for that exact operation
If MCP exists, use MCP only
Use gh CLI only when no equivalent MCP write tool is available

Devcontainer Reliability Rule

Do not run gh auth login or gh auth status in devcontainer workflows unless the user explicitly asks for CLI auth troubleshooting.
For PR/issue creation, rely on MCP tool authentication by default.
If MCP write tools are missing in the current environment, report the limitation explicitly and provide a no-auth fallback path (for example, PR compare URL).

Decision Matrix

Operation	Tool	Reference
Create/read/update issues	MCP (`mcp_github_issue_write`, `mcp_github_issue_read`)	`references/mcp-tools.md`
Search issues	MCP (`mcp_github_search_issues`)	`references/mcp-tools.md`
Create/merge/review PRs	MCP (`mcp_github_create_pull_request`, etc.)	`references/mcp-tools.md`
List/search PRs	MCP (`mcp_github_list_pull_requests`, etc.)	`references/mcp-tools.md`
Repo create/clone/fork	`gh repo`	`references/gh-cli.md`
Workflow run/list/watch	`gh workflow`, `gh run`	`references/gh-cli.md`
Releases	`gh release`	`references/gh-cli.md`
Secrets & variables	`gh secret`, `gh variable`	`references/gh-cli.md`
REST/GraphQL API	`gh api`	`references/gh-cli.md`
Labels	`gh label`	`references/gh-cli.md`
Search code/repos	`gh search`	`references/gh-cli.md`

DO / DON'T

DO: Use MCP tools first for issues and PRs
DO: Use gh CLI for Actions, releases, repos, secrets, API
DO: Explain when MCP write tools are unavailable and why fallback is required
DO: Confirm repository context before creating issues/PRs
DO: Search for existing issues/PRs before creating duplicates
DO: Check for PR templates before creating PRs
DO: Ask for missing critical information rather than guessing
DON'T: Create issues/PRs without confirming repo owner and name
DON'T: Merge PRs without user confirmation
DON'T: Use gh CLI for issues/PRs when MCP tools are available
DON'T: Attempt gh auth flows in devcontainers unless explicitly requested

References

GitHub CLI Manual: https://cli.github.com/manual/
REST API: https://docs.github.com/en/rest
GraphQL API: https://docs.github.com/en/graphql