Github

GitHub Issues Manager

Complete GitHub issue management using the gh CLI tool. This Skill provides comprehensive capabilities for creating, viewing, updating, and managing GitHub issues.

Capabilities

1. Create issues - Create new GitHub issues with context from conversations 2. List issues - View and filter issues by state, labels, assignees 3. View issues - Display full issue details including comments 4. Update issues - Modify titles, bodies, labels, and assignees 5. Close issues - Close issues with optional closing comments 6. Assign issues - Assign issues to team members

Quick Reference

For detailed instructions on each operation, see:

• CREATE_ISSUE.md - Creating new issues
• LIST_ISSUES.md - Listing and filtering issues
• VIEW_ISSUE.md - Viewing issue details
• UPDATE_ISSUE.md - Updating existing issues
• CLOSE_ISSUE.md - Closing issues
• ASSIGN_ISSUE.md - Assigning issues to users

Common Workflows

Bug reporting workflow

1. User reports a bug in conversation 2. Create issue with /create-issue or ask me to create one 3. Issue is created with context from our discussion 4. Assign to appropriate team member 5. Add labels (bug, priority, etc.)

Issue triage workflow

1. List open issues with filters 2. View specific issues for details 3. Update labels and assignments 4. Close resolved issues with status updates

Sprint planning workflow

1. List issues by label or milestone 2. Assign issues to team members 3. Update priorities and estimates 4. Track progress through status updates

Critical Instructions

REQUIRED: Before executing ANY GitHub issue operations, you MUST load the relevant reference file(s) using the Read tool. These references contain essential command patterns, parameters, and workflows that are NOT included in this overview.

When the user asks to work with GitHub issues:

1. Identify the operation they want to perform (create, list, view, update, close, assign) 2. MANDATORY: Load the relevant reference file(s) using the Read tool BEFORE executing any commands:

• Creating issues → Read CREATE_ISSUE.md FIRST
• Listing issues → Read LIST_ISSUES.md FIRST
• Viewing issues → Read VIEW_ISSUE.md FIRST
• Updating issues → Read UPDATE_ISSUE.md FIRST
• Closing issues → Read CLOSE_ISSUE.md FIRST
• Assigning issues → Read ASSIGN_ISSUE.md FIRST

3. Execute the gh CLI commands following the exact patterns from the loaded reference 4. Use temporary files for issue bodies to avoid markdown conflicts (as specified in references) 5. Confirm actions and display results

DO NOT attempt to execute GitHub issue commands without first loading and reading the relevant reference documentation.

Best Practices

• Always use `--body-file` for issue bodies to avoid shell escaping issues
• Use `$$` in temp file names to avoid conflicts (expands to process ID)
• Format issue bodies with proper markdown structure
• Include context from conversations when creating issues
• Clean up temp files after operations
• Display issue URLs so users can navigate to GitHub

Examples

Create an issue from context

User: "I found a bug where login fails with special characters"
Me: *Creates issue with details from conversation*

List and filter issues

User: "Show me all open bugs assigned to alice"
Me: gh issue list --state open --label bug --assignee alice

Update an issue

User: "Add high-priority label to issue #123"
Me: gh issue edit 123 --add-label "high-priority"

Close with context

User: "Close issue #456, it was fixed in the last PR"
Me: gh issue close 456 --comment "Fixed in PR #789"

Assign GitHub Issue

Assign a GitHub issue to one or more team members, or assign it to yourself.

Instructions

1. Get the issue number and assignee:

• The user should provide the issue number
• The user should provide the username (or "me" for self-assignment)
• If not provided, ask the user

2. Determine the assignee:

• If "me" or "@me", assign to the current user
• Otherwise, use the provided username(s)
• Multiple usernames can be provided

3. Perform the assignment (see examples below)

4. Confirm the assignment:

• Display a message confirming who was assigned
• Optionally show the updated issue with gh issue view [number]

Assignment Examples

Assign to yourself

gh issue edit 123 --add-assignee "@me"

Assign to specific user

gh issue edit 123 --add-assignee "username"

Assign to multiple users

gh issue edit 123 --add-assignee "user1,user2,user3"

Remove assignee

# Remove specific user
gh issue edit 123 --remove-assignee "username"

Remove all assignees

