gh-search-prs
Skill9 starsChanged 12 months agoMITView on GitHub
Use when searching GitHub pull requests ACROSS REPOSITORIES or organizations - provides syntax for filtering by draft status, merge status, review state, CI checks, branches. For current repo PRs, use gh pr list instead.
In this repository8 other files it gives its agents.
- gh-cli-setupSkill
- gh-search-codeSkill
- gh-search-commitsSkill
- gh-search-issuesSkill
- 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 pull requests across GitHub repositories using gh search prs.
- 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 pr list for current repo operations instead
- Very specific: line 131
When using inline query exclusions (negations with -), you MUST use the -- separator:
- Very specific: line 175
CRITICAL: When excluding results, you MUST use query syntax with the -- separator.
- Very specific: line 178
Use the -- separator before your query
- Very specific: line 179
Use -qualifier:value format (dash prefix for negation)
- Very specific: line 334
If gh command not found:
- Very specific: line 358
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 Pull Requests
Overview
Search for pull requests across GitHub repositories using gh search prs. Includes PR-specific filters like draft status, merge state, review status, and CI checks.
⚠️ CRITICAL: Search vs List Commands
gh search prs - 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 draft PRs in kubernetes repos", "Search for approved PRs in microsoft org"
gh pr list - Current repository only (NOT THIS SKILL):
- Lists PRs in your current working directory's repo
- Uses simple flag-based filtering
- Examples: "Show my PRs in this repo", "List open PRs here"
When user says "my PRs" or "PRs here" → Use gh pr list (NOT this skill)
When user specifies repo/org or cross-repo search → Use gh search prs (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 draft PRs across the organization")
- Complex queries needing search qualifiers (e.g., "approved PRs with >10 comments in golang repos")
DO NOT use this skill when:
- User asks about "PRs in this repo" or "my PRs here"
- No repo/org is specified and context is clearly current repository
- Use
gh pr listfor current repo operations instead
Syntax
gh search prs [<query>] [flags]Key Flags Reference
PR-Specific Filters
| Flag | Purpose | Example |
--draft | Filter draft PRs | --draft |
--merged | Filter merged PRs | --merged |
--merged-at <date> | Merged at date | --merged-at ">2024-01-01" |
-B, --base <string> | Base branch name | --base main |
-H, --head <string> | Head branch name | --head feature-auth |
--review <string> | Review status | --review approved |
--review-requested <user> | Review requested from | --review-requested @me |
--reviewed-by <user> | Reviewed by user | --reviewed-by octocat |
--checks <string> | CI check status | --checks success |
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 |
PR Attributes
| Flag | Purpose | Example |
--label <strings> | Has specific labels | --label bug,urgent |
--state <string> | PR 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 typescript |
--visibility <strings> | Repo visibility | --visibility public |
--archived | In archived repos | --archived |
Engagement Metrics
| Flag | Purpose | Example |
--comments <number> | Number of comments | --comments ">5" |
--reactions <number> | Reaction count | --reactions ">10" |
--interactions <number> | Comments + reactions | --interactions ">15" |
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 |
Output & Sorting
| Flag | Purpose | Example |
-L, --limit <int> | Max results (default: 30) | --limit 100 |
--sort <string> | Sort by: comments, created, reactions, etc. | --sort updated |
--order <string> | Sort direction: asc or desc | --order desc |
--json <fields> | JSON output | --json number,title,state,isDraft |
-w, --web | Open in browser | -w |
JSON Output Fields
assignees, author, authorAssociation, body, closedAt, commentsCount, createdAt, id, isDraft, 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 prs -- "search-terms -qualifier:value"
❌ Wrong: gh search prs "search-terms" --flag=-value
❌ Wrong: gh search prs "search-terms" --flag=!value
❌ Wrong: gh search prs --label=-WIP
Examples:
gh search prs -- "feature -label:draft"(exclude label)gh search prs -- "fix -is:draft"(exclude draft PRs)gh search prs -- "deploy -author:bot"(exclude author)gh search prs -- "security -review:changes_requested"(exclude review status)
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 prs "refactor" --draft --state openQuery Syntax with -- (required for exclusions):
gh search prs -- "refactor -label:wip -is:draft"⚠️ 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 prs -- "refactor -label:wip"
# Exclude draft PRs
gh search prs -- "feature -is:draft"Multiple exclusions:
# Exclude multiple labels
gh search prs -- "bug -label:wip -label:blocked"
# Exclude draft PRs and specific review status
gh search prs -- "security -is:draft -review:changes_requested"Combine with positive filters using flags:
# Wrong - mixing syntaxes:
gh search prs "fix" --state open -label:wip # ❌
# Correct - use query syntax for everything when excluding:
gh search prs -- "fix state:open -label:wip" # ✅PowerShell exclusions:
# Use --% to prevent PowerShell parsing
gh --% search prs -- "refactor -label:wip"Common Exclusion Patterns:
| User Request | Command |
| "Find PRs but not drafts" | gh search prs -- "feature -is:draft" |
| "PRs excluding specific label" | gh search prs -- "bug -label:wip" |
| "PRs not from bot authors" | gh search prs -- "update -author:dependabot -author:renovate" |
| "PRs excluding failed checks" | gh search prs -- "deploy -status:failure" |
| "PRs not targeting main branch" | gh search prs -- "feature -base:main" |
| "PRs excluding review status" | gh search prs -- "fix -review:changes_requested" |
| "PRs not merged yet" | gh search prs -- "feature -is:merged" |
2. Special Values
@me- Current authenticated usergh search prs --review-requested @me --state open
3. Review Status Values
none- No reviewsrequired- Review requiredapproved- Approvedchanges_requested- Changes requested
4. Check Status Values
pending- Checks pendingsuccess- All checks passedfailure- Checks failed
5. Quoting Rules
Multi-word search:
gh search prs "bug fix"Labels with spaces:
gh search prs -- 'refactor label:"needs review"'Comparison operators need quotes:
gh search prs "performance" --comments ">5"Common Use Cases
Find your open PRs across all of GitHub:
gh search prs --author @me --state openFind PRs awaiting your review in an organization:
gh search prs --review-requested @me --state open --owner kubernetesFind draft PRs in a specific repo:
gh search prs --draft --repo microsoft/vscodeFind merged PRs in date range across an org:
gh search prs --merged --merged-at "2024-01-01..2024-12-31" --owner golangFind PRs with failing checks in specific repos:
gh search prs --checks failure --state open --repo cli/cliFind approved PRs not yet merged in a repo:
gh search prs --review approved --state open --repo kubernetes/kubernetesFind PRs by base branch in an organization:
gh search prs --base main --state open --owner githubFind PRs with specific head branch pattern across repos:
gh search prs --head feature-* --state open --language goExclude specific labels in cross-repo search:
gh search prs -- "refactor -label:wip -label:draft" --owner myorgFind stale PRs across multiple repos:
gh search prs --state open --updated "<2024-01-01" --owner rust-langCommon Mistakes
| Mistake | Problem | Fix |
--label="NOT wip" or --draft=-true | Flag syntax doesn't support negation | Use query: -- "-label:wip" or -- "-is:draft" |
gh search prs fix -label:wip | -label interpreted as flag | Use --: -- "fix -label:wip" |
"fix NOT label:wip" | NOT keyword doesn't work | Use -: -- "fix -label:wip" |
Mixing syntaxes: --draft "fix -label:wip" | Can't mix flags with query qualifiers | Use query for all: -- "fix is:draft -label:wip" |
--review-requested @username | Invalid @ prefix | Use @me or drop @: --review-requested username |
| Not quoting comparisons | Shell interprets > | Quote: --comments ">5" |
label:"needs review" outside quotes | Shell parsing error | Quote query: 'label:"needs review"' |
Using --merged with --state open | Contradictory filters | Merged PRs are closed; remove --state |
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 prs "authentication 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-issues,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.

