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

gh-search

Skill9 starsChanged 12 months agoMITView on GitHub

Use when searching GitHub via CLI for issues, PRs, repos, code, or commits - provides correct syntax for exclusions, qualifiers, quoting, and platform-specific handling to avoid command failures

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Search GitHub from the command line using gh search subcommands.

    line 10
  2. Distinctive:

    Use this skill when:

    line 14

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

Overview

Search GitHub from the command line using gh search subcommands. The key principle: Always use -- before queries with exclusions to prevent shell interpretation of - prefixes.

When to Use

Use this skill when:

  • Searching GitHub via gh CLI for issues, PRs, repos, code, or commits
  • User requests searches with exclusions (NOT, minus prefix)
  • Constructing complex queries with multiple qualifiers
  • Queries contain spaces or special characters

Subcommands Quick Reference

SubcommandUse ForCommon Flags
gh search issuesIssues (add --include-prs for PRs too)--label, --state, --author, --assignee
gh search prsPull requests only--label, --state, --author, --draft, --merged
gh search reposRepositories--language, --stars, --topic, --owner
gh search codeCode within files--repo, --language, --filename
gh search commitsCommit messages--repo, --author, --committer

Critical Syntax Rules

1. Exclusions Require -- Flag

Unix/Linux/Mac:

gh search issues -- "bug -label:duplicate"

PowerShell:

gh --% search issues -- "bug -label:duplicate"

Why: The - prefix gets interpreted as a command flag without --. PowerShell needs --% to stop parsing.

2. Quoting Rules

Multi-word queries need quotes:

gh search issues "memory leak"

Entire query with spaces should be quoted:

gh search issues "bug label:urgent created:>2024-01-01"

Qualifier values with spaces need inner quotes:

gh search prs -- 'security label:"bug fix"'

3. Qualifier Syntax

Inline qualifiers (use within search query):

gh search repos "react stars:>1000 language:typescript"

Flag-based (use as separate flags):

gh search repos "react" --language typescript --stars ">1000"

Can mix both:

gh search issues "crash" --label bug created:>2024-01-01

Common Qualifiers

Comparison Operators

  • >, >=, <, <= - Numeric: stars:>100, comments:>=5
  • .. - Ranges: stars:10..50, created:2024-01-01..2024-12-31

Special Values

  • @me - Current user: author:@me, assignee:@me, owner:@me
  • Dates use ISO8601: created:>2024-01-01 or created:2024-01-01..2024-12-31

Field-Specific Search

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

Exclusions

  • -qualifier:value - Exclude: -label:bug, -language:javascript
  • NOT keyword - For words only: "hello NOT world"

Examples

Find your open issues without bug label:

gh search issues -- "is:open author:@me -label:bug"

Find popular Python ML repos updated recently:

gh search repos "machine learning" --language python --stars ">1000" --updated ">2024-01-01"

Find PRs with specific label and text:

gh search prs -- 'security label:"bug fix" created:>2024-01-01'

Search code in organization repos:

gh search code "TODO" --owner myorg --language javascript

Common Mistakes

MistakeProblemFix
gh search issues -label:bug-label interpreted as flagAdd --: gh search issues -- "-label:bug"
gh search repos machine learningSearches "machine" OR "learning"Quote it: "machine learning"
in:title outside quotesShell interprets : oddlyInclude in query: "crash in:title"
Mixing @ with valueInvalid syntaxUse @me or username, not both: author:@me ✓, author:@username ✗ (drop @)
PowerShell without --%Parsing breaks with exclusionsAdd gh --% before command

Output Options

All subcommands support:

  • --limit <n> - Max results (default: 30, max: 1000)
  • --json <fields> - JSON output for scripting
  • --web - Open results in browser
  • --sort <field> - Sort by: comments, created, reactions, updated, stars, etc.
  • --order asc|desc - Sort direction (default: desc)

Real-World Impact

Correct syntax prevents:

  • Command failures from misinterpreted flags
  • Missing results from incorrect exclusions
  • Errors from unquoted spaces
  • Platform-specific parsing issues

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.