name: github-mcp-issues description: Manage GitHub Issues in this repository using the GitHub MCP server tools (create/search/update/comment/close/sub-issues) and produce consistently high-quality issue reports.

GitHub MCP Issues

Use this skill to manage GitHub Issues end-to-end for this repository via the GitHub MCP server tools, and to create high-quality issues (clear scope, reproducible, actionable, correctly triaged).

When to use this skill

Creating a new issue (bug, task, chore, proposal) with strong quality.
Triage: dedupe, reproduce, label, assign, set milestone, close with reason.
Maintaining issue hygiene: status updates, clarifying questions, sub-issues, duplicate handling.

What this skill covers (capabilities)

This skill is designed to cover all GitHub Issue operations available via the MCP tools exposed in this environment:

Search issues (avoid duplicates)
Read issue details, comments, labels, sub-issues
Create or update issues (title/body/labels/assignees/milestone/state/state_reason)
Add comments
Manage sub-issues (add/remove/reprioritize)
List available issue types (when supported by the org)

If you need an operation that is not supported by the available MCP tools (e.g., creating new labels, editing label definitions, managing Projects), call that out explicitly and propose the closest supported alternative.

Steps

Tooling quick guide (what to set)

Prefer search → read → write sequences.
For create/update, use mcp_io_github_git_issue_write:
- title and body should be explicit and stable.
- labels should be minimal and accurate.
- assignees only when someone is truly on point.
- state + state_reason when closing.
For closure reasons:
- Use state: closed, state_reason: completed when done.
- Use state: closed, state_reason: not_planned when intentionally not doing.
- Use state: closed, state_reason: duplicate when superseded; include the canonical issue link/number.

1) Identify intent and scope

Decide what you’re doing:

Create a new issue
Triage/update an existing issue
Close an issue (completed / not planned / duplicate)

If the user request is ambiguous, ask up to 3 clarifying questions. Prefer asking about:

expected behavior vs actual behavior
reproduction steps and environment
desired outcome / acceptance criteria

2) Dedupe first (mandatory for new issues)

Before creating anything:

Use the issues search tool to find likely duplicates.
If a duplicate exists, do not create a new issue.
Instead, add a comment to the existing issue with any new data (repro details, logs, screenshots, workarounds) and optionally mark the new report as a duplicate (close + state_reason duplicate) when appropriate.

3) Choose issue type (if supported) and metadata

If the repository owner supports Issue Types, fetch them first and pick the best match.

Then set:

labels (keep to the minimal set that communicates triage)
assignees (only when appropriate)
milestone (only when the repo uses milestones for planning)

4) Draft a high-quality issue body

Use the template in assets/issue-body-template.md.

Quality rules:

Put the problem statement in the first 2–3 lines.
Include reproduction steps for bugs.
Include acceptance criteria as a short checklist.
Include scope boundaries (what’s explicitly not included).
Include links to code/docs/PRs if relevant.

5) Execute the operation with MCP tools

Use the “Tool map” in references/tooling-map.md.

Always prefer a safe sequence:

read / search → then write
update incrementally (don’t overwrite fields unnecessarily)
when closing, set state_reason

6) Follow-through hygiene

After creating/updating:

add a short “next steps” comment if action is needed from others
if blocked, ask concrete questions in a single comment
if the issue should be broken down, create sub-issues and reprioritize them

Operational playbooks

Create a new issue (safe default)

mcp_io_github_git_search_issues for likely duplicates.
If none, (optional) mcp_io_github_git_list_issue_types and choose a type.
mcp_io_github_git_issue_write with method: create.
If needed, mcp_io_github_git_add_issue_comment for follow-up questions or next steps.

Update an existing issue (triage)

mcp_io_github_git_issue_read (method: get) to avoid clobbering context.
mcp_io_github_git_issue_write with method: update changing only what’s necessary (labels/body/assignees/milestone).

Close an issue with the right reason

(Optional) add a final comment explaining the decision.
mcp_io_github_git_issue_write with method: update, state: closed, and the correct state_reason.

Mark as duplicate

Search and confirm canonical issue.
Comment with a link to the canonical issue.
Close with state_reason: duplicate.

Break down into sub-issues

Create the sub-issues first.
Use mcp_io_github_git_sub_issue_write (method: add) to attach each sub-issue to the parent.
Use method: reprioritize to order them by dependency.

Examples (prompts that should work well)

“Search for duplicates of: ‘install.sh excludes .rpi projects incorrectly’, then create an issue if none exists. Add labels and acceptance criteria.”
“Triage issue #123: summarize, ask 2 clarifying questions, and propose labels. Don’t close it.”
“Close issue #456 as duplicate of #120, and leave a brief explanation comment with the rationale.”
“Break issue #789 into 3 sub-issues, add them, and reprioritize them in a logical order.”

Edge cases

No issue types configured: skip issue type selection and proceed with labels.
Missing metadata conventions: keep labels/assignees/milestones minimal and avoid guessing.
Cannot reproduce: still file the issue if impact is credible; explicitly mark as “needs repro” and list what info is missing.
Sensitive information: do not include secrets, tokens, internal URLs, or personal data in issue bodies/comments.

Resources

Template: assets/issue-body-template.md
Tool map: references/tooling-map.md
Quality checklist: references/issue-quality-checklist.md