Github Issues

GitHubOfficialContributed by @tgrall via pull request #550Distributed by GitHub

Skill
Tool integration
Software development
MIT
No issues found

From the author

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.

— the description by tgrall

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a comprehensive interface for interacting with GitHub issues. It leverages the Model Context Protocol (MCP) for efficient read and write operations, while integrating with the GitHub CLI (gh) for advanced tasks that require specific REST or GraphQL API calls. It covers the full lifecycle of issue management, including creation, updates, categorization, project tracking, and complex dependency mapping.

What it does

Create, update, and manage GitHub issues with support for custom fields and issue types.
List, search, and filter repository issues using standard GitHub search syntax.
Manage repository labels, milestones, and project board items.
Handle complex issue relationships including sub-issues and blocked-by/blocking dependencies.
Add comments and reactions to existing issues.
Provide guidance on embedding images and structuring issue content using templates.

When to use it

When you need to automate the creation of bug reports or feature requests.
When managing project workflows and tracking issue dependencies.
When you need to perform bulk updates or complex queries across multiple repositories.
When you need to interact with GitHub project boards or custom issue metadata.

Advantages

Unified interface for both simple issue management and advanced API operations.
Supports canonical GitHub issue types for better categorization.
Provides structured templates for consistent bug and feature reporting.
Enables programmatic management of blocked-by/blocking relationships.
Offers clear guidance on handling private repository images and metadata.

Usage examples

“Create a bug report for the login page crashing when using SSO.”: The agent uses the GitHub API to create an issue with the title, body, and type 'Bug' set, returning the new issue's URL.
“List all high-priority issues in the current repository.”: The agent uses the MCP search tool to filter issues by the 'high-priority' label and returns a summary list.
“Mark issue #10 as blocked by issue #5.”: The agent executes the necessary REST API call to establish a blocking dependency between the two issues.
“Update issue #12 to closed and add a comment.”: The agent performs a PATCH request to update the issue state and a POST request to add the specified comment.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/github/github-issues/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip github-issues.zip -d .agents/skills

Documentation by tgrall

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

Determine action: Create, update, or query?
Gather context: Get repo info, existing labels, milestones if needed
Structure content: Use appropriate template from references/templates.md
Execute: Use MCP tools for reads, gh api for writes
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. 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 crashes

## Expected Behavior
SSO authentication should complete and redirect to dashboard.

## Actual Behavior
Page becomes unresponsive and displays error." \
  --jq '{number, html_url}'

Example 2: Feature Request

User: "Create a feature request for dark mode with high priority"

Action:

gh api repos/github/awesome-copilot/issues \
  -X POST \
  -f title="Add dark mode support" \
  -f type="Feature" \
  -f 'labels[]=high-priority' \
  -f body="## Summary
Add dark mode theme option for improved user experience and accessibility.

## Motivation
- Reduces eye strain in low-light environments
- Increasingly expected by users

## Proposed Solution
Implement theme toggle with system preference detection.

## Acceptance Criteria
- [ ] Toggle switch in settings
- [ ] Persists user preference
- [ ] Respects system preference by default" \
  --jq '{number, html_url}'

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
`high-priority`	Urgent issues

Tips

Always confirm the repository context before creating issues
Ask for missing critical information rather than guessing
Link related issues when known: Related to #123
For updates, fetch current issue first to preserve unchanged fields

Extended Capabilities

The following features require REST or GraphQL APIs beyond the basic MCP tools. Each is documented in its own reference file so the agent only loads the knowledge it needs.

