GitHub Search & Discovery Skill

Request: $ARGUMENTS

Determine which mode to use based on the user's request, then follow that section.

Prerequisites

• Tools/CLIs: gh (GitHub CLI) installed
• Credentials/env: an authenticated gh session (gh auth login completed)
• Services/network: reachable api.github.com
• User inputs & decisions: which mode + target query/repo (parsed from the request); runtime-only confirmations that can't be front-loaded because they depend on probed data — multi-repo inspect >5 repos, deep-clone target >500 MB (CRITICAL RULES 7)

STEP 0: Preflight

Verify GitHub CLI auth before any operation:

gh auth status

If this fails, tell the user to run gh auth login first and HARD-STOP — no mode can proceed without it. No other prerequisite exists (no env vars, no input files); mode-specific runtime confirmations (bulk multi-repo, large deep-clone) are handled at their own step since they depend on data only known after the query runs.

MODE 1: SEARCH REPOS

Search GitHub repositories by keywords, stars, topics, language, owner, and more.

Argument Parsing

Extract from user's natural language or explicit flags:

Execution

gh search repos "<query>" \
  --stars "<stars>" \
  --language "<language>" \
  --topic "<topics>" \
  --owner "<owner>" \
  --sort "<sort>" \
  --order "<order>" \
  --limit <limit> \
  --archived=<archived> \
  --json fullName,description,stargazersCount,language,updatedAt,url,forksCount,license \
  --jq '.[] | {fullName, description, stars: .stargazersCount, language, updated: .updatedAt, url, forks: .forksCount, license: .license.key}'

Only include flags the user specified — omit unset optional params. Never pass empty values.

Output Format

## GitHub Repo Search: "<query>"
Filters: stars:<stars> | language:<language> | topic:<topic> | sort:<sort>
Results: N found

| # | Repository | ⭐ Stars | Language | Updated | Description |
|---|-----------|---------|----------|---------|-------------|
| 1 | owner/repo | 12.3K | Python | 2026-03-01 | Short description... |
| 2 | ... | ... | ... | ... | ... |

Use `/github inspect <repo>` to explore any repository.

Natural Language Examples

MODE 2: SEARCH CODE

Search for specific code, files, or patterns across all GitHub repositories.

Argument Parsing

Extract from user's natural language or explicit flags:

Execution

gh search code "<query>" \
  --filename "<filename>" \
  --extension "<extension>" \
  --language "<language>" \
  --owner "<owner>" \
  --repo "<repo>" \
  --limit <limit> \
  --json path,repository,url,textMatches \
  --jq '.[] | {path, repo: .repository.fullName, url, matches: [.textMatches[].fragment]}'

Only include flags the user specified — omit unset optional params. Never pass empty values.

Output Format

## GitHub Code Search: "<query>"
Filters: filename:<filename> | language:<language> | owner:<owner>
Results: N found

| # | Repository | File Path | Match Preview |
|---|-----------|-----------|---------------|
| 1 | owner/repo | .claude/skills/foo/SKILL.md | ...matching text fragment... |
| 2 | owner/repo2 | agents/bar.md | ...matching text fragment... |

Use `/github inspect <repo> --files "<path>"` to read full file contents.

Natural Language Examples

Limitations

If results seem incomplete, inform the user:

• GitHub code search uses a legacy engine via API — results may differ from github.com
• Regex is not supported via the API
• Only indexed files are searchable (very large or binary files are excluded)
• Suggest running with gh search code "<query>" --web to open results in browser for full search capabilities

MODE 3: DEEP INSPECT

After finding repositories via Mode 1 or Mode 2, inspect them to extract and analyze specific files.

Argument Parsing

Input Normalization

Accept various repo formats:

• owner/repo → use directly
• https://github.com/owner/repo → extract owner/repo
• https://github.com/owner/repo/tree/main/path → extract repo + path as --files hint

Depth Level: SHALLOW

Fetch repo metadata and README only. Fastest option.

# Metadata
gh api repos/OWNER/REPO --jq '{
  name: .full_name,
  description: .description,
  stars: .stargazers_count,
  forks: .forks_count,
  language: .language,
  license: .license.key,
  topics: .topics,
  created: .created_at,
  updated: .pushed_at,
  open_issues: .open_issues_count,
  default_branch: .default_branch,
  archived: .archived
}'

# README
gh api repos/OWNER/REPO/readme --jq '.content' | base64 -d

Output:

## Repo: owner/repo
⭐ 12.3K | 🍴 450 | Language: Python | License: MIT
Topics: claude-code, skills, ai-agents
Created: 2025-01-15 | Last push: 2026-03-10
Open issues: 23 | Archived: No

### README (truncated to first 100 lines)
[README content]

Depth Level: TARGETED (default)

