github-issues

Original source / Raw SKILL.md

---
name: github-issues
description: Query and search GitHub issues using gh CLI with web fallback. Supports filtering by labels, state, assignees, and full-text search. Use when troubleshooting errors, checking if an issue is already reported, or finding workarounds.
allowed-tools: Bash, Read, Glob, Grep, WebFetch, WebSearch
---

# GitHub Issues Lookup

Query and search GitHub issues for troubleshooting, bug tracking, and finding workarounds. Supports `gh` CLI with automatic web fallback.

## Overview

This skill provides comprehensive guidance for querying GitHub issues from any repository. It prioritizes the GitHub CLI (`gh`) for fast, reliable access with automatic fallback to web-based methods when gh is unavailable.

**Core value:** Quickly find relevant issues when troubleshooting errors, checking if bugs are already reported, or discovering workarounds for known problems.

## When to Use This Skill

This skill should be used when:

- **Troubleshooting errors** - Search for issues matching error messages or symptoms
- **Checking if issue exists** - Before reporting a bug, search for duplicates
- **Finding workarounds** - Discover solutions from issue discussions
- **Tracking features** - Search for feature requests and their status
- **Understanding history** - Find closed issues explaining past decisions

**Trigger keywords:** github issues, search issues, find issue, bug report, issue lookup, gh issue, troubleshoot, workaround, known issue

## Prerequisites

**Recommended (not required):**

- **GitHub CLI (gh)** - Install from <https://cli.github.com/>
- **Authentication** - Run `gh auth login` for private repos

The skill works without `gh` by falling back to web-based methods.

## Quick Start

### Search Issues (gh CLI)

```bash
# Check if gh is available
gh --version

# Search for issues by keyword
gh issue list --repo owner/repo --search "keyword" --state all

# Filter by label
gh issue list --repo owner/repo --label "bug" --state open

# View specific issue
gh issue view 11984 --repo owner/repo

# Search with multiple terms
gh issue list --repo owner/repo --search "error message here" --limit 20
```

### Search Issues (Web Fallback)

When gh is unavailable, use WebSearch or WebFetch:

```text
# Search via web (using WebSearch tool)
Search: "site:github.com/owner/repo/issues keyword"

# Direct URL pattern
https://github.com/owner/repo/issues?q=keyword
```

## Core Capabilities

### 1. Basic Issue Search

Search issues by keywords, matching title and body text.

**gh CLI:**

```bash
# Basic keyword search (all states)
gh issue list --repo anthropics/claude-code --search "path doubling" --state all

# Open issues only
gh issue list --repo anthropics/claude-code --search "path doubling" --state open

# Closed issues only
gh issue list --repo anthropics/claude-code --search "path doubling" --state closed
```

**For detailed query syntax:** See [references/query-patterns.md](references/query-patterns.md)

---

### 2. Filter by Labels

Narrow results using repository labels.

```bash
# Single label
gh issue list --repo owner/repo --label "bug"

# Multiple labels (AND)
gh issue list --repo owner/repo --label "bug" --label "high-priority"

# Common label patterns
gh issue list --repo owner/repo --label "enhancement" --state open
gh issue list --repo owner/repo --label "documentation"
```

---

### 3. Filter by Assignee/Author

Find issues by who created or is assigned to them.

```bash
# By assignee
gh issue list --repo owner/repo --assignee username

# By author
gh issue list --repo owner/repo --author username

# Combined filters
gh issue list --repo owner/repo --author username --state closed
```

---

### 4. View Issue Details

Get full issue content including description and comments.

```bash
# View issue (opens in terminal)
gh issue view 11984 --repo anthropics/claude-code

# View with comments
gh issue view 11984 --repo anthropics/claude-code --comments

# JSON output for parsing
gh issue view 11984 --repo anthropics/claude-code --json title,body,comments
```

---

### 5. Web Fallback Strategy

When gh CLI is unavailable, fall back to web-based methods.

**Detection:**

```bash
# Check if gh is available
if command -v gh &> /dev/null; then
    echo "gh available"
else
    echo "falling back to web"
fi
```

**Web methods (in order of preference):**

1. **WebSearch tool**: `site:github.com/owner/repo/issues keyword`
2. **firecrawl MCP**: Scrape GitHub search results
3. **Direct URL**: `https://github.com/owner/repo/issues?q=keyword`

**For detailed fallback guidance:** See [references/web-fallback.md](references/web-fallback.md)

---

## Output Formats

The skill supports three output formats:

