|
| 1 | +# github-explore |
| 2 | + |
| 3 | +> Discovery + management wrappers around the `gh` CLI for AI coding agents. |
| 4 | +
|
| 5 | +[](LICENSE) |
| 6 | +[](https://www.python.org/) |
| 7 | +[](#the-scripts) |
| 8 | +[](scripts/schemas) |
| 9 | +[](https://cli.github.com/) |
| 10 | + |
| 11 | +[English](README.md) · [简体中文](README_zh.md) |
| 12 | + |
| 13 | +--- |
| 14 | + |
| 15 | +## What is this |
| 16 | + |
| 17 | +`github-explore` is an agent skill that turns "search GitHub for X" into structured, deduplicated, relevance-scored output. It wraps `gh search` and `gh repo view` with smart filters, semantic multi-axis exploration, and layered output designed to keep an agent's context window small. |
| 18 | + |
| 19 | +When you ask an agent *"find multi-agent collaboration repos"*, you don't want a star-sorted dump of ollama, langchain, and a bunch of unrelated generic LLM frameworks. You want the canonical anchors (crewAI, autogen, MetaGPT, langgraph, camel, ChatDev, AutoGPT) surfaced first, with the protocol layer (A2A, ANP, ag-ui) as a separate axis, and `awesome-*` lists pushed to the bottom. That's what this skill does. |
| 20 | + |
| 21 | +--- |
| 22 | + |
| 23 | +## Why it exists |
| 24 | + |
| 25 | +Plain `gh search` has three structural problems for agent-driven research: |
| 26 | + |
| 27 | +1. **Star-sorted default = giant noise.** A query for `"multi-agent"` returns ollama (180k★) and langchain (140k★) on top because GitHub sorts by popularity, not topical fit. |
| 28 | +2. **No semantic axes.** "Search repos about Y" is a one-dimensional query. Real topics have multiple semantic facets (frameworks vs. protocols vs. patterns) that should be explored in parallel and then unioned. |
| 29 | +3. **Output floods context.** `gh search repos --json` returns full bodies, dates, and license objects per repo. Piping 50 of these into an LLM wastes thousands of tokens. |
| 30 | + |
| 31 | +`github-explore` addresses all three with a thin layer of Python around `gh`. |
| 32 | + |
| 33 | +--- |
| 34 | + |
| 35 | +## Key features |
| 36 | + |
| 37 | +- **Multi-axis exploration** — `explore.py` lets the agent define 2-4 semantic axes per topic, runs them in parallel, and unions results with a relevance score that combines cross-axis hits, canonical anchor recall, and awesome-list signals. |
| 38 | +- **Smart defaults** — every discovery script filters forks and archived repos by default, enforces a minimum star floor, dedupes by `fullName`, and renders in a layered markdown summary (~3KB stdout). |
| 39 | +- **Layered output** — full reports go to `%TEMP%/gh-explore-{topic}-{ts}.md` automatically; the agent reads the summary, and pulls the file only when it needs more detail. Default exploration drops your context from ~18KB to ~2KB. |
| 40 | +- **Field-level contract** — `python scripts/<script>.py --schema` prints the output JSON structure for the four scripts that support it; the other six read their contract from `scripts/schemas/*.schema.json`. |
| 41 | +- **No new CLI surface** — every script is a wrapper over `gh search` or `gh repo view`. You can drop the skill and run the same `gh` commands by hand; the value is in the filter, dedup, and relevance scoring. |
| 42 | + |
| 43 | +--- |
| 44 | + |
| 45 | +## Quick start |
| 46 | + |
| 47 | +```bash |
| 48 | +# 1. Install the skill (Claude Code, Codex, Cursor, and 15+ agent CLIs) |
| 49 | +npx skills add Fectivnfy112357/github-explore |
| 50 | + |
| 51 | +# Hermes Agent users |
| 52 | +hermes skills install https://raw.githubusercontent.com/Fectivnfy112357/github-explore/main/SKILL.md --force |
| 53 | + |
| 54 | +# 2. Make sure gh CLI is authenticated |
| 55 | +gh auth status |
| 56 | + |
| 57 | +# 3. Try it — scripts live under the installed skill dir (e.g. ~/.claude/skills/github-explore/) |
| 58 | +cd ~/.claude/skills/github-explore |
| 59 | +python scripts/find_repos.py "vector database" --language python --min-stars 500 |
| 60 | +python scripts/explore.py "multi-agent" \ |
| 61 | + --axis "framework|multi-agent framework in:readme; collaborative agents in:readme" \ |
| 62 | + --axis "protocol|A2A agent protocol in:readme; agent-to-agent communication in:readme" |
| 63 | +``` |
| 64 | + |
| 65 | +Each command writes a layered markdown summary to stdout (~3KB) and a full report to a temp file. Pass `--format json` for machine-readable output (explicit; piping does **not** auto-switch). |
| 66 | + |
| 67 | +--- |
| 68 | + |
| 69 | +## The scripts |
| 70 | + |
| 71 | +| Script | Purpose | `--schema` | Notes | |
| 72 | +|---|---|---|---| |
| 73 | +| `find_repos.py` | Smart repo search with multi-dimensional filters | ✅ | Default entry point. Multi-word free-text runs dual-scope (`in:readme` + default) for conceptual recall. | |
| 74 | +| `explore.py` | Multi-axis topic exploration | ✅ | Agent defines axes inline. Outputs canonical anchors + cross-axis hits + top 5/axis. | |
| 75 | +| `discover.py` | Auto-expand topics from a seed search | ❌ | Reads top seed results, extracts their topics, runs per-topic searches. Fast, opportunistic. | |
| 76 | +| `trending.py` | Time-windowed trending repos | ❌ | Default 7d window; supports `--topic`, `--language`, `--min-stars`. | |
| 77 | +| `repo_summary.py` | Deep dive on a single repo | ✅ | Topics, languages, recent activity, mentionable users, license. | |
| 78 | +| `find_similar.py` | Alternatives to a given repo | ❌ | Cross-language option (`--no-language`). | |
| 79 | +| `code_search.py` | GitHub code search by pattern | ❌ | `--repo`, `--org`, `--owner`, `--extension`, `--filename`. | |
| 80 | +| `search_issues.py` | Issue/PR search | ❌ | `--state`, `--type`, `--label`, `--author`, `--assignee`. | |
| 81 | +| `org_landscape.py` | Audit an entire org | ❌ | `--group-by {language,topic,activity,stars}`. | |
| 82 | +| `_lib.py` | Shared helpers | n/a | `ensure_auth`, `gh_json`, `parse_since`, `print_schema`. Not for direct use. | |
| 83 | +| `__init__.py` | Module docstring | n/a | Documents the scripts package. | |
| 84 | + |
| 85 | +**`--schema` gap:** 6 of 11 scripts don't yet expose `--schema` as a CLI flag. The schema files for those 6 are still pending in `scripts/schemas/`. Until they're added, the four scripts with `--schema` and the existing `repo.schema.json` / `explore.schema.json` / `repo_summary.schema.json` files cover the most-used paths. |
| 86 | + |
| 87 | +--- |
| 88 | + |
| 89 | +## Architecture |
| 90 | + |
| 91 | +``` |
| 92 | + ┌─────────────────────────────────────────────┐ |
| 93 | + │ Agent (LLM, coder, etc.) │ |
| 94 | + │ - reads SKILL.md for trigger + protocol │ |
| 95 | + │ - decides which script + which axes │ |
| 96 | + └──────────────────┬──────────────────────────┘ |
| 97 | + │ python scripts/<name>.py [args] |
| 98 | + ▼ |
| 99 | + ┌────────────────────────────────────────────────────┐ |
| 100 | + │ scripts/ (10 entry points + _lib + __init__) │ |
| 101 | + │ ─────────────────────────────────────────────────│ |
| 102 | + │ find_repos explore discover trending │ |
| 103 | + │ repo_summary find_similar code_search │ |
| 104 | + │ search_issues org_landscape │ |
| 105 | + │ │ |
| 106 | + │ shared: _lib.ensure_auth, _lib.gh_json, │ |
| 107 | + │ _lib.print_schema, _lib.parse_since │ |
| 108 | + └──────────────────┬─────────────────────────────────┘ |
| 109 | + │ subprocess.run(['gh', ...]) |
| 110 | + ▼ |
| 111 | + ┌────────────────────────────────────────────────────┐ |
| 112 | + │ gh CLI (search repos / repo view / search code) │ |
| 113 | + │ Authenticated via gh auth status. │ |
| 114 | + └──────────────────┬─────────────────────────────────┘ |
| 115 | + │ |
| 116 | + ▼ |
| 117 | + ┌────────────────────────────────────────────────────┐ |
| 118 | + │ GitHub REST + Search API │ |
| 119 | + │ ~5000/hr core / ~30/min search (authenticated) │ |
| 120 | + └────────────────────────────────────────────────────┘ |
| 121 | +
|
| 122 | + Output: |
| 123 | + - stdout: ~3KB layered markdown summary (default) |
| 124 | + - stdout: full JSON when --format json (explicit) |
| 125 | + - disk: %TEMP%/gh-explore-{topic}-{ts}.md (always) |
| 126 | +``` |
| 127 | + |
| 128 | +**Two layers, one mental model.** Scripts handle discovery (search / dedup / score / render). Direct `gh` calls handle management (create / update / merge / label / workflow). The `references/commands-*.md` files document the management side without bloating `SKILL.md`. |
| 129 | + |
| 130 | +--- |
| 131 | + |
| 132 | +## When to use what |
| 133 | + |
| 134 | +| Task | Tool | |
| 135 | +|---|---| |
| 136 | +| Find repos about a topic | `find_repos.py "<query>"` | |
| 137 | +| Map a field's full landscape | `explore.py "<topic>" --axis ...` | |
| 138 | +| Auto-expand into related topics | `discover.py "<seed>"` | |
| 139 | +| See what shipped recently | `trending.py --window 7d` | |
| 140 | +| Read up on one repo | `repo_summary.py owner/repo` | |
| 141 | +| Find alternatives | `find_similar.py owner/repo` | |
| 142 | +| Where is this pattern used? | `code_search.py "<pattern>" --org ...` | |
| 143 | +| Search issues / PRs | `search_issues.py "<query>"` | |
| 144 | +| Audit an org | `org_landscape.py <org>` | |
| 145 | +| Create a repo, open a PR, label, run CI | `gh <command>` (see `references/commands-*.md`) | |
| 146 | + |
| 147 | +--- |
| 148 | + |
| 149 | +## Design decisions worth knowing |
| 150 | + |
| 151 | +These are the non-obvious calls the skill makes, surfaced so you don't have to reverse-engineer them: |
| 152 | + |
| 153 | +1. **`in:readme` is the default for multi-word free text.** Description is too short to disambiguate topics. `find_repos` runs two scopes and unions, with a relevance bonus for `in:readme` hits to keep canonical small projects above generic big repos. |
| 154 | +2. **`--exclude` is a post-filter, not a query token.** GitHub's `-term` exclusion is unreliable for awesome lists and tutorials; this skill filters at the merge stage on `fullName` / `description` substrings. |
| 155 | +3. **`awesome-*` directories are tagged `☰list` and heavily demoted**, not deleted. They're a different artifact (curation vs. code) and should appear below real projects but still be findable. |
| 156 | +4. **Star sorting is a fallback, not a default.** `explore.py` orders by a relevance score that combines canonical-anchor recall, cross-axis hits, and a log-scaled star count. A 100★ canonical anchor always beats a 200k★ repo that merely mentions the topic. |
| 157 | +5. **Output is layered, not inlined.** Stdout stays under ~3KB; full results go to a temp file. This is the single biggest context-saver when an agent loops through multiple topics. |
| 158 | + |
| 159 | +--- |
| 160 | + |
| 161 | +## Contributing |
| 162 | + |
| 163 | +Issues and pull requests are welcome. This is a personal skill that's been refactored over multiple real uses; the test surface is the scripts themselves, not a unit-test suite. |
| 164 | + |
| 165 | +Before opening a PR: |
| 166 | + |
| 167 | +1. Make sure the affected scripts still pass `python scripts/<name>.py --help` and (where supported) `--schema`. |
| 168 | +2. If you add a new script, add a row to the [scripts table](#the-scripts) and consider whether it needs a schema file under `scripts/schemas/`. |
| 169 | +3. Keep the layered-output convention: stdout summary + temp-file full report, no exceptions. |
| 170 | + |
| 171 | +--- |
| 172 | + |
| 173 | +## License |
| 174 | + |
| 175 | +MIT. See [LICENSE](LICENSE). |
| 176 | + |
| 177 | +## Credits |
| 178 | + |
| 179 | +Built and maintained by 贾晓源 ([@Fectivnfy112357](https://github.com/Fectivnfy112357)). |
0 commit comments