gh issue edit 123 --remove-assignee "*"

Replace assignee

# Remove old assignee and add new one
gh issue edit 123 --remove-assignee "olduser" --add-assignee "newuser"

Common Assignment Patterns

Take ownership of an issue

gh issue edit 123 --add-assignee "@me"

Reassign to another team member

gh issue edit 123 --remove-assignee "@me" --add-assignee "teammate"

Assign to team lead for review

gh issue edit 123 --add-assignee "team-lead"
gh issue comment 123 --body "Ready for review @team-lead"

Distribute work across team

# Assign frontend work
gh issue edit 123 --add-assignee "frontend-dev"

# Assign backend work
gh issue edit 456 --add-assignee "backend-dev"

# Assign design work
gh issue edit 789 --add-assignee "designer"

Query Assigned Issues

View issues assigned to you

gh issue list --assignee "@me"

View issues assigned to specific user

gh issue list --assignee "username"

View unassigned issues

gh issue list --assignee ""

View issues by state and assignee

# Open issues assigned to you
gh issue list --state open --assignee "@me"

# All issues (open and closed) assigned to user
gh issue list --state all --assignee "username"

Important Notes

• Use @me to assign to yourself without knowing your username
• Multiple assignees are comma-separated (no spaces)
• Use * to remove all assignees
• Not all repositories allow multiple assignees (depends on GitHub plan)
• Assignees must have read access to the repository

Best Practices

1. Assign early: Assign issues when starting work to avoid duplicates 2. Communicate: Add a comment when assigning to someone else 3. Check capacity: Don't overload team members with assignments 4. Use yourself: Assign to yourself when taking ownership 5. Update status: Combine assignment with label updates (e.g., "in-progress")

Assignment Workflow Example

Starting work on an issue

# 1. Assign to yourself
gh issue edit 123 --add-assignee "@me"

# 2. Update status label
gh issue edit 123 --add-label "in-progress"

# 3. Add comment
gh issue comment 123 --body "Starting work on this issue"

Requesting help

# 1. Add additional assignee
gh issue edit 123 --add-assignee "helper"

# 2. Add comment explaining what help is needed
gh issue comment 123 --body "@helper Could you help with the database schema changes?"

Handing off work

# 1. Remove yourself and add new person
gh issue edit 123 --remove-assignee "@me" --add-assignee "teammate"

# 2. Add comment with context
gh issue comment 123 --body "$(cat <<'EOF'
@teammate Handing this off to you.

## Context
- Database migrations are complete
- API endpoints need implementation
- Tests are in progress

Let me know if you need any clarification!
EOF
)"

Close GitHub Issue

Close a GitHub issue, optionally adding a final comment explaining the resolution.

Instructions

1. Get the issue number:

• The user should provide the issue number
• If not provided, ask the user

2. Determine if a comment should be added:

• If the user provides a reason, use it as the closing comment
• If there's context from the conversation, create a brief closing comment
• Otherwise, close without a comment

3. Close the issue (see examples below)

4. Confirm the closure:

• Display a message confirming the issue was closed
• Show the issue number and final state
• Optionally run gh issue view [number] to show the closed issue

Close Examples

Close with comment

gh issue close 123 --comment "Fixed in PR #456"

Close with detailed explanation

gh issue close 123 --comment "$(cat <<'EOF'
## Resolution
This issue has been resolved.

**Fix**: Implemented proper validation for special characters
**Tested**: All edge cases now pass
**PR**: #456
EOF
)"

Close as not planned

# Use this when the issue won't be worked on
gh issue close 123 --reason "not planned" --comment "This is out of scope for the current roadmap"

Close as completed (default)

# Default reason is "completed"
gh issue close 123 --comment "Issue resolved"

Simple close without comment

gh issue close 123

Close Reasons

GitHub supports two close reasons:

• completed (default): The issue was resolved/fixed
• not planned: The issue won't be worked on

When to use "not planned"

# Duplicate issue
gh issue close 123 --reason "not planned" --comment "Duplicate of #456"

# Out of scope
gh issue close 123 --reason "not planned" --comment "Out of scope for this project"

# Won't fix
gh issue close 123 --reason "not planned" --comment "This behavior is intentional"

# Cannot reproduce
gh issue close 123 --reason "not planned" --comment "Cannot reproduce. Please reopen with more details if this persists"