Capability	When to use	Reference
Advanced search	Complex queries with boolean logic, date ranges, cross-repo search, issue field filters (`field.name:value`)	references/search.md
Sub-issues & parent issues	Breaking work into hierarchical tasks	references/sub-issues.md
Milestones	Create, read, update, close, reopen, delete milestones and manage milestone issues	references/milestones.md
Labels	Discover, create, rename, recolor, and delete repository labels; add or replace labels on an issue	references/labels.md
Issue dependencies	Tracking blocked-by / blocking relationships	references/dependencies.md
Issue types (advanced)	GraphQL operations beyond MCP `list_issue_types` / `type` param	references/issue-types.md
Projects V2	Project boards, progress reports, field management	references/projects.md
Issue fields	Custom metadata: dates, priority, text, numbers (private preview)	references/issue-fields.md
Images in issues	Embedding images in issue bodies and comments via CLI	references/images.md

Files

ATTRIBUTION.mdAdded by AutoGineer927 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md9.0 KiB
references/dependencies.md1.8 KiB
references/images.md4.7 KiB
references/issue-fields.md7.6 KiB
references/issue-types.md1.7 KiB
references/labels.md5.2 KiB
references/milestones.md2.4 KiB
references/projects.md8.4 KiB
references/search.md7.1 KiB
references/sub-issues.md3.6 KiB
references/templates.md1.4 KiB

references/search.md

Advanced Issue Search

The search_issues MCP tool uses GitHub's issue search query format for cross-repo searches, supporting implicit-AND queries, date ranges, and metadata filters (but not explicit OR/NOT operators).

When to Use Search vs List vs Advanced Search

There are three ways to find issues, each with different capabilities:

Capability	`list_issues` (MCP)	`search_issues` (MCP)	Advanced search (`gh api`)
Scope	Single repo only	Cross-repo, cross-org	Cross-repo, cross-org
Issue field filters (`field.priority:P0`)	No	No	Yes (dot notation)
Issue type filter (`type:Bug`)	No	Yes	Yes
Boolean logic (AND/OR/NOT, nesting)	No	Yes (implicit AND only)	Yes (explicit AND/OR/NOT)
Label/state/date filters	Yes	Yes	Yes
Assignee/author/mentions	No	Yes	Yes
Negation (`-label:x`, `no:label`)	No	Yes	Yes
Text search (title/body/comments)	No	Yes	Yes
`since` filter	Yes	No	No
Result limit	No cap (paginate all)	1,000 max	1,000 max
How to call	MCP tool directly	MCP tool directly	`gh api` with `advanced_search=true`

Decision guide:

Single repo, simple filters (state, labels, recent updates): use list_issues
Cross-repo, text search, author/assignee, issue types: use search_issues
Issue field values (Priority, dates, custom fields) or complex boolean logic: use gh api with advanced_search=true

Query Syntax

The query parameter is a string of search terms and qualifiers. A space between terms is implicit AND.

Scoping

repo:owner/repo       # Single repo (auto-added if you pass owner+repo params)
org:github            # All repos in an org
user:octocat          # All repos owned by user
in:title              # Search only in title
in:body               # Search only in body
in:comments           # Search only in comments

State & Close Reason

is:open               # Open issues (auto-added: is:issue)
is:closed             # Closed issues
reason:completed      # Closed as completed
reason:"not planned"  # Closed as not planned

People

author:username       # Created by
assignee:username     # Assigned to
mentions:username     # Mentions user
commenter:username    # Has comment from
involves:username     # Author OR assignee OR mentioned OR commenter
author:@me            # Current authenticated user
team:org/team         # Team mentioned

Labels, Milestones, Projects, Types

label:"bug"                 # Has label (quote multi-word labels)
label:bug label:priority    # Has BOTH labels (AND)
label:bug,enhancement       # Has EITHER label (OR)
-label:wontfix              # Does NOT have label
milestone:"v2.0"            # In milestone
project:github/57           # In project board
type:"Bug"                  # Issue type

Missing Metadata

no:label              # No labels assigned
no:milestone          # No milestone
no:assignee           # Unassigned
no:project            # Not in any project

Dates

All date qualifiers support >, <, >=, <=, and range (..) operators with ISO 8601 format:

