gh-search-issues
Skill9 starsChanged 12 months agoMITView on GitHub
Use when searching GitHub issues ACROSS REPOSITORIES or organizations - provides syntax for filtering by labels, state, assignees, authors, comments, reactions, dates. For current repo issues, use gh issue list instead.
In this repository8 other files it gives its agents.
- gh-cli-setupSkill
- gh-search-codeSkill
- gh-search-commitsSkill
- gh-search-prsSkill
- gh-search-reposSkill
- gh-searchSkill
- testing-gh-skillsSkill
- using-gh-cli-searchSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 2 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
Search for issues across GitHub repositories using gh search issues.
- Distinctive: line 30
Use this skill when the user explicitly indicates:
- Distinctive: line 38
No repo/org is specified and context is clearly current repository
- Very specific: line 39
Use gh issue list for current repo operations instead
- Very specific: line 118
When using inline query exclusions (negations with -), you MUST use the -- separator:
- Very specific: line 162
CRITICAL: When excluding results, you MUST use query syntax with the -- separator.
- Very specific: line 165
Use the -- separator before your query
- Very specific: line 166
Use -qualifier:value format (dash prefix for negation)
- Very specific: line 297
If gh command not found:
- Very specific: line 321
Use in: to search specific fields:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
GitHub CLI: Search Issues
Overview
Search for issues across GitHub repositories using gh search issues. Add --include-prs flag to also search pull requests.
⚠️ CRITICAL: Search vs List Commands
gh search issues - GitHub-wide search (THIS SKILL):
- Searches across multiple repositories or organizations
- Searches in specific repos outside your current directory
- Uses GitHub's search query syntax with qualifiers
- Examples: "Find issues in the microsoft organization", "Search for bugs in kubernetes repos"
gh issue list - Current repository only (NOT THIS SKILL):
- Lists issues in your current working directory's repo
- Uses simple flag-based filtering
- Examples: "Show my issues in this repo", "List open bugs here"
When user says "my issues" or "issues here" → Use gh issue list (NOT this skill)
When user specifies repo/org or cross-repo search → Use gh search issues (THIS skill)
When to Use This Skill
Use this skill when the user explicitly indicates:
- Searching across multiple repositories or organizations
- Searching in a specific repo (e.g., "in kubernetes/kubernetes")
- Cross-GitHub searches (e.g., "all my open issues across GitHub")
- Complex queries needing search qualifiers (e.g., "comments>50 across microsoft repos")
DO NOT use this skill when:
- User asks about "issues in this repo" or "my issues here"
- No repo/org is specified and context is clearly current repository
- Use
gh issue listfor current repo operations instead
Syntax
gh search issues [<query>] [flags]Key Flags Reference
User Filters
| Flag | Purpose | Example |
--author <string> | Created by user | --author octocat |
--assignee <string> | Assigned to user | --assignee @me |
--mentions <user> | Mentions specific user | --mentions octocat |
--commenter <user> | Commented by user | --commenter octocat |
--team-mentions <string> | Mentions team | --team-mentions myteam |
Issue Attributes
| Flag | Purpose | Example |
--label <strings> | Has specific labels | --label bug,urgent |
--state <string> | Issue state: open or closed | --state open |
--milestone <title> | In specific milestone | --milestone v1.0 |
--locked | Locked conversation | --locked |
--no-label | Has no labels | --no-label |
Repository Filters
| Flag | Purpose | Example |
--owner <strings> | Repository owner | --owner github |
-R, --repo <strings> | Specific repository | --repo cli/cli |
--language <string> | Repository language | --language go |
--visibility <strings> | Repo visibility | --visibility public |
--archived | In archived repos | --archived |
Engagement Metrics
| Flag | Purpose | Example |
--comments <number> | Number of comments | --comments ">10" |
--reactions <number> | Reaction count | --reactions ">5" |
--interactions <number> | Comments + reactions | --interactions ">20" |
Date Filters
| Flag | Purpose | Example |
--created <date> | Creation date | --created ">2024-01-01" |
--updated <date> | Last update date | --updated ">2024-06-01" |
--closed <date> | Close date | --closed "<2024-12-31" |
Search Scope
| Flag | Purpose | Example |
--match <strings> | Search in: title, body, comments | --match title |
--include-prs | Include pull requests | --include-prs |
Output & Sorting
| Flag | Purpose | Example |
-L, --limit <int> | Max results (default: 30) | --limit 100 |
--sort <string> | Sort by: comments, created, reactions, etc. | --sort comments |
--order <string> | Sort direction: asc or desc | --order desc |
--json <fields> | JSON output | --json number,title,state |
-w, --web | Open in browser | -w |
JSON Output Fields
assignees, author, authorAssociation, body, closedAt, commentsCount, createdAt, id, isLocked, isPullRequest, labels, number, repository, state, title, updatedAt, url
Exclusion Syntax (Critical!)
When using inline query exclusions (negations with -), you MUST use the -- separator:
✅ Correct: gh search issues -- "search-terms -qualifier:value"
❌ Wrong: gh search issues "search-terms" --flag=-value
❌ Wrong: gh search issues "search-terms" --flag=!value
❌ Wrong: gh search issues --label!=bug
Examples:
gh search issues -- "bug -label:wontfix"(exclude label)gh search issues -- "crash -assignee:olduser"(exclude assignee)gh search issues -- "error -author:bot"(exclude author)gh search issues -- "performance -milestone:v1.0"(exclude milestone)
Why the -- separator is required:
The -- tells the shell to stop parsing flags and treat everything after it as arguments. Without it, -qualifier:value inside quotes may be misinterpreted.
Critical Syntax Rules
When to Use Flag Syntax vs Query Syntax
Decision Tree:
Does your search include:
- Any exclusions (NOT, minus, without, except)? → Use Query Syntax with `--`
- Complex boolean logic (OR, AND)? → Use Query Syntax with `--`
Otherwise:
- Simple positive filters only? → Use Flag SyntaxFlag Syntax (for positive filters):
gh search issues "bug" --label urgent --state openQuery Syntax with -- (required for exclusions):
gh search issues -- "bug -label:duplicate -label:wontfix"⚠️ NEVER mix both syntaxes in a single command!
1. Exclusions and Negations
CRITICAL: When excluding results, you MUST use query syntax with the -- separator.
Exclusion Syntax Rules:
- Use the
--separator before your query - Use
-qualifier:valueformat (dash prefix for negation) - Quote the entire query string
Examples:
Single exclusion:
# Exclude specific label
gh search issues -- "bug -label:duplicate"
# Exclude specific assignee
gh search issues -- "crash -assignee:olduser"Multiple exclusions:
# Exclude multiple labels
gh search issues -- "bug -label:duplicate -label:wontfix"
# Exclude author and label
gh search issues -- "performance -author:bot -label:invalid"Combine with positive filters using flags:
# Wrong - mixing syntaxes:
gh search issues "bug" --state open -label:duplicate # ❌
# Correct - use query syntax for everything when excluding:
gh search issues -- "bug state:open -label:duplicate" # ✅PowerShell exclusions:
# Use --% to prevent PowerShell parsing
gh --% search issues -- "bug -label:duplicate"Common Exclusion Patterns:
| User Request | Command |
| "Find bugs but not duplicates" | gh search issues -- "bug -label:duplicate" |
| "Issues not assigned to anyone" | gh search issues -- "enhancement -assignee:*" (use --no-assignee instead) |
| "Open issues excluding specific label" | gh search issues -- "state:open -label:wontfix" |
| "Issues excluding multiple labels" | gh search issues -- "crash -label:duplicate -label:invalid" |
| "Issues not in milestone" | gh search issues -- "bug -milestone:v1.0" |
| "Issues not by bot authors" | gh search issues -- "error -author:dependabot -author:renovate" |
2. Special Values
@me- Current authenticated usergh search issues --assignee @me --state open
3. Quoting Rules
Multi-word search:
gh search issues "memory leak"Labels with spaces:
gh search issues -- 'crash label:"bug fix"'Comparison operators need quotes:
gh search issues "performance" --comments ">10"Common Use Cases
Find your open issues across all of GitHub:
gh search issues --author @me --state openFind unassigned bugs in a specific org:
gh search issues --label bug --no-assignee --state open --owner kubernetesFind highly discussed issues in a specific repo:
gh search issues --comments ">50" --state open --repo microsoft/vscodeFind stale issues across multiple repos:
gh search issues --state open --updated "<2023-01-01" --owner myorgSearch issues AND PRs in an organization:
gh search issues "authentication" --include-prs --state open --owner githubExclude specific labels in cross-repo search:
gh search issues -- "crash -label:duplicate -label:wontfix" --repo cli/cliFind issues in milestone across repos:
gh search issues --milestone v2.0 --state open --owner golangFind issues by title only in specific language repos:
gh search issues "error in:title" --state open --language rustCommon Mistakes
| Mistake | Problem | Fix |
--label="NOT duplicate" or --assignee=-bot | Flag syntax doesn't support negation | Use query: -- "-label:duplicate" or -- "-assignee:bot" |
gh search issues bug -label:duplicate | -label interpreted as flag | Use --: -- "bug -label:duplicate" |
"bug NOT label:duplicate" | NOT keyword doesn't work | Use -: -- "bug -label:duplicate" |
Mixing syntaxes: --state open "bug -label:dup" | Can't mix flags with query qualifiers | Use query for all: -- "bug state:open -label:dup" |
--assignee @username | Invalid @ prefix | Use @me or drop @: --assignee username |
| Not quoting comparisons | Shell interprets > | Quote: --comments ">10" |
label:"bug fix" outside quotes | Shell parsing error | Quote query: 'label:"bug fix"' |
Forgetting --include-prs | Misses pull requests | Add: --include-prs |
PowerShell without --% | Breaks with exclusions | Add: gh --% |
Installation Check
If gh command not found:
# Check if gh is installed
which gh
# Install: https://cli.github.com/manual/installationIf not authenticated:
# Authenticate with GitHub
gh auth loginComparison Operators
>- Greater than>=- Greater than or equal<- Less than<=- Less than or equal..- Range:10..50or2024-01-01..2024-12-31
Field Qualifiers
Use in: to search specific fields:
in:title- Search in title onlyin:body- Search in body onlyin:comments- Search in comments only
Example: gh search issues "crash in:title" --state open
Related
- GitHub search syntax: https://docs.github.com/search-github/searching-on-github/searching-issues-and-pull-requests
- For searching other resources:
gh-search-code,gh-search-commits,gh-search-prs,gh-search-repos
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

