Fectivnfy112357/github-explore

Discovery + management wrappers around the gh CLI for AI coding agents.

English · 简体中文

---

What is this

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.

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.

---

Why it exists

Plain gh search has three structural problems for agent-driven research:

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

github-explore addresses all three with a thin layer of Python around gh.

---

Key features

• 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.
• 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).
• 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.
• Field-level contract — python scripts/<script>.py --schema prints the output JSON structure for the three scripts that support it (find_repos, explore, repo_summary), backed by the schema files in skills/github-explore/scripts/schemas/. The other scripts' JSON mirrors gh search's native camelCase fields (documented in skills/github-explore/references/commands-search-format.md).
• 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.

---

Quick start

# 1. Install the skill (Claude Code, Codex, Cursor, and 15+ agent CLIs)
npx skills add Fectivnfy112357/github-explore

# Hermes Agent users
hermes skills install https://raw.githubusercontent.com/Fectivnfy112357/github-explore/main/skills/github-explore/SKILL.md --force

# 2. Make sure gh CLI is authenticated
gh auth status

# 3. Try it — scripts live under the installed skill dir (e.g. ~/.claude/skills/github-explore/)
cd ~/.claude/skills/github-explore
python scripts/find_repos.py "vector database" --language python --min-stars 500
python scripts/explore.py "multi-agent" \
  --axis "framework|multi-agent framework in:readme; collaborative agents in:readme" \
  --axis "protocol|A2A agent protocol in:readme; agent-to-agent communication in:readme"

Install as a DeepSeek Harness (dsh) plugin

The same repo is also a dsh profile bundle: its package.json declares dsh.bundle.patch, so it installs like any other dsh plugin and registers the skill at runtime (no manual file copying). dsh plugin forwards its argument to pnpm, so any pnpm spec works — shortest forms first:

# GitHub shorthand (no publish needed) — shortest
dsh plugin --profile web add Fectivnfy112357/github-explore

# Full git URL
dsh plugin --profile web add git+https://github.com/Fectivnfy112357/github-explore.git

# Bare npm name — after this package is published (npm publish)
dsh plugin --profile web add github-explore

# Local checkout / path / tarball (same flow)
dsh plugin --profile web add /path/to/github-explore

After a profile restart, the github-explore skill appears in the agent's catalog — the plugin (lib/index.js) parses skills/github-explore/SKILL.md and registers it with ctx.skills, with resourceBase pointing at the skill directory so the skill body's scripts/ / references/ paths keep working. Remove with dsh plugin --profile web remove github-explore.

Install as an Agent Plugins 1.0 plugin

The repo is also an Agent Plugins 1.0 package: plugin.json declares the manifest and the skill lives (self-contained, with its scripts/ and references/) at the fixed skills/github-explore/ location. Any Agent Plugins 1.0-compatible client (ChatGPT, Codex, Cursor, GitHub Copilot, Kiro, VS Code, …) can load it directly from the repo (https://github.com/Fectivnfy112357/github-explore) or from a locally checked-out copy — no extra build step:

git clone https://github.com/Fectivnfy112357/github-explore.git
# point your client at the repo root: plugin.json + skills/github-explore/SKILL.md

One repo, three install paths — npx skills add (standard skills), dsh plugin --profile web add (DeepSeek Harness), and any Agent Plugins 1.0 client all read the same files.

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).

---

Repository layout

A single repo serves all three packaging formats; the skill is self-contained under the Agent Plugins fixed location so it works identically no matter which installer copies it:

github-explore/
├── plugin.json                    # Agent Plugins 1.0 manifest ($schema + name required)
├── skills/
│   └── github-explore/            # the one skill, fully self-contained
│       ├── SKILL.md               #   skill body (frontmatter: name/description)
│       ├── scripts/               #   9 entry scripts + _lib.py + schemas/
│       └── references/            #   gh command references (commands-*.md)
├── package.json                   # dsh plugin (dsh.bundle.patch) + npm metadata
├── cordis.patch.yml               # dsh loader patch (inserts the skill entry)
├── lib/index.js                   # dsh plugin: registers the skill via ctx.skills
├── README.md / README_zh.md
└── LICENSE