Common Closing Patterns

Fixed in PR

gh issue close 123 --comment "Fixed in PR #789"

Fixed in commit

gh issue close 123 --comment "Fixed in commit abc123"

Duplicate

gh issue close 123 --reason "not planned" --comment "Duplicate of #456"

Cannot reproduce

gh issue close 123 --reason "not planned" --comment "Cannot reproduce this issue. Please reopen with additional details if it persists."

Working as intended

gh issue close 123 --reason "not planned" --comment "This is working as designed. See documentation for details."

Completed as requested

gh issue close 123 --comment "Completed as requested. Feature is now available in v2.0"

Important Notes

• Always provide context in the closing comment
• Reference PRs or commits that fixed the issue
• Use "not planned" for issues that won't be fixed
• Be clear and helpful in closing comments
• Consider adding relevant labels before closing (e.g., "wontfix", "duplicate")

Best Practices

1. Be specific: Explain what was done or why it's closing 2. Reference work: Link to PRs, commits, or related issues 3. Be helpful: Provide next steps or alternatives if applicable 4. Update labels: Add appropriate labels before closing 5. Thank contributors: Acknowledge community contributions

Create GitHub Issue from Context

You need to create a GitHub issue using the gh CLI tool. Follow these steps:

Variables

{ TMPDIR: $TMPDIR, TIMESTAMP: $TIMESTAMP } = $node -p "JSON.stringify({TMPDIR: require('os').tmpdir(), TIMESTAMP: new Date().toISOString().replace(/[:.]/g, '-')})"

Example

Use the "Write" tool to write the body to a temp file $TMPDIR/gh_issue_body_$TIMESTAMP.md <template>

Summary

Login fails when username contains special characters like @, #, or spaces.

Context

User reported authentication errors during testing. The issue occurs consistently with usernames containing special characters.

Details

Error message: "Invalid username format" Affected usernames: user@domain, user#123, "user name"

Acceptance Criteria

• [ ] Special characters are properly escaped
• [ ] All valid email formats work as usernames
• [ ] Tests added for edge cases

</template>

List the Available Labels using the gh CLI tool

gh label list

Create the issue using the gh CLI tool

gh issue create --title "Fix login with special characters in username" --body-file $TMPDIR/gh_issue_body_$TIMESTAMP.md

Avoid Cleaning Up Temporary Files

Don't attempt to rm the temporary file.

List GitHub Issues

List and filter GitHub issues from the current repository using the gh CLI.

Instructions

1. Determine the filter:

• Common filters:
• open - Show open issues (default)
• closed - Show closed issues
• all - Show all issues
• assigned - Show issues assigned to you
• created - Show issues created by you
• mentioned - Show issues where you're mentioned
• label:bug - Show issues with specific label
• assignee:username - Show issues assigned to specific user
• If no filter specified, default to showing open issues

2. Fetch and display issues:

• Run: gh issue list --state [filter] or appropriate filter command
• Use --limit 20 to show first 20 issues
• Format output with: --json number,title,state,labels,assignees,createdAt

3. Display results:

• Show a formatted list of issues
• Include issue number, state, title, and labels
• Provide guidance on using view-issue for details

Example Commands

List open issues

gh issue list --state open --limit 20

List all issues

gh issue list --state all --limit 20

List by label

gh issue list --label bug --limit 20
gh issue list --label "high-priority" --limit 20

List assigned to specific user

gh issue list --assignee username --limit 20
gh issue list --assignee "@me" --limit 20

List with detailed JSON output

gh issue list --state open --limit 20 --json number,title,state,labels,assignees,createdAt

Combine filters

gh issue list --state open --label bug --assignee "@me" --limit 10

Output Format

The default output shows:

