GitHub Issues

Full issue lifecycle — create, search, triage, label, assign, comment, close, and link to PRs. Structured steps so the user can interrupt at any point.

When to use this skill

• User wants to create, search, update, or close GitHub issues.
• Agent discovers a bug or improvement worth tracking during other work.
• User asks to triage a backlog of unlabeled or unassigned issues.

When NOT to use this skill

• PR reviews — use github-code-review instead.
• Opening or merging PRs — use github-pr-workflow instead.
• Repository administration (branch protection, secrets, releases) — use github-repo-management instead.

Preflight

Before any issue operation:

gh auth status          # must succeed
gh repo view --json nameWithOwner -q '.nameWithOwner'  # confirm target repo

If gh is not installed, stop and point the user to cli.github.com.

Quick reference

Use gh first. Fall back to gh api (which handles auth headers automatically) only when gh issue subcommands lack a needed option.

Creating issues

# Simple
gh issue create --title "Widget fails on empty input" --body "Steps to reproduce..."

# With labels and assignee
gh issue create \
  --title "Add rate limiting to /api/v2" \
  --label "enhancement" --label "priority:high" \
  --assignee "@me" \
  --body-file plan.md

Searching issues

# Open bugs assigned to me
gh issue list --search "is:open label:bug assignee:@me"

# Issues mentioning a keyword
gh issue list --search "rate limit in:title,body"

# Issues in a milestone
gh issue list --milestone "v2.0"

# JSON output for scripting
gh issue list --search "is:open" --json number,title,labels --limit 100

Triage workflow

Structured sequence for processing an untriaged backlog:

1. List unlabeled issues

gh issue list --search "is:open no:label" --json number,title,body --limit 50

2. Categorize each issue

Read the title and body. Assign one of:

3. Set priority

4. Assign

gh issue edit 42 --add-label "bug" --add-label "priority:high" --add-assignee "username"

5. Comment with status

gh issue comment 42 --body "Triaged as high-priority bug. Assigned to @username. ETA: next sprint."

For issues needing more information:

gh issue comment 42 --body "Thanks for reporting. Could you provide:
- Steps to reproduce
- Expected vs actual behavior
- Environment (OS, version)

Marking as needs-info until we have repro steps."
gh issue edit 42 --add-label "needs-info"

Gotcha: issues endpoint returns PRs

The GitHub REST API's /repos/{owner}/{repo}/issues endpoint returns both issues and pull requests. PRs are technically issues with a pull_request field.

To filter correctly:

• gh CLI search: use is:issue in the search query — gh issue list --search "is:issue is:open"
• REST API: check that the pull_request field is absent in each response object
• GraphQL: use the Issues connection, not IssuesAndPullRequests

The gh issue list command filters this automatically. The gotcha only bites when using gh api directly.

Bulk operations

Batch labeling

# Label all issues matching a search
gh issue list --search "is:open websocket in:title" --json number -q '.[].number' | \
  xargs -I{} gh issue edit {} --add-label "component:websocket"

Close stale issues

List the issues with no activity in 90 days (<cutoff-date> is today minus 90 days, YYYY-MM-DD):

gh issue list --search "is:open updated:<<cutoff-date>" --json number -q '.[].number'

Then, for each number it prints:

gh issue comment <number> --body "Closing due to inactivity. Reopen if still relevant."
gh issue close <number>

Transfer issues

gh issue transfer 42 owner/other-repo

Issue templates

Bug report

```markdown
## Bug report

**Describe the bug**
A clear and concise description.

**Steps to reproduce**
1. Go to '...'
2. Click on '...'
3. See error

**Expected behavior**
What you expected to happen.

**Actual behavior**
What actually happened. Include error messages or stack traces.

**Environment**
- OS: [e.g. macOS 15.1]
- Node: [e.g. 24.0]
- Version: [e.g. 1.2.3]
```

Feature request

```markdown
## Feature request

**Problem**
What problem does this solve? Who is affected?

**Proposed solution**
How should it work? Be specific.

**Alternatives considered**
What else did you consider and why did you reject it?

**Additional context**
Links, screenshots, prior art.
```

Issue → PR linking

Option 1: gh issue develop

Creates a branch linked to the issue and optionally opens a PR:

# Create a branch for issue 42
gh issue develop 42 --base main --name fix-widget-empty-input

# Create branch + checkout
gh issue develop 42 --base main --checkout

Option 2: Keywords in PR body

Include one of these keywords in the PR title or body to auto-close the issue when the PR merges:

• Fixes #42
• Closes #42
• Resolves #42

For cross-repo linking: Fixes owner/repo#42.

Multiple issues: Fixes #42, fixes #43.

Option 3: Manual linking

# Add a comment cross-referencing the PR
gh issue comment 42 --body "Fix submitted in #87."

Hard rules

• Never close an issue without a comment explaining why (fix merged, duplicate, won't fix, stale).
• Never bulk-close without user confirmation. Print the list first, ask, then proceed.
• Prefer gh CLI over raw API calls. Only use gh api when gh issue subcommands lack the needed option.

Setup the user needs to do once

1. Install gh: per cli.github.com.
2. Authenticate: gh auth login. Follow the browser flow.
3. Verify: gh auth status should print "Logged in to github.com as ...".

Adapted from NousResearch/hermes-agent (MIT)