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

gh-search-code

Skill9 starsChanged 12 months agoMITView on GitHub

Use when searching code across GitHub repositories - provides syntax for file extensions, filenames, languages, sizes, exclusions, and using -w flag for regex search via web interface

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 3 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

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

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

    Search for code across GitHub repositories using gh search code.

    line 10
  2. Distinctive:

    Use this skill when searching code across GitHub:

    line 14
  3. Very specific:

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

    line 49
  4. Very specific:

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

    line 155
  5. Very specific:

    Use the -- separator before your query

    line 158
  6. Very specific:

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

    line 159
  7. Distinctive:

    Use quotes for comparison operators:

    line 230
  8. Very specific:

    If gh command not found:

    line 296
  9. Distinctive:

    Use the web flag when you need:

    line 328
  10. Very specific:

    Workaround: Use -w/--web to access full GitHub search features

    line 348

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

Overview

Search for code across GitHub repositories using gh search code. Important: CLI API uses legacy search engine. For regex and advanced features, use -w flag to open in web browser.

When to Use This Skill

Use this skill when searching code across GitHub:

  • Searching for code patterns across multiple repositories
  • Finding specific file types or filenames in repos/orgs
  • Locating code by language or file size across GitHub
  • Searching in specific repositories or organizations
  • Need to exclude certain results (requires -- flag)
  • Need regex search (use -w to open in browser)

Syntax

gh search code <query> [flags]

Key Flags Reference

FlagPurposeExample
--extension <string>Filter by file extension--extension js
--filename <string>Target specific filenames--filename package.json
--language <string>Filter by programming language--language python
--owner <strings>Limit to specific owners--owner microsoft
-R, --repo <strings>Search within repository--repo cli/cli
--size <string>Filter by file size (KB)--size ">100"
--match <strings>Search in file or path--match file or --match path
-L, --limit <int>Max results (default: 30)--limit 100
-w, --webOpen in browser-w
--json <fields>JSON output--json path,repository

JSON Output Fields

Available fields: path, repository, sha, textMatches, url

Exclusion Syntax (Critical!)

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

✅ Correct: gh search code -- "search-terms -qualifier:value" ❌ Wrong: gh search code "search-terms" --flag=-value ❌ Wrong: gh search code "search-terms" --flag=!value ❌ Wrong: gh search code "search-terms" --filename="!test"

Examples:

  • gh search code -- "function -filename:test" (exclude files named "test")
  • gh search code -- "import -language:javascript" (exclude language)
  • gh search code -- "config -path:vendor" (exclude vendor directories)
  • gh search code -- "TODO -extension:md" (exclude extension)

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.

Understanding -filename: vs -path: Qualifiers

Critical Distinction: These qualifiers have different matching behaviors:

QualifierMatchesUse When
-filename:Filename only (e.g., test.js, utils_test.py)Excluding files by their name pattern
-path:Full file path (e.g., src/test/file.js, lib/testing/util.js)Excluding directory paths or path segments

When to Use Each

Use -filename: when:

  • User says "exclude test files" → means files named with "test"
  • Targeting files by their name pattern
  • Examples: test.js, config_test.py, utils.test.ts

Use -path: when:

  • User says "exclude test directories" → means directories containing "test"
  • Targeting files in specific directory paths
  • Examples: tests/, __test__/, src/test/, lib/testing/

Matching Examples