Fetch specific files by path or pattern. Uses GitHub Contents API — no cloning required.

Step 1 — List repository tree:

gh api repos/OWNER/REPO/git/trees/BRANCH?recursive=1 \
  --jq '.tree[] | select(.type=="blob") | .path'

Step 2 — Match files against user's --files patterns:

Filter the tree listing using the user's patterns. Patterns support:

• Exact paths: SKILL.md, .claude/settings.json
• Wildcards: *.md, agents/*.md, **/*.py
• Directory prefixes: .claude/skills/ (matches all files under it)

If no --files specified, auto-detect interesting files based on the search context:

• If user searched for skills → look for **/SKILL.md
• If user searched for agents → look for **/agents/*.md
• If user searched for CLAUDE.md → look for **/CLAUDE.md
• If user searched for code patterns → look for files matching the search language/extension
• Otherwise → show the tree listing and ask the user what to inspect

Step 3 — Fetch matched files:

# For each matched file
gh api repos/OWNER/REPO/contents/FILE_PATH?ref=BRANCH --jq '.content' | base64 -d

Rate limit awareness: If more than 30 files match, warn the user and ask to narrow the pattern. Fetch max 30 files per invocation to avoid hitting API rate limits.

Output:

## Inspecting: owner/repo (targeted)
Branch: main | Matched files: 5/342 total

### File: .claude/skills/implement/SKILL.md (2.1 KB)
[full file content]

### File: .claude/skills/fix-loop/SKILL.md (1.8 KB)
[full file content]

---
Inspected 5 files from owner/repo.

Depth Level: DEEP

Shallow clone the repo and run local search across all files.

# Clone with depth 1 (minimal history)
TMPDIR=$(mktemp -d)
gh repo clone OWNER/REPO "$TMPDIR/repo" -- --depth 1 --branch BRANCH 2>/dev/null

Then use Glob and Grep tools on $TMPDIR/repo/ to find files matching --glob and --grep patterns:

# Find files by glob
Glob: pattern="**/*.md" path="$TMPDIR/repo"

# Search content by grep
Grep: pattern="allowed-tools" path="$TMPDIR/repo" glob="*.md"

Read matched files with the Read tool, then clean up:

rm -rf "$TMPDIR"

Output: Same format as Targeted, but potentially more files since full repo is searchable.

Size guard: Before cloning, check repo size:

gh api repos/OWNER/REPO --jq '.size'

If >500000 KB (500 MB), warn the user and ask for confirmation before proceeding.

Multi-Repo Inspect

When the user wants to inspect multiple repos (e.g., "inspect the top 5 from my last search"):

1. Use the Agent tool to launch parallel subagents — one per repo
2. Each subagent runs the inspect workflow independently
3. Aggregate results into a single comparison report:

## Multi-Repo Comparison: "claude code skills"
Inspected 5 repositories

| Repo | Stars | Files Found | Notable Patterns |
|------|-------|-------------|-----------------|
| owner/repo1 | 12.3K | 24 skills | Comprehensive, mode-based |
| owner/repo2 | 3.1K | 8 skills | Focused, minimal |
| ... | ... | ... | ... |

### Detailed Results
[Per-repo output as above]

If the user requests >5 repos, confirm before launching parallel inspections.

Natural Language Examples

File Export

When --output <path> is specified, write the full results as a markdown file:

Write: file_path="<path>" content="<formatted results>"

Report: Results written to <path>

CRITICAL RULES

1. No hardcoded content types — This skill searches for ANY content on GitHub. Never assume the user is searching for skills, agents, or Claude-specific files. Parse their actual query.
2. Rate limit awareness — GitHub API has rate limits (5000 requests/hour authenticated, 60/hour unauthenticated). If gh api returns 403/rate-limit errors, report to the user and suggest gh auth login or waiting.
3. Auth check first — Before any operation, verify gh auth status. If unauthenticated, tell the user to run gh auth login.
4. No credential exposure — Never log or display tokens, API keys, or auth headers.
5. Respect --limit — Never fetch more results than requested. Default 20 for search, max 100. Max 30 files for targeted inspect.
6. Clean up deep clones — Always remove temp directories after deep inspect completes, even on errors.
7. Confirm before bulk operations — If multi-repo inspect would hit >5 repos or deep inspect targets a repo >500 MB, confirm with the user first.
8. Preserve search context — When the user says "inspect the top 3" or "look at the first one", reference results from the most recent Mode 1/Mode 2 output in this session.
9. Omit unused flags — Only include gh CLI flags the user specified. Never pass empty values — this causes search errors.
10. Suggest next steps — After Mode 1/2 results, suggest /github inspect <repo>. After Mode 3, suggest what the user can do with the extracted content.

QUICK REFERENCE