/github-issues

name: github-issues
description: 'Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, manage repository labels, set issue fields (dates, priority, custom fields), set issue types, manage issue workflows, link issues, add dependencies, or track blocked-by/blocking relationships. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", "set the priority", "set the start date", "create a label", "rename a label", "list repo labels", "link issues", "add dependency", "blocked by", "blocking", or any GitHub issue management task.'

GitHub Issues

Manage GitHub issues using the `@modelcontextprotocol/server-github` MCP server.

Available Tools

MCP Tools (read operations)

| Tool | Purpose | |------|---------| | `mcp__github__issue_read` | Read issue details, sub-issues, comments, labels (methods: get, get_comments, get_sub_issues, get_labels) | | `mcp__github__list_issues` | List and filter repository issues by state, labels, date | | `mcp__github__search_issues` | Search issues across repos using GitHub search syntax | | `mcp__github__projects_list` | List projects, project fields, project items, status updates | | `mcp__github__projects_get` | Get details of a project, field, item, or status update | | `mcp__github__projects_write` | Add/update/delete project items, create status updates |

MCP Tools (write operations)

| Tool | Purpose | |------|---------| | `mcp__github__issue_write` | Create or update an issue (methods: create, update). Supports title, body, type, labels, assignees, milestone, and issue fields | | `mcp__github__add_issue_comment` | Add a comment or a reaction to an issue | | `mcp__github__sub_issue_write` | Add, remove, or reprioritize a sub-issue |

CLI / REST API (write operations)

`gh api` performs the same writes and is the form used in the examples below. Reach for it when the MCP server is not connected, or when you need a REST field the MCP tools do not expose.

| Operation | Command | |-----------|---------| | Create issue | `gh api repos/{owner}/{repo}/issues -X POST -f title=... -f body=...` | | Update issue | `gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f title=... -f state=...` | | Add comment | `gh api repos/{owner}/{repo}/issues/{number}/comments -X POST -f body=...` | | Close issue | `gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f state=closed` | | Set issue type | Include `-f type=Bug` in the create call (REST API only, not supported by `gh issue create` CLI) |

**Note:** `gh issue create` works for basic issue creation but does **not** support the `--type` flag. Use `gh api` when you need to set issue types.

Workflow

1. **Determine action**: Create, update, or query? 2. **Gather context**: Get repo info, existing labels, milestones if needed 3. **Structure content**: Use appropriate template from [references/templates.md](references/templates.md) 4. **Execute**: Use MCP tools for reads, `gh api` for writes 5. **Confirm**: Report the issue URL to user

Creating Issues

Use `gh api` to create issues. This supports all parameters including issue types.

gh api repos/{owner}/{repo}/issues \
  -X POST \
  -f title="Issue title" \
  -f body="Issue body in markdown" \
  -f type="Bug" \
  --jq '{number, html_url}'

Optional Parameters

Add any of these flags to the `gh api` call:

-f type="Bug"                    # Issue type (Bug, Feature, Task, Epic, etc.)
-f 'labels[]=bug'                # Labels (repeat for multiple)
-f 'assignees[]=username'        # Assignees (repeat for multiple)
-f milestone=1                   # Milestone number

**Quote the whole `name[]=value` pair.** `[]` is a glob pattern in zsh, the default shell on macOS, so an unquoted `-f labels[]=bug` never reaches `gh`:

zsh: no matches found: labels[]=bug

**Issue types** are organization-level metadata. To discover available types, use:

gh api graphql -f query='{ organization(login: "ORG") { issueTypes(first: 10) { nodes { name } } } }' --jq '.data.organization.issueTypes.nodes[].name'

**Prefer issue types over labels for categorization.** When issue types are available (e.g., Bug, Feature, Task), use the `type` parameter instead of applying equivalent labels like `bug` or `enhancement`. Issue types are the canonical way to categorize issues on GitHub. Only fall back to labels when the org has no issue types configured.

Title Guidelines

• Be specific and actionable
• Keep under 72 characters
• When issue types are set, don't add redundant prefixes like `[Bug]`
• Examples:
• `Login fails with SSO enabled` (with type=Bug)
• `Add dark mode support` (with type=Feature)
• `Add unit tests for auth module` (with type=Task)

Body Structure

Always use the templates in [references/templates.md](references/templates.md). Choose based on issue type:

| User Request | Template | |--------------|----------| | Bug, error, broken, not working | Bug Report | | Feature, enhancement, add, new | Feature Request | | Task, chore, refactor, update | Task |

Updating Issues

Use `gh api` with PATCH:

gh api repos/{owner}/{repo}/issues/{number} \
  -X PATCH \
  -f state=closed \
  -f title="Updated title" \
  --jq '{number, html_url}'

Only include fields you want to change. Available fields: `title`, `body`, `state` (open/closed), `labels`, `assignees`, `milestone`.

Examples

Example 1: Bug Report

**User**: "Create a bug issue - the login page crashes when using SSO"

**Action**:

gh api repos/github/awesome-copilot/issues \
  -X POST \
  -f title="Login page crashes when using SSO" \
  -f type="Bug" \
  -f body="## Description
The login page crashes when users attempt to authenticate using SSO.

## Steps to Reproduce
1. Navigate to login page
2. Click 'Sign in with SSO'
3. Page cras