created:>2026-01-01              # Created after Jan 1
updated:>=2026-03-01             # Updated since Mar 1
closed:2026-01-01..2026-02-01   # Closed in January
created:<2026-01-01              # Created before Jan 1

Linked Content

linked:pr             # Issue has a linked PR
-linked:pr            # Issues not yet linked to any PR
linked:issue          # PR is linked to an issue

Numeric Filters

comments:>10          # More than 10 comments
comments:0            # No comments
interactions:>100     # Reactions + comments > 100
reactions:>50         # More than 50 reactions

Boolean Logic & Nesting

Use AND, OR, and parentheses (up to 5 levels deep, max 5 operators):

label:bug AND assignee:octocat
assignee:octocat OR assignee:hubot
(type:"Bug" AND label:P1) OR (type:"Feature" AND label:P1)
-author:app/dependabot          # Exclude bot issues

A space between terms without an explicit operator is treated as AND.

Common Query Patterns

Unassigned bugs:

repo:owner/repo type:"Bug" no:assignee is:open

Issues closed this week:

repo:owner/repo is:closed closed:>=2026-03-01

Stale open issues (no updates in 90 days):

repo:owner/repo is:open updated:<2026-01-01

Open issues without a linked PR (needs work):

repo:owner/repo is:open -linked:pr

Issues I'm involved in across an org:

org:github involves:@me is:open

High-activity issues:

repo:owner/repo is:open comments:>20

Issues by type and priority label:

repo:owner/repo type:"Epic" label:P1 is:open

Issue Field Search

Reliability warning: The field.name:value search qualifier syntax is experimental and may return 0 results even when matching issues exist. For reliable filtering by field values, use the GraphQL bulk query approach documented in issue-fields.md.

Issue fields can theoretically be searched via the field.name:value qualifier using advanced search mode. This works in the web UI but results from the API are inconsistent.

REST API

Add advanced_search=true as a query parameter:

gh api "search/issues?q=org:github+field.priority:P0+type:Epic+is:open&advanced_search=true" \
  --jq '.items[] | "#\(.number): \(.title)"'

GraphQL

Use type: ISSUE_ADVANCED instead of type: ISSUE:

{
  search(query: "org:github field.priority:P0 type:Epic is:open", type: ISSUE_ADVANCED, first: 10) {
    issueCount
    nodes {
      ... on Issue { number title }
    }
  }
}

Issue Field Qualifiers

The syntax uses dot notation with the field's slug name (lowercase, hyphens for spaces):

field.priority:P0                  # Single-select field equals value
field.priority:P1                  # Different option value
field.target-date:>=2026-04-01     # Date comparison
has:field.priority                 # Has any value set
no:field.priority                  # Has no value set

MCP limitation: The search_issues MCP tool does not pass advanced_search=true. You must use gh api directly for issue field searches.

Common Field Search Patterns

P0 epics across an org:

org:github field.priority:P0 type:Epic is:open

Issues with a target date this quarter:

org:github field.target-date:>=2026-04-01 field.target-date:<=2026-06-30 is:open

Open bugs missing priority:

org:github no:field.priority type:Bug is:open

Limitations

Query text: max 256 characters (excluding operators/qualifiers)
Boolean operators: max 5 AND/OR/NOT per query
Results: max 1,000 total (use list_issues if you need all issues)
Repo scan: searches up to 4,000 matching repositories
Rate limit: 30 requests/minute for authenticated search
Issue field search requires advanced_search=true (REST) or ISSUE_ADVANCED (GraphQL); not available through MCP search_issues

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an MCP server, Needs a command-line tool

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Contributed by

@tgrall via pull request #550

Publisher

GitHub (Official)

Distributed by

GitHub

Source

github/awesome-copilot · skills/github-issues · commit 797337f

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

Contributors

alx-so, devantler, labudis, m2moiz

AutoGineer is not affiliated with or endorsed by tgrall or GitHub.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download github-issues.zip