• Agent Plugins 1.0 reads plugin.json + skills/<name>/SKILL.md (+ optional mcp.json).
• dsh reads package.json → dsh.bundle.patch → cordis.patch.yml → lib/index.js.
• npx skills add discovers skills/<name>/SKILL.md and installs the whole skill directory (scripts + references included).

---

The scripts

Script	Purpose	--schema	Notes
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.
explore.py	Multi-axis topic exploration	✅	Agent defines axes inline. Outputs canonical anchors + cross-axis hits + top 5/axis.
discover.py	Auto-expand topics from a seed search	❌	Reads top seed results, extracts their topics, runs per-topic searches. Fast, opportunistic.
trending.py	Time-windowed trending repos	❌	Default 7d window; supports --topic, --language, --min-stars.
repo_summary.py	Deep dive on a single repo	✅	Topics, languages, recent activity, mentionable users, license.
find_similar.py	Alternatives to a given repo	❌	Cross-language option (--no-language).
code_search.py	GitHub code search by pattern	❌	--repo, --org, --owner, --extension, --filename.
search_issues.py	Issue/PR search	❌	--state, --type, --label, --author, --assignee.
org_landscape.py	Audit an entire org	❌	--group-by {language,topic,activity,stars}.
_lib.py	Shared helpers	n/a	ensure_auth, gh_json, parse_since, print_schema. Not for direct use.
__init__.py	Module docstring	n/a	Documents the scripts package.

--schema gap: 6 of 9 scripts don't yet expose --schema as a CLI flag. The three scripts that do — find_repos, explore, repo_summary — cover the most-used paths, backed by repo.schema.json / explore.schema.json / repo_summary.schema.json.

---

Architecture

                  ┌─────────────────────────────────────────────┐
                  │           Agent (LLM, coder, etc.)         │
                  │  - reads SKILL.md for trigger + protocol   │
                  │  - decides which script + which axes       │
                  └──────────────────┬──────────────────────────┘
                                     │ python scripts/<name>.py [args]
                                     ▼
            ┌────────────────────────────────────────────────────┐
            │  skills/github-explore/scripts/                   │
            │  (9 entry points + _lib + __init__)               │
            │  ─────────────────────────────────────────────────│
            │  find_repos   explore   discover   trending       │
            │  repo_summary find_similar code_search            │
            │  search_issues org_landscape                       │
            │                                                    │
            │  shared: _lib.ensure_auth, _lib.gh_json,           │
            │          _lib.print_schema, _lib.parse_since       │
            └──────────────────┬─────────────────────────────────┘
                               │ subprocess.run(['gh', ...])
                               ▼
            ┌────────────────────────────────────────────────────┐
            │  gh CLI  (search repos / repo view / search code)  │
            │  Authenticated via gh auth status.                 │
            └──────────────────┬─────────────────────────────────┘
                               │
                               ▼
            ┌────────────────────────────────────────────────────┐
            │  GitHub REST + Search API                          │
            │  ~5000/hr core / ~30/min search (authenticated)    │
            └────────────────────────────────────────────────────┘

            Output:
            - stdout:  ~3KB layered markdown summary (default)
            - stdout:  full JSON when --format json (explicit)
            - disk:    %TEMP%/gh-explore-{topic}-{ts}.md (always)

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.

---

When to use what

Task	Tool
Find repos about a topic	find_repos.py "<query>"
Map a field's full landscape	explore.py "<topic>" --axis ...
Auto-expand into related topics	discover.py "<seed>"
See what shipped recently	trending.py --window 7d
Read up on one repo	repo_summary.py owner/repo
Find alternatives	find_similar.py owner/repo
Where is this pattern used?	code_search.py "<pattern>" --org ...
Search issues / PRs	search_issues.py "<query>"
Audit an org	org_landscape.py <org>
Create a repo, open a PR, label, run CI	gh <command> (see references/commands-*.md)

---

Design decisions worth knowing

These are the non-obvious calls the skill makes, surfaced so you don't have to reverse-engineer them:

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

---

Contributing

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.

Before opening a PR:

1. Make sure the affected scripts still pass python scripts/<name>.py --help and (where supported) --schema.
2. If you add a new script, add a row to the scripts table and consider whether it needs a schema file under skills/github-explore/scripts/schemas/.
3. Keep the layered-output convention: stdout summary + temp-file full report, no exceptions.

---

License

MIT. See LICENSE.

Credits

Built and maintained by 贾晓源 (@Fectivnfy112357).