agentleFS
aaddrickaaddrick/gh-cli-search/skills/gh-search-issues/SKILL.md

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.

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
  1. Very specific:

    Search for issues across GitHub repositories using gh search issues.

    line 10
  2. Distinctive:

    Use this skill when the user explicitly indicates:

    line 30
  3. Distinctive:

    No repo/org is specified and context is clearly current repository

    line 38
  4. Very specific:

    Use gh issue list for current repo operations instead

    line 39
  5. Very specific:

    When using inline query exclusions (negations with -), you MUST use the -- separator:

    line 118
  6. Very specific:

    CRITICAL: When excluding results, you MUST use query syntax with the -- separator.

    line 162
  7. Very specific:

    Use the -- separator before your query

    line 165
  8. Very specific:

    Use -qualifier:value format (dash prefix for negation)

    line 166
  9. Very specific:

    If gh command not found:

    line 297
  10. Very specific:

    Use in: to search specific fields:

    line 321

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 list for current repo operations instead

Syntax

gh search issues [<query>] [flags]

Key Flags Reference

User Filters

FlagPurposeExample
--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

FlagPurposeExample
--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
--lockedLocked conversation--locked
--no-labelHas no labels--no-label

Repository Filters

FlagPurposeExample
--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
--archivedIn archived repos--archived

Engagement Metrics

FlagPurposeExample
--comments <number>Number of comments--comments ">10"
--reactions <number>Reaction count--reactions ">5"
--interactions <number>Comments + reactions--interactions ">20"

Date Filters

FlagPurposeExample
--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

FlagPurposeExample
--match <strings>Search in: title, body, comments--match title
--include-prsInclude pull requests--include-prs

Output & Sorting

FlagPurposeExample
-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, --webOpen 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 Syntax

Flag Syntax (for positive filters):

gh search issues "bug" --label urgent --state open

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

  1. Use the -- separator before your query
  2. Use -qualifier:value format (dash prefix for negation)
  3. 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 RequestCommand
"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 user
    gh 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 open

Find unassigned bugs in a specific org:

gh search issues --label bug --no-assignee --state open --owner kubernetes

Find highly discussed issues in a specific repo:

gh search issues --comments ">50" --state open --repo microsoft/vscode

Find stale issues across multiple repos:

gh search issues --state open --updated "<2023-01-01" --owner myorg

Search issues AND PRs in an organization:

gh search issues "authentication" --include-prs --state open --owner github

Exclude specific labels in cross-repo search:

gh search issues -- "crash -label:duplicate -label:wontfix" --repo cli/cli

Find issues in milestone across repos:

gh search issues --milestone v2.0 --state open --owner golang

Find issues by title only in specific language repos:

gh search issues "error in:title" --state open --language rust

Common Mistakes

MistakeProblemFix
--label="NOT duplicate" or --assignee=-botFlag syntax doesn't support negationUse query: -- "-label:duplicate" or -- "-assignee:bot"
gh search issues bug -label:duplicate-label interpreted as flagUse --: -- "bug -label:duplicate"
"bug NOT label:duplicate"NOT keyword doesn't workUse -: -- "bug -label:duplicate"
Mixing syntaxes: --state open "bug -label:dup"Can't mix flags with query qualifiersUse query for all: -- "bug state:open -label:dup"
--assignee @usernameInvalid @ prefixUse @me or drop @: --assignee username
Not quoting comparisonsShell interprets >Quote: --comments ">10"
label:"bug fix" outside quotesShell parsing errorQuote query: 'label:"bug fix"'
Forgetting --include-prsMisses pull requestsAdd: --include-prs
PowerShell without --%Breaks with exclusionsAdd: gh --%

Installation Check

If gh command not found:

# Check if gh is installed
which gh

# Install: https://cli.github.com/manual/installation

If not authenticated:

# Authenticate with GitHub
gh auth login

Comparison Operators

  • > - Greater than
  • >= - Greater than or equal
  • < - Less than
  • <= - Less than or equal
  • .. - Range: 10..50 or 2024-01-01..2024-12-31

Field Qualifiers

Use in: to search specific fields:

  • in:title - Search in title only
  • in:body - Search in body only
  • in:comments - Search in comments only

Example: gh search issues "crash in:title" --state open

Related

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.