-filename:test matches:

  • test.js ✅
  • utils_test.py ✅
  • test_helper.rb ✅
  • src/file.js ❌ (doesn't contain "test" in filename)
  • tests/utils.js ❌ (filename is "utils.js", not "test")

-path:test matches:

  • tests/utils.js ✅ (path contains "test")
  • src/test/file.js ✅ (path contains "test")
  • lib/testing/helper.py ✅ (path contains "test")
  • test.js ✅ (path includes filename)
  • src/utils.js ❌ (path doesn't contain "test")

Practical Examples

Exclude files by name:

# User: "Find functions but NOT in test files"
gh search code -- "function -filename:test"
# Excludes: test.js, utils_test.py, config.test.ts
# Includes: tests/utils.js (filename is "utils.js", not "test")

Exclude directories:

# User: "Find config but NOT in test directories"
gh search code -- "config -path:test"
# Excludes: tests/config.js, src/test/config.py, __test__/setup.js
# Includes: config_test.js (not in test directory)

Combine both qualifiers:

# User: "Exclude both test files AND test directories"
gh search code -- "function -filename:test -path:test"
# Excludes: test.js, tests/utils.js, src/test/file.js, utils_test.py

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 code "import" --language python --extension py

Query Syntax with -- (required for exclusions):

gh search code -- "function -filename:test.js -language:javascript"

⚠️ 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 files named "test.js"
gh search code -- "function -filename:test.js"

# Exclude specific language
gh search code -- "import -language:javascript"

# Exclude vendor directories
gh search code -- "config -path:vendor"

Multiple exclusions:

# Exclude multiple filenames
gh search code -- "function -filename:test.js -filename:spec.js"

# Exclude language and test directories
gh search code -- "TODO -language:go -path:test"

# Exclude multiple languages
gh search code -- "class -language:java -language:kotlin"

Combine with positive filters using flags:

# Wrong - mixing syntaxes:
gh search code "function" --language python -filename:test  # ❌

# Correct - use query syntax for everything when excluding:
gh search code -- "function language:python -filename:test"  # ✅

PowerShell exclusions:

# Use --% to prevent PowerShell parsing
gh --% search code -- "function -filename:test.js"

Common Exclusion Patterns:

User RequestCommandQualifier Used
"Find code but not in test files"gh search code -- "function -filename:test"-filename: (matches file names)
"Code excluding test directories"gh search code -- "function -path:test"-path: (matches directory paths)
"Code excluding specific language"gh search code -- "import -language:javascript"-language:
"Code not in vendor/node_modules dirs"gh search code -- "config -path:vendor -path:node_modules"-path: (matches directories)
"Functions excluding test and spec files"gh search code -- "function -filename:test -filename:spec"-filename: (matches file names)
"Code excluding large files"gh search code -- "class -size:>500"-size:
"Code not in specific extension"gh search code -- "TODO -extension:md -extension:txt"-extension:
"Code excluding example/doc directories"gh search code -- "api -path:examples -path:docs"-path: (matches directories)

2. Quoting Rules

Multi-word search:

gh search code "error handling"

Complex queries with qualifiers:

gh search code "TODO in:file" --language javascript

3. Size Comparisons

Use quotes for comparison operators:

gh search code "import" --size ">50" --language python

Common Use Cases

Search for function patterns:

gh search code "async function" --language typescript

Find configuration files:

gh search code "database" --filename config.json --owner myorg

Search in specific repo:

gh search code "TODO" --repo owner/repo --language go

Exclude files named with "test":

gh search code -- "function -filename:test"

Exclude test directories:

gh search code -- "function -path:test"

Search by file size:

gh search code "import" --size "100..500" --language python

Use regex (via web):

# Open in browser for regex support
gh search code "function.*test" --language javascript -w
# Web UI allows: /function.*test/ or /class\s+\w+/

Build complex query, refine in web:

# Start with CLI filters, finish with regex in browser
gh search code --owner microsoft --language typescript -w

Common Mistakes

MistakeProblemFix
--extension="NOT js" or --language=-pythonFlag syntax doesn't support negationUse query: -- "-extension:js" or -- "-language:python"
gh search code import -language:js-language interpreted as flagUse --: gh search code -- "import -language:js"
"function NOT language:js"NOT keyword doesn't workUse -: -- "function -language:js"
Mixing syntaxes: --language python "code -filename:test"Can't mix flags with query qualifiersUse query for all: -- "code language:python -filename:test"
Not quoting multi-word queriesSearches separatelyQuote: "error handling"
Forgetting quotes on comparisonsShell interprets >Quote: --size ">100"
Using -filename inline without --Parsed as flagUse --: -- "code -filename:test"
Trying regex via CLICLI API doesn't support regexUse -w flag: gh search code "pattern" -w
PowerShell without --%Breaks with exclusionsAdd: gh --%

Installation Check

If gh command not found:

# Check if gh is installed
which gh

# If not installed, see: https://cli.github.com/manual/installation

If not authenticated:

# Authenticate with GitHub
gh auth login

Web Browser Flag (-w/--web)

Important workaround for advanced features:

The -w/--web flag opens your search in GitHub's web interface, which supports features not available via CLI API:

Regex Search (Web Only)

# This opens in browser where you can use regex
gh search code "function.*test" --language javascript -w

# In the web UI, you can then modify to use regex syntax:
# /function.*test/ language:javascript

When to Use -w

Use the web flag when you need:

  • Regex patterns - /pattern/ syntax for complex matching
  • Advanced filters - Newer GitHub search features
  • Visual browsing - Easier to explore results visually
  • Better results - Web uses newer search engine

Combining CLI + Web

# Build query with CLI, open in web for regex
gh search code --language python --repo myorg/myrepo -w
# Then add regex pattern in web UI

Limitations (CLI API)

  • Powered by legacy GitHub search engine
  • Results may differ from github.com
  • Regex search not available via CLI (use -w flag instead)
  • Some advanced features may not work
  • Workaround: Use -w/--web to access full GitHub search features

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.