issues by shpigford/skills

Interact with GitHub issues - create, list, and view issues.

Instructions

This command helps you work with GitHub issues using the gh CLI.

Step 1: Determine Action

Use AskUserQuestion to ask what the user wants to do:

Question:

question: "What would you like to do with GitHub issues?"
header: "Action"
multiSelect: false
options:
- label: "Create new issue" description: "Open a new issue with title, body, and optional labels"
- label: "List issues" description: "View open issues in the current repository"
- label: "View issue" description: "See details of a specific issue by number"

If "Create new issue" selected:

Step 2a: Get Issue Title

Use AskUserQuestion to get the issue title:

Question:

question: "What's a short, scannable title for this issue? Keep it brief (5-10 words max) - details go in the body. (Use 'Other' to type your title)"
header: "Title"
multiSelect: false
options:
- label: "I'll type a title" description: "Enter a concise title like 'Login button unresponsive' or 'Add dark mode support'"

Title guidelines:

Keep titles SHORT and scannable (5-10 words max)
Good: "Fix broken password reset flow"
Bad: "When I try to reset my password and click the button nothing happens and I get an error"
The description/body is where details belong, not the title

If the user provides a long title, help them shorten it and move the details to the body.

Step 3a: Get Issue Body

Use AskUserQuestion to gather the issue body content:

Question 1 - Issue type context:

question: "What type of issue is this?"
header: "Type"
multiSelect: false
options:
- label: "Bug" description: "Something broken that needs fixing"
- label: "Enhancement" description: "Improvement to existing functionality"
- label: "New feature" description: "Brand new functionality"
- label: "Task" description: "General work item or chore"

Question 2 - Description:

question: "Now provide the full details. This is where you explain context, background, and specifics that didn't fit in the title. (Use 'Other' to type your description)"
header: "Description"
multiSelect: false
options:
- label: "I'll describe it in detail" description: "Provide context, steps, examples, and any relevant information"

The user will select "Other" here to provide their full description.

Description guidelines:

This is where ALL the detail goes - be thorough
Include context: what were you doing, what's the background?
Include specifics: error messages, URLs, versions, etc.
The more detail here, the better - unlike the title which should be brief

Question 3 - For bugs, ask about reproduction: If issue type is "Bug", use AskUserQuestion:

question: "Can you provide steps to reproduce this bug? (Use 'Other' to type steps)"
header: "Repro steps"
multiSelect: false
options:
- label: "Provide steps" description: "I'll describe how to reproduce the issue"
- label: "Not reproducible" description: "The bug is intermittent or hard to reproduce"

Question 4 - Expected vs actual behavior (for bugs): If issue type is "Bug", use AskUserQuestion:

question: "What did you expect to happen vs what actually happened? (Use 'Other' to describe)"
header: "Behavior"
multiSelect: false
options:
- label: "Describe behavior" description: "I'll explain expected vs actual behavior"

Step 4a: Get Labels (Optional)

Use AskUserQuestion to select labels:

question: "Which labels should we add? (if any)"
header: "Labels"
multiSelect: true
options:
- label: "bug" description: "Something isn't working"
- label: "enhancement" description: "New feature or request"
- label: "documentation" description: "Improvements to docs"
- label: "good first issue" description: "Good for newcomers"

Step 5a: Create the Issue

Construct the issue body based on the type:

For Bug reports:

## Description
[User's description]

## Steps to Reproduce
[User's reproduction steps or "Not easily reproducible"]

## Expected Behavior
[What should happen]

## Actual Behavior
[What actually happens]

For Feature requests/Enhancements:

## Description
[User's description]

## Use Case
[Why this would be useful]

For Tasks/Other:

## Description
[User's description]

Run the gh command to create the issue:

gh issue create --title "[title]" --body "[constructed body]" --label "[labels]"

Report the issue URL back to the user.

If "List issues" selected:

Step 2b: Filter Options

Use AskUserQuestion to determine filtering:

question: "How would you like to filter issues?"
header: "Filter"
multiSelect: false
options:
- label: "All open issues" description: "Show all open issues"
- label: "Assigned to me" description: "Issues assigned to the current user"
- label: "Created by me" description: "Issues I created"
- label: "With specific label" description: "Filter by a label"

If "With specific label" selected, use AskUserQuestion:

question: "Which label to filter by? (Use 'Other' for custom label)"
header: "Label"
multiSelect: false
options:
- label: "bug" description: "Bug reports"
- label: "enhancement" description: "Feature requests"
- label: "documentation" description: "Documentation issues"

Step 3b: List Issues

Run the appropriate gh command:

All open: gh issue list
Assigned to me: gh issue list --assignee @me
Created by me: gh issue list --author @me
With label: gh issue list --label "[label]"

Display the results in a clean format.

If "View issue" selected:

Step 2c: Get Issue Number

Use AskUserQuestion:

question: "Which issue number would you like to view? (Use 'Other' to enter the number)"
header: "Issue #"
multiSelect: false
options:
- label: "Enter issue number" description: "I'll type the issue number"

Step 3c: View Issue

Run: gh issue view [number]

Display the issue details including title, body, labels, assignees, and comments.

Error Handling

If gh command fails:

Check if user is authenticated: gh auth status
If not authenticated, inform user to run gh auth login
Check if in a git repository with a GitHub remote
Report specific error message to user

Important Notes

Titles should be succinct (5-10 words) - if a user provides a long title, help shorten it and move details to body
Bodies should be detailed - encourage users to provide thorough context, steps, and specifics
Always confirm the issue was created successfully by showing the URL
For issue bodies, preserve user's formatting and newlines
If the user provides minimal information, that's okay - create the issue with what they gave

Use HEREDOC for the body to preserve formatting:

gh issue create --title "Title" --body "$(cat <<'EOF'
Body content here
EOF
)"