GitHub Issues Management

Create, retrieve, update, and manage GitHub issues with comprehensive context integration and structured workflows.

When to Use This Skill

Activate this skill when:

The user wants to create a new GitHub issue

The user asks to view or retrieve issue details

The user needs to update an existing issue

The user wants to list issues in a repository

The user mentions managing issues, bug reports, or feature requests in GitHub

The user wants to close, reopen, or modify issue properties

The user needs to add comments or labels to issues

The user wants to search for issues

Critical Rules

IMPORTANT: Always confirm owner/repo before creating or modifying issues

Always use descriptive issue titles and provide structured descriptions

Never create duplicate issues - search existing issues first when appropriate

Available MCP Tools

Tool

Purpose

github-mcp(create_issue)

Create new issues

github-mcp(update_issue)

Update existing issues

github-mcp(get_issue)

Fetch issue details

github-mcp(search_issues)

Search issues

github-mcp(add_issue_comment)

Add comments

github-mcp(list_issues)

List repository issues

Workflow

1. Gather Context

First, collect information about the current repository and context:

Identify the repository (owner and repo name)

Understand the type of issue (bug, feature, task, etc.)

Gather relevant labels, milestones, and assignees if applicable

2. Repository Verification

Before any operation, verify you have the correct repository identifier:

Confirm repository exists

Understand repository structure

Check available labels and milestones

3. Issue Operations

Creating a New Issue

When creating issues, gather complete context:

Required Information:

owner

Repository owner (organization or user)

repo

Repository name

title

Clear, descriptive issue title

Optional but Recommended:

body

Detailed description in Markdown format

labels

Array of label names (e.g., ["bug", "enhancement"])

assignees

Array of usernames to assign

milestone

Milestone number (integer) Human-in-the-Loop - Ask for Context Always ask to clarify issue details: Question: "What type of issue is this?" Options: - "Bug report - something is not working correctly" - "Feature request - new functionality needed" - "Task - work item to complete" - "Documentation - documentation needs update" - "Other - let me describe it" Title Guidelines: Start with type prefix when useful: [Bug] , [Feature] , [Docs] Be specific and actionable Keep under 72 characters Examples: [Bug] Login fails with SSO enabled [Feature] Add dark mode support Add unit tests for auth module Issue Description Template: Structure descriptions for clarity:

Summary [Brief description of the issue]

Current Behavior [What is happening now - for bugs]

Expected Behavior [What should happen - for bugs]

Steps to Reproduce [For bugs - numbered steps]

Acceptance Criteria [For features/tasks - what defines "done"]

Additional Context

[Screenshots, logs, related issues, etc.]

Retrieving Issue Details

Use

github-mcp(get_issue)

with:

owner

Repository owner

repo

Repository name

issue_number

Issue number (e.g., 42)

This returns complete issue information including:

Title and body

State (open/closed)

Labels and milestone

Assignees and author

Created/updated timestamps

Listing Issues

Use

github-mcp(list_issues)

with filters:

owner

Repository owner

repo

Repository name

state

"open", "closed", or "all"

labels

Filter by labels (comma-separated)

assignee

Filter by assignee username

sort

Sort by "created", "updated", "comments"

direction

"asc" or "desc"

per_page

Results per page (max 100)

Searching Issues

Use

github-mcp(search_issues)

for advanced queries:

Search across repositories

Use GitHub search qualifiers (is:open, label:bug, etc.)

Full-text search in titles and bodies

Updating an Issue

When updating issues, only provide changed fields:

Use

github-mcp(update_issue)

with:

owner

Repository owner

repo

Repository name

issue_number

Issue number

Plus any fields to update (title, body, labels, state, etc.)

State Changes:

state: "open"

- Open/reopen the issue

state: "closed"

- Close the issue

Adding Comments

Use

github-mcp(add_issue_comment)

with:

owner

Repository owner

repo

Repository name

issue_number

Issue number

body

Comment content in Markdown 4. Execute Operations (Requires Confirmation) CRITICAL: Confirm with user before creating or modifying issues After gathering all information, present a summary for user approval: Creating issue in repository: owner/repo Title: [title] Description: [summary] Labels: [labels] Assignee: [assignee] Proceed with issue creation? Issue Type Templates Bug Report

Description The [component] is experiencing [issue] when [condition].

Steps to Reproduce 1. [First step] 2. [Second step] 3. [See error]

Expected Behavior [What should happen]

Actual Behavior [What actually happens]

Environment

Application Version: [version]

Screenshots/Logs [Attach relevant files]

Possible Solution [Optional: if you have ideas] Feature Request

Summary [One-line description of the feature]

Motivation [Why is this feature needed? What problem does it solve?]

Proposed Solution [How should this work?]

Acceptance Criteria

