GitHub Issue Management Skill

This skill provides comprehensive issue management operations including creating, listing, updating, and commenting on GitHub issues.

Available Operations

1. Create Issue

Create a new issue in a repository with title, body, labels, and assignees.

2. List Issues

List issues with various filters (state, labels, assignee, etc.).

3. Get Issue

Retrieve details of a specific issue.

4. Update Issue

Update issue properties like title, body, state, labels, or assignees.

5. Add Comment

Add a comment to an existing issue.

6. Search Issues

Search for issues across repositories.

Usage Examples

Create a New Issue

Basic issue:

gh issue create --repo owner/repo-name --title "Bug: Login not working" --body "Users cannot log in with valid credentials"

Issue with labels:

gh issue create --repo owner/repo-name \
  --title "Feature: Add dark mode" \
  --body "Add dark mode support to the application" \
  --label "enhancement" \
  --label "ui"

Issue with assignee:

gh issue create --repo owner/repo-name \
  --title "Fix memory leak" \
  --body "Memory usage increases over time" \
  --label "bug" \
  --assignee username

Interactive mode:

gh issue create --repo owner/repo-name
# Follow the prompts to enter title and body

From template:

gh issue create --repo owner/repo-name --template bug_report.md

List Issues

List all open issues:

gh issue list --repo owner/repo-name

List all issues (including closed):

gh issue list --repo owner/repo-name --state all

Filter by label:

gh issue list --repo owner/repo-name --label bug

Multiple labels (AND):

gh issue list --repo owner/repo-name --label bug --label critical

Filter by assignee:

gh issue list --repo owner/repo-name --assignee username

Filter by author:

gh issue list --repo owner/repo-name --author username

Limit results:

gh issue list --repo owner/repo-name --limit 50

Custom output format:

gh issue list --repo owner/repo-name --json number,title,state,labels --jq '.[] | "\(.number): \(.title)"'

Get Issue Details

View issue in terminal:

gh issue view 123 --repo owner/repo-name

View with comments:

gh issue view 123 --repo owner/repo-name --comments

View in browser:

gh issue view 123 --repo owner/repo-name --web

JSON output:

gh issue view 123 --repo owner/repo-name --json number,title,body,state,labels,assignees,createdAt

Update an Issue

Change issue state to closed:

gh issue close 123 --repo owner/repo-name

Close with comment:

gh issue close 123 --repo owner/repo-name --comment "Fixed in PR #456"

Reopen issue:

gh issue reopen 123 --repo owner/repo-name

Edit issue title and body:

gh issue edit 123 --repo owner/repo-name \
  --title "Updated title" \
  --body "Updated description"

Add labels:

gh issue edit 123 --repo owner/repo-name --add-label "needs-triage"

Remove labels:

gh issue edit 123 --repo owner/repo-name --remove-label "needs-triage"

Add assignees:

gh issue edit 123 --repo owner/repo-name --add-assignee user1,user2

Remove assignees:

gh issue edit 123 --repo owner/repo-name --remove-assignee user1

Interactive edit:

gh issue edit 123 --repo owner/repo-name

Add Comment to Issue

Add simple comment:

gh issue comment 123 --repo owner/repo-name --body "This is my comment"

Add multi-line comment:

gh issue comment 123 --repo owner/repo-name --body "First line
Second line
Third line"

Comment from file:

gh issue comment 123 --repo owner/repo-name --body-file comment.md

Interactive comment:

gh issue comment 123 --repo owner/repo-name
# Opens editor for comment

Search Issues

Search across all repositories:

gh search issues "memory leak" --limit 20

Search in specific repository:

gh search issues "bug" --repo owner/repo-name

Search with filters:

gh search issues "crash" --label bug --state open --limit 10

Search by author:

gh search issues "feature" --author username

Search by date:

gh search issues "security" --created ">2025-01-01"

Search in organization:

gh search issues "todo" --owner myorg

Complex query:

gh search issues "is:open label:bug assignee:username"

Common Patterns

Triage Workflow

# List new untriaged issues
gh issue list --repo owner/repo-name --label "needs-triage" --state open

# Review an issue
gh issue view 123 --repo owner/repo-name

# Add labels and assign
gh issue edit 123 --repo owner/repo-name \
  --add-label "bug" \
  --add-label "high-priority" \
  --remove-label "needs-triage" \
  --add-assignee developer1

# Add triage comment
gh issue comment 123 --repo owner/repo-name --body "Confirmed bug. High priority for next sprint."

Bug Report Processing

# Create bug from template
gh issue create --repo owner/repo-name \
  --title "Bug: API returns 500 error" \
  --body "$(cat bug-details.md)" \
  --label "bug" \
  --label "api"

# Get issue number from output, e.g., #456

# Link to related issue
gh issue comment 456 --repo owner/repo-name --body "Related to #123"

# Update when fixed
gh issue close 456 --repo owner/repo-name --comment "Fixed in commit abc123"

Bulk Operations

Close multiple stale issues:

# List stale issues
gh issue list --repo owner/repo-name --label "stale" --state open --json number --jq '.[].number' > stale_issues.txt

# Close each one
while read issue_num; do
  gh issue close $issue_num --repo owner/repo-name --comment "Closing stale issue"
done < stale_issues.txt

Add label to multiple issues:

for issue in 101 102 103 104; do
  gh issue edit $issue --repo owner/repo-name --add-label "sprint-3"
done

Issue Templates

Create from bug template:

gh issue create --repo owner/repo-name --template bug_report.md --web

Create from feature template:

gh issue create --repo owner/repo-name --template feature_request.md --web

Error Handling

Issue Not Found

# Check if issue exists
gh issue view 123 --repo owner/repo-name 2>&1 | grep -q "could not find" && echo "Issue not found"

Invalid Label

# List available labels first
gh label list --repo owner/repo-name

# Then create issue with valid label
gh issue create --repo owner/repo-name --title "Test" --body "Test" --label "valid-label"

Permission Denied

# Check repository access
gh auth status

# Verify you have write access
gh api repos/owner/repo-name --jq '.permissions'

Best Practices

1. Use descriptive titles: Make titles clear and searchable
2. Add relevant labels: Use labels for categorization and filtering
3. Assign appropriately: Only assign when someone is actively working on it
4. Link related issues: Reference related issues with #123 syntax
5. Close with context: Always add a comment when closing issues
6. Use templates: Create issue templates for consistency
7. Regular triage: Review and label new issues regularly
8. Track progress: Use project boards or milestones to track issue progress

Issue State Transitions

[Open] -> [Closed]                    # gh issue close
[Closed] -> [Open]                    # gh issue reopen
[Open] -> [In Progress]               # Add label/project card
[In Progress] -> [Closed]             # Complete work and close

Integration with Other Skills

• Use

  repository-management

  to create repos before creating issues
• Use

  pull-request-management

  to link PRs that fix issues
• Use

  search-operations

  for advanced cross-repository issue searches
• Use

  commit-operations

  to reference commits that address issues

References

• GitHub CLI Issue Documentation
• GitHub Issues Guide
• Issue Search Syntax