### Compact (default)

One line per issue, good for scanning:

```text
#11984 [open] Path doubling in PowerShell hooks (bug, hooks)
#11523 [closed] Fix memory leak in long sessions (bug, fixed)
#10892 [open] Add custom status line support (enhancement)
```

### Table

Markdown table format for structured display:

```markdown
| # | State | Title | Labels |
| --- | --- | --- | --- |
| 11984 | open | Path doubling in PowerShell hooks | bug, hooks |
| 11523 | closed | Fix memory leak in long sessions | bug, fixed |
```

### Detailed

Full information for deep investigation:

```markdown
### #11984 - Path doubling in PowerShell hooks
**State:** open | **Labels:** bug, hooks | **Created:** 2024-12-01
**URL:** https://github.com/anthropics/claude-code/issues/11984

When using cd && in PowerShell, paths get doubled...
```

---

## Common Workflows

### Troubleshooting an Error

1. Extract key terms from error message
2. Search issues with those terms
3. Check both open and closed issues
4. Look for workarounds in comments

```bash
# Example: Troubleshoot a specific error
gh issue list --repo anthropics/claude-code --search "ENOENT" --state all --limit 10
```

### Before Reporting a Bug

1. Search for existing issues with similar symptoms
2. Check closed issues for past fixes
3. If duplicate exists, add your context as a comment

```bash
# Search before reporting
gh issue list --repo owner/repo --search "feature not working" --state all
```

### Finding Workarounds

1. Search closed issues with your problem keywords
2. Look for issues with "workaround" or "solution" in body
3. Check issue comments for community solutions

```bash
# Find workarounds
gh issue list --repo owner/repo --search "workaround" --state closed --label "bug"
```

---

## Error Handling

### gh not installed

```text
Error: gh: command not found

Solution: Install GitHub CLI from https://cli.github.com/
  - macOS: brew install gh
  - Windows: winget install --id GitHub.cli
  - Linux: See https://github.com/cli/cli/blob/trunk/docs/install_linux.md

Alternatively, falling back to web-based search...
```

### Not authenticated

```text
Error: gh requires authentication

Solution: Run `gh auth login` and follow the prompts.
For public repos, web fallback can be used without authentication.
```

### Rate limited

```text
Error: API rate limit exceeded

Solution: Wait 60 seconds before retrying.
Authenticated requests have higher limits (5000/hour vs 60/hour).
```

### No results found

```text
No issues found matching "very specific query"

Suggestions:
- Try broader search terms
- Remove filters (state, label)
- Check spelling
- Search closed issues too (--state all)
```

---

## References

**Detailed Guides:**

- [references/gh-cli-guide.md](references/gh-cli-guide.md) - Installation, authentication, advanced usage
- [references/query-patterns.md](references/query-patterns.md) - Search syntax and filter examples
- [references/web-fallback.md](references/web-fallback.md) - Web-based fallback strategies

**Related Agents:**

- **history-reviewer** agent - Git history exploration and summarization

---

## Test Scenarios

### Scenario 1: Basic issue search

**Query:** "Search for issues about hooks in the Claude Code repo"

**Expected Behavior:**

- Skill activates on "issues", "hooks", "Claude Code"
- Checks if gh CLI is available
- Runs `gh issue list --repo anthropics/claude-code --search "hooks" --state all`
- Returns formatted results

### Scenario 2: Troubleshooting error

**Query:** "I'm getting a path doubling error in PowerShell. Is this a known issue?"

**Expected Behavior:**

- Skill activates on "error", "known issue", "PowerShell"
- Searches for related issues
- Finds #11984 and similar
- Provides workaround if available

### Scenario 3: Fallback to web

**Query:** "Search for issues but gh isn't installed"

**Expected Behavior:**

- Detects gh not available
- Falls back to WebSearch with `site:github.com/owner/repo/issues`
- Returns results in same format

## Version History

- **v1.0.0** (2025-12-26): Initial release

---

## Last Updated

**Date:** 2025-12-05
**Model:** claude-opus-4-5-20251101

**Audit Status:** NEW - Pending initial audit


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/query-patterns.md

```markdown
# Query Patterns and Filter Syntax

Comprehensive guide to GitHub issue search syntax and filtering options.

## Basic Search Syntax

### Keywords

Search matches title and body text:

```bash
# Single keyword
gh issue list --search "authentication"

# Multiple keywords (AND)
gh issue list --search "authentication error"

