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)

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:

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:

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

2. Filter by Labels

Narrow results using repository labels.

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.

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.

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:

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):

• WebSearch tool: site:github.com/owner/repo/issues keyword

• firecrawl MCP: Scrape GitHub search results

• Direct URL: https://github.com/owner/repo/issues?q=keyword

For detailed fallback guidance: See references/web-fallback.md

Output Formats

The skill supports three output formats:

Compact (default)

One line per issue, good for scanning:

#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:

Detailed

Full information for deep investigation:

#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

• Extract key terms from error message

• Search issues with those terms

• Check both open and closed issues

• Look for workarounds in comments

Example: Troubleshoot a specific error

gh issue list --repo anthropics/claude-code --search "ENOENT" --state all --limit 10

Before Reporting a Bug

• Search for existing issues with similar symptoms

• Check closed issues for past fixes

• If duplicate exists, add your context as a comment

Search before reporting

gh issue list --repo owner/repo --search "feature not working" --state all

Finding Workarounds

• Search closed issues with your problem keywords

• Look for issues with "workaround" or "solution" in body

• Check issue comments for community solutions

Find workarounds

gh issue list --repo owner/repo --search "workaround" --state closed --label "bug"

Error Handling

gh not installed

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

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

Error: API rate limit exceeded

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

No results found

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 - Installation, authentication, advanced usage

• references/query-patterns.md - Search syntax and filter examples

• 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