• Issue number (e.g., #123)
• Issue state (OPEN, CLOSED)
• Issue title
• Labels (if any)
• Time information

Tips

• Use --limit N to control how many issues are shown (default is 30)
• Use --json for structured output that can be parsed
• Combine multiple filters to narrow down results
• Use --assignee "@me" to see your assigned issues
• Use --author username to see issues created by specific user

Update GitHub Issue

Modify an existing GitHub issue's title, body, labels, assignees, or other attributes.

Instructions

1. Identify the issue:

• Get the issue number from the user
• If not provided, ask which issue to update

2. Determine the update type: Ask the user or infer from context what needs updating:

• Title: New title for the issue
• Body: Updated description
• Labels: Add or remove labels
• Assignees: Add or remove assignees
• Milestone: Set milestone
• Comment: Add a comment to the issue

3. Perform the appropriate update (see examples below)

4. Confirm the update:

• Run gh issue view [number] to show the updated issue
• Display what was changed

Update Examples

Update title

gh issue edit 123 --title "New Issue Title"

Update body (using temporary file)

# Create temp file with new body
cat > /tmp/gh_issue_update_$$.md <<'EOF'
## Updated Summary
New description of the issue...

## Additional Details
More context and information...
EOF

gh issue edit 123 --body-file /tmp/gh_issue_update_$$.md
rm /tmp/gh_issue_update_$$.md

Add labels

# Add single label
gh issue edit 123 --add-label "bug"

# Add multiple labels
gh issue edit 123 --add-label "bug,high-priority,needs-review"

Remove labels

# Remove single label
gh issue edit 123 --remove-label "wontfix"

# Remove multiple labels
gh issue edit 123 --remove-label "duplicate,invalid"

Add assignees

# Assign to yourself
gh issue edit 123 --add-assignee "@me"

# Assign to specific user
gh issue edit 123 --add-assignee "username"

# Assign to multiple users
gh issue edit 123 --add-assignee "user1,user2"

Remove assignees

# Remove specific assignee
gh issue edit 123 --remove-assignee "username"

# Remove all assignees
gh issue edit 123 --remove-assignee "*"

Set milestone

gh issue edit 123 --milestone "v2.0"

Add a comment

# Simple comment
gh issue comment 123 --body "This is a comment"

# Multi-line comment with heredoc
gh issue comment 123 --body "$(cat <<'EOF'
## Status Update
Work is in progress.

Expected completion: Next week
EOF
)"

Combine multiple updates

gh issue edit 123 \
  --title "Updated Title" \
  --add-label "in-progress" \
  --add-assignee "@me"

Important Notes

• Use --body-file for body updates to avoid markdown conflicts
• Multiple labels/assignees can be comma-separated
• Use $$ in temp file names to avoid conflicts (expands to process ID)
• Clean up temporary files after updates
• Verify changes with gh issue view [number]

Common Update Patterns

Mark as in progress

gh issue edit 123 --add-label "in-progress" --add-assignee "@me"

Mark as blocked

gh issue edit 123 --add-label "blocked"
gh issue comment 123 --body "Blocked by: [reason]"

Request review

gh issue edit 123 --add-label "needs-review"
gh issue comment 123 --body "Ready for review @reviewer"

Update priority

gh issue edit 123 --remove-label "low-priority" --add-label "high-priority"

View GitHub Issue Details

Display the full details of a specific GitHub issue including description, comments, labels, and metadata.

Instructions

1. Get the issue number:

• The user should provide the issue number
• If not provided, ask the user for the issue number

2. Fetch issue details:

• Run: gh issue view [issue-number]
• This will display the full issue including:
• Title and body
• Issue number and state (open/closed)
• Author and creation date
• Labels and assignees
• All comments with timestamps

3. Display the information:

• Present the issue details in a readable format
• Highlight key information like current state, assignees, and labels
• If the issue has many comments, summarize the discussion

4. Suggest actions:

• Based on the issue content, suggest relevant actions:
• Update the issue if changes are needed
• Close the issue if it's resolved
• Assign the issue to someone if unassigned

Example Commands

View basic issue

gh issue view 123

View with web browser

gh issue view 123 --web

View with JSON output

gh issue view 123 --json title,body,state,labels,assignees,comments

View with comments

# Default view includes all comments
gh issue view 123

Output Includes

• Title: The issue title
• State: Open or closed status
• Author: Who created the issue
• Labels: All labels attached to the issue
• Assignees: Who the issue is assigned to
• Milestone: Associated milestone (if any)
• Body: The full issue description
• Comments: All comments in chronological order

Tips

• Use --web to open the issue in your browser
• Use --json to get structured data for parsing
• Review comments to understand the full context
• Check labels to understand issue categorization
• Look at assignees to see who's responsible