# Exact phrase
gh issue list --search '"exact phrase here"'
```

### Search Qualifiers

GitHub supports special qualifiers in search:

```bash
# By state
gh issue list --search "is:open"
gh issue list --search "is:closed"

# By label
gh issue list --search "label:bug"
gh issue list --search "label:\"help wanted\""

# By author
gh issue list --search "author:username"

# By assignee
gh issue list --search "assignee:username"

# By milestone
gh issue list --search "milestone:v1.0"
```

---

## Filter Flags

### State Filter

```bash
# Open only (default)
gh issue list --state open

# Closed only
gh issue list --state closed

# All states
gh issue list --state all
```

### Label Filter

```bash
# Single label
gh issue list --label "bug"

# Multiple labels (AND - must have ALL labels)
gh issue list --label "bug" --label "high-priority"

# Labels with spaces
gh issue list --label "help wanted"
```

### Assignee Filter

```bash
# Specific user
gh issue list --assignee username

# Self
gh issue list --assignee @me

# Unassigned
gh issue list --search "no:assignee"
```

### Author Filter

```bash
# Issues created by user
gh issue list --author username
```

### Milestone Filter

```bash
# Specific milestone
gh issue list --milestone "v1.0"

# No milestone
gh issue list --search "no:milestone"
```

---

## Combining Filters

### CLI Flags

```bash
# Label + state
gh issue list --label "bug" --state open

# Author + label + state
gh issue list --author username --label "bug" --state closed

# Assignee + label
gh issue list --assignee @me --label "high-priority"
```

### Search Qualifiers (More Flexible)

```bash
# Complex queries
gh issue list --search "is:open label:bug author:username"

# Excluding labels
gh issue list --search "is:open -label:wontfix"

# Multiple conditions
gh issue list --search "is:closed label:bug label:confirmed"
```

---

## Date Filters

Search by creation or update date:

```bash
# Created after date
gh issue list --search "created:>2024-01-01"

# Created before date
gh issue list --search "created:<2024-06-01"

# Created in range
gh issue list --search "created:2024-01-01..2024-06-01"

# Updated recently
gh issue list --search "updated:>2024-11-01"

# Closed after date
gh issue list --search "closed:>2024-01-01"
```

---

## Sort and Limit

### Limit Results

```bash
# Limit to 10 results
gh issue list --limit 10

# Limit to 50
gh issue list --limit 50

# Default is 30
```

### Sort Order

Sort is controlled via search qualifiers:

```bash
# Sort by created date (newest first)
gh issue list --search "sort:created-desc"

# Sort by created date (oldest first)
gh issue list --search "sort:created-asc"

# Sort by updated date
gh issue list --search "sort:updated-desc"

# Sort by comments count
gh issue list --search "sort:comments-desc"
```

---

## Common Query Patterns

### Find Bug Reports

```bash
gh issue list --repo owner/repo --label "bug" --state open
```

### Find Feature Requests

```bash
gh issue list --repo owner/repo --label "enhancement" --state open
```

### Find Issues Needing Help

```bash
gh issue list --repo owner/repo --label "help wanted"
```

### Find Recent Activity

```bash
gh issue list --repo owner/repo --search "updated:>2024-11-01" --state all
```

### Find Closed Fixed Bugs

```bash
gh issue list --repo owner/repo --label "bug" --state closed --limit 20
```

### Find Issues with Specific Error

```bash
gh issue list --repo owner/repo --search "ENOENT" --state all
gh issue list --repo owner/repo --search "TypeError" --state all
gh issue list --repo owner/repo --search "path doubling" --state all
```

---

## Output Customization

### JSON Fields

Available fields for `--json`:

```bash
# Common fields
gh issue list --json number,title,state,labels,createdAt

# Full list
gh issue list --json number,title,body,state,labels,assignees,author,comments,createdAt,updatedAt,closedAt,milestone,url
```

### Template Output

```bash
# Custom format
gh issue list --template '{{range .}}#{{.number}} [{{.state}}] {{.title}}{{"\n"}}{{end}}'

# With labels
gh issue list --template '{{range .}}#{{.number}} {{.title}} ({{range .labels}}{{.name}}, {{end}}){{"\n"}}{{end}}'
```

---

## Related Documentation

- [GitHub Search Syntax](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests)
- [gh issue list Reference](https://cli.github.com/manual/gh_issue_list)

```

### references/web-fallback.md