[ ] [ Criterion 1 ] - [ ] [ Criterion 2 ] - [ ] [ Criterion 3 ]

Alternatives Considered [Other approaches considered]

Additional Context [Mockups, examples, references] Task

Task Description [What needs to be done]

Background [Why is this needed?]

Requirements

[ ] [ Requirement 1 ] - [ ] [ Requirement 2 ]

Definition of Done

[ ] [ Criterion 1 ] - [ ] [ Criterion 2 ]

Dependencies [Related issues, blockers] Examples Example 1: Creating a Bug Report User: "Create a bug issue - the login page crashes when using SSO" AI Workflow: Ask for repository (owner/repo) if not known Ask clarifying questions about the bug Generate structured description Present summary for confirmation Create issue with github-mcp(create_issue) Result: { "owner" : "myorg" , "repo" : "webapp" , "title" : "[Bug] Login page crashes when using SSO" , "body" : "## Description\nThe login page crashes when users attempt to authenticate using SSO.\n\n## Steps to Reproduce\n1. Navigate to login page\n2. Click 'Sign in with SSO'\n3. Page crashes\n\n## Expected Behavior\nSSO authentication should complete and redirect to dashboard.\n\n## Actual Behavior\nPage becomes unresponsive and displays error.\n\n## Environment\n- Browser: [To be filled]\n- OS: [To be filled]" , "labels" : [ "bug" ] } Example 2: Feature Request with Priority User: "Create a feature request for dark mode with high priority" AI Workflow: Gather feature details Structure the request Add appropriate labels Confirm and create Result: { "owner" : "myorg" , "repo" : "webapp" , "title" : "[Feature] Add dark mode support" , "body" : "## Summary\nAdd dark mode theme option for improved user experience and accessibility.\n\n## Motivation\n- Reduces eye strain in low-light environments\n- Increasingly expected by users\n- Improves accessibility\n\n## Proposed Solution\nImplement theme toggle with system preference detection.\n\n## Acceptance Criteria\n- [ ] Toggle switch in settings\n- [ ] Persists user preference\n- [ ] Respects system preference by default\n- [ ] All UI components support both themes" , "labels" : [ "enhancement" , "high-priority" ] } Example 3: Listing and Filtering Issues User: "Show me all open bugs assigned to me" AI Workflow: Use github-mcp(list_issues) with filters: state: "open" labels: "bug" assignee: [current user] Result: Found 3 open bug issues assigned to you:

142 - [Bug] API timeout on large file uploads

Labels: bug, priority-medium Created: 2024-01-15

138 - [Bug] Dashboard graphs not rendering on Safari

Labels: bug, frontend Created: 2024-01-12

125 - [Bug] Email notifications delayed by 30+ minutes

Labels: bug, priority-high Created: 2024-01-08 Example 4: Closing an Issue with Comment User: "Close issue #142 and add a comment that it's fixed in v2.4.0" AI Workflow: First, add a comment to the issue Then update issue state to closed Using github-mcp(add_issue_comment): { "owner" : "myorg" , "repo" : "webapp" , "issue_number" : 142 , "body" : "Fixed in v2.4.0. Closing this issue." } Using github-mcp(update_issue): { "owner" : "myorg" , "repo" : "webapp" , "issue_number" : 142 , "state" : "closed" } Common Labels Use these standard labels when applicable: Label Use For bug Something isn't working enhancement New feature or improvement documentation Documentation updates good first issue Good for newcomers help wanted Extra attention needed question Further information requested wontfix Will not be addressed duplicate Already exists invalid Not a valid issue Important Notes Always verify repository access - Ensure you have permission to create/modify issues Use labels consistently - Follow repository labeling conventions Be specific in titles - Prefix with [Bug], [Feature], [Task] for clarity Include reproduction steps - Essential for bug reports Define acceptance criteria - Clear "definition of done" for features/tasks Link related issues - Use "Related to #XX" or "Blocks #XX" in descriptions Mention users with @username - For visibility and notifications Use milestones - Associate issues with releases when applicable GitHub Issue Best Practices Writing Effective Titles Be concise but descriptive Include issue type prefix: [Bug], [Feature], [Task], [Docs] Mention affected component if applicable Avoid vague titles like "Fix bug" or "Update code" Structuring Descriptions Use Markdown formatting for readability Include all relevant context upfront Add screenshots or logs when helpful Link to related issues, PRs, or documentation Use task lists for trackable sub-items Label Strategy Combine type labels ( bug , enhancement ) with area labels ( frontend , api ) Use priority labels when needed ( priority-high , priority-low ) Keep label taxonomy consistent across repositories Assignment and Workflow Assign issues to specific team members Use milestones for release planning Update issue status as work progresses Close issues with reference to fixing PR: "Fixes #XX"