name: issue-management description: Work with GitHub issues - create, list, update, comment, and search issues using gh CLI

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