```markdown
# Web Fallback Strategies

When the GitHub CLI (gh) is unavailable, these fallback methods provide access to GitHub issues.

## Fallback Priority

1. **WebSearch tool** - Fast, works across public repos
2. **firecrawl MCP** - Better parsing of results
3. **Direct URL construction** - Manual but reliable
4. **GitHub API** - Programmatic but rate-limited

---

## Method 1: WebSearch Tool

Use Claude Code's WebSearch tool with site-specific queries:

```text
Query: site:github.com/owner/repo/issues keyword
```

### Examples

```text
# Search Claude Code issues for hooks
site:github.com/anthropics/claude-code/issues hooks

# Search for specific error
site:github.com/anthropics/claude-code/issues "path doubling"

# Include pull requests
site:github.com/anthropics/claude-code keyword
```

### Parsing Results

WebSearch returns search result snippets. Look for:

- Issue number in URL (e.g., `/issues/11984`)
- Title and description snippets
- State indicators (open, closed) if visible

---

## Method 2: firecrawl MCP

Use the firecrawl MCP server to scrape GitHub issue pages:

```text
URL: https://github.com/owner/repo/issues?q=keyword
```

### Example Usage

```javascript
// Scrape issue list page
mcp__firecrawl__firecrawl_scrape({
  url: "https://github.com/anthropics/claude-code/issues?q=hooks",
  formats: ["markdown"]
})
```

### Advantages

- Better structured output than WebSearch
- Can extract issue details more reliably
- Handles pagination

---

## Method 3: Direct URL Construction

Construct GitHub search URLs manually:

### Search URLs

```text
# Basic search
https://github.com/owner/repo/issues?q=keyword

# Filter by state
https://github.com/owner/repo/issues?q=keyword+is:open
https://github.com/owner/repo/issues?q=keyword+is:closed

# Filter by label
https://github.com/owner/repo/issues?q=keyword+label:bug

# Combined filters
https://github.com/owner/repo/issues?q=keyword+is:open+label:bug
```

### View Specific Issue

```text
https://github.com/owner/repo/issues/11984
```

Use WebFetch to retrieve content:

```text
WebFetch: https://github.com/anthropics/claude-code/issues/11984
Prompt: Extract issue title, state, labels, and description
```

---

## Method 4: GitHub API (Unauthenticated)

Direct API access with rate limits (60 requests/hour unauthenticated):

### API Endpoints

```text
# List issues
GET https://api.github.com/repos/owner/repo/issues

# Search issues
GET https://api.github.com/search/issues?q=keyword+repo:owner/repo

# Get specific issue
GET https://api.github.com/repos/owner/repo/issues/11984
```

### Using with WebFetch

```text
WebFetch: https://api.github.com/repos/anthropics/claude-code/issues?state=all&per_page=10
Prompt: Parse the JSON and list issues with number, title, and state
```

### Rate Limit Considerations

- Unauthenticated: 60 requests/hour
- Check limit: `curl -I https://api.github.com/rate_limit`
- Headers include remaining quota

---

## Fallback Detection Logic

```bash
# Check gh availability
check_gh_available() {
    if command -v gh &> /dev/null; then
        # Check if authenticated (optional)
        if gh auth status &> /dev/null; then
            echo "gh_authenticated"
        else
            echo "gh_unauthenticated"
        fi
    else
        echo "gh_unavailable"
    fi
}

# Use result to choose method
status=$(check_gh_available)
case $status in
    gh_authenticated)
        # Full gh CLI access
        gh issue list --repo owner/repo --search "keyword"
        ;;
    gh_unauthenticated)
        # gh works for public repos
        gh issue list --repo owner/repo --search "keyword"
        ;;
    gh_unavailable)
        # Fall back to web methods
        echo "Falling back to WebSearch..."
        ;;
esac
```

---

## Comparison of Methods

| Method | Speed | Auth Required | Rate Limit | Parsing Quality |
| --- | --- | --- | --- | --- |
| gh CLI | Fast | Recommended | 5000/hr | Excellent |
| WebSearch | Fast | No | N/A | Moderate |
| firecrawl | Medium | No | Varies | Good |
| Direct URL + WebFetch | Slow | No | N/A | Variable |
| GitHub API | Fast | Optional | 60/hr (unauth) | Excellent |

---

## Best Practices

1. **Always try gh first** - It's the most reliable method
2. **Cache results** - Avoid repeated requests for same query
3. **Handle failures gracefully** - Have multiple fallback layers
4. **Inform user** - Let them know which method is being used
5. **Rate limit awareness** - Don't exhaust limits with repeated queries

---

## Example Fallback Workflow

```text
1. Check: Is gh installed?
   - Yes: Use gh issue list
   - No: Continue to step 2

2. Try: WebSearch with site:github.com query
   - Success: Parse and return results
   - Failure: Continue to step 3

3. Try: WebFetch on search URL
   - Success: Parse HTML and return results
   - Failure: Report inability to search

4. Report: Method used and any limitations
```

---

## Related Documentation

- [GitHub API Documentation](https://docs.github.com/en/rest/issues)
- [GitHub Search Documentation](https://docs.github.com/en/search-github)

```

### references/gh-cli-guide.md

```markdown
# GitHub CLI (gh) Guide

Complete guide to installing, authenticating, and using the GitHub CLI for issue management.

## Installation

### macOS

```bash
# Homebrew (recommended)
brew install gh

# MacPorts
sudo port install gh
```

### Windows

```powershell
# winget (recommended)
winget install --id GitHub.cli

# Chocolatey
choco install gh

# Scoop
scoop install gh
```

### Linux

```bash
# Debian/Ubuntu
type -p curl >/dev/null || (sudo apt update && sudo apt install curl -y)
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
&& sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
&& sudo apt update \
&& sudo apt install gh -y

# Fedora/RHEL/CentOS
sudo dnf install gh

# Arch Linux
sudo pacman -S github-cli
```

### Verify Installation

```bash
gh --version
# gh version 2.x.x (2024-xx-xx)
```

---

## Authentication

### Interactive Login (Recommended)

```bash
gh auth login
```

Follow the prompts to:

1. Choose GitHub.com or GitHub Enterprise
2. Choose authentication method (browser or token)
3. Complete authentication

### Token-Based Login

```bash
# Using environment variable
export GH_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
gh auth status

# Or pass token directly
gh auth login --with-token < token.txt
```

### Verify Authentication

```bash
gh auth status
# github.com
#   Logged in to github.com account username (keyring)
#   Token: ghp_************************************
#   Token scopes: 'gist', 'read:org', 'repo', 'workflow'
```

### Authentication for Private Repos

For private repositories, ensure your token has:

- `repo` scope (full control of private repositories)

---

## Issue Commands Reference

### List Issues

```bash
# Basic list (open issues in current repo)
gh issue list

# All states
gh issue list --state all

# With search
gh issue list --search "keyword"

# Specific repo
gh issue list --repo owner/repo

# Filter by label
gh issue list --label "bug"

# Filter by assignee
gh issue list --assignee @me

# Limit results
gh issue list --limit 50

# JSON output
gh issue list --json number,title,state,labels
```

### View Issue

```bash
# View in terminal
gh issue view 123

# With comments
gh issue view 123 --comments

# JSON output
gh issue view 123 --json title,body,comments,labels,state

# Open in browser
gh issue view 123 --web
```

### Search Issues

```bash
# Basic search
gh issue list --search "error message"

# Search with qualifiers
gh issue list --search "is:open label:bug"

# Author search
gh issue list --search "author:username"

# Combined
gh issue list --search "is:closed label:bug milestone:v1.0"
```

---

## Advanced Usage

### Output Formatting

```bash
# JSON output
gh issue list --json number,title,state

# Custom template
gh issue list --template '{{range .}}#{{.number}} {{.title}}{{"\n"}}{{end}}'

# Pipe to jq for processing
gh issue list --json number,title | jq '.[].title'
```

### Combining with Other Tools

```bash
# Filter with grep
gh issue list --json title | grep -i "error"

# Count issues
gh issue list --json number | jq 'length'

# Export to file
gh issue list --json number,title,state > issues.json
```

### Rate Limits

- **Authenticated:** 5,000 requests/hour
- **Unauthenticated:** 60 requests/hour

Check current status:

```bash
gh api rate_limit
```

---

## Troubleshooting

### "gh: command not found"

GitHub CLI not installed. Follow installation steps above.

### "authentication required"

Run `gh auth login` to authenticate.

### "repository not found"

- Check repository path (owner/repo)
- Verify you have access to private repositories
- Ensure correct authentication scopes

### Rate limit exceeded

Wait for rate limit reset or authenticate for higher limits:

```bash
gh api rate_limit --jq '.rate.reset | strftime("%Y-%m-%d %H:%M:%S")'
```

---

## Related Documentation

- [GitHub CLI Manual](https://cli.github.com/manual/)
- [GitHub CLI Issue Commands](https://cli.github.com/manual/gh_issue)

```