Add github-explore: GitHub search/discovery/audit skill via gh CLI

[Fectivnfy112357]

What it solves

Finding the right repositories on GitHub is noisy: broad searches drown in
high-star general-purpose repos, awesome-list directories mix with real
projects, and search quotas are easy to blow. github-explore packages a
proven discovery workflow — dual-scope semantic search, topic mining,
multi-axis field mapping with signal flags (canonical / awesome / list),
trending, similar projects, code/issue search and org audits — backed by 9
zero-config, stdlib-only Python scripts — so an agent can answer
"what exists and what matters" in one skill.

What it covers

Read-only discovery (9 entry-point scripts, default)

All scripts only call gh search / gh repo view / gh api against
api.github.com; they never create, update, or delete anything.

Script	Purpose
find_repos	Smart repo search with multi-dimensional filters (language, topic, stars, license, pushed-since, dual-scope for multi-word queries)
discover	Auto-expand topics from a seed search (read top results, extract their topics, run per-topic searches)
explore	Multi-axis topic exploration — agent defines 2-4 semantic axes inline, runs in parallel, unions with relevance scoring (canonical anchors + cross-axis hits + log-scaled stars)
trending	Time-windowed trending repos (default 7d; --topic, --language, --min-stars)
repo_summary	Deep dive on a single repo (topics, languages, recent activity, mentionable users, license)
find_similar	Alternatives to a given repo (cross-language option --no-language)
code_search	GitHub code search by pattern (--repo, --org, --owner, --extension, --filename)
search_issues	Issue / PR search (--state, --type, --label, --author, --assignee)
org_landscape	Audit an entire org grouped by language, topic, activity, or stars

Output is layered: stdout ~3KB markdown summary + full report written to
%TEMP%/gh-explore-{topic}-{ts}.md; --format json for pipelines.

Opt-in management (references only, not in scripts)

For things the discovery scripts can't do (create repo, open PR, label,
workflow dispatch, etc.), the skill ships reference docs under
skills/github-explore/references/commands-*.md so an agent can run raw
gh commands safely. The references are organized by domain:

• commands-auth-config.md — auth, config, env vars
• commands-repo-issue-pr.md — repo, issue, PR lifecycle
• commands-cicd.md — workflow, cache, secret, variable, release
• commands-misc.md — org, label, SSH/GPG, gist, codespace, alias, extension
• commands-search-format.md — gh search, JSON/jq/template output, gh api
• SECURITY-NOTES.md — the 4-point consent rule (target / impact /
  minimal data / confirmation) for any write command

Try it

Install from /plugins → Local, then ask:

find repos about vector databases written in Python

Expected result: a ranked, deduplicated list of repositories with
relevance scores, filtered of forks/archived/awesome-list noise, plus a
layered markdown summary (or --format json for pipelines).

Other examples:

what's trending in LLM topics this month
give me an overview of langchain-ai/langchain
find projects similar to vercel/next.js
audit the vercel org by language

Dependencies and platforms

• Python 3.10+ (scripts are zero-dependency stdlib-only)
• gh CLI 2.x, authenticated (gh auth login)
• Network access to your GitHub host — default api.github.com; GH_HOST redirects it (e.g. GitHub Enterprise Server, see "Network and data")

Security model

• Read-only by default. The 9 discovery scripts never call create /
  update / delete / merge / dispatch. They only read.
• Write operations require explicit user consent, across ALL
  commands-*.md. This includes repo/issue/PR/workflow writes,
  commands-auth-config.md auth/config writes (gh auth login/logout/ switch/setup-git/refresh --scopes, gh config set), and
  commands-search-format.md API mutations (gh api --method POST|PUT|DELETE|PATCH, GraphQL mutation). Before any such command
  runs, the agent must state the target (incl. host), the impact (incl.
  credential/config effects and downstream triggers), the minimal data
  being changed, and obtain explicit user confirmation. The full rule
  lives in references/SECURITY-NOTES.md.
• No token exposure. Auth diagnostics use gh auth status only —
  never gh auth token, --show-token, or --with-token.
• Honest error-redaction scope. The 9 discovery scripts internally
  mask credential-shaped stderr via _lib.redact_secrets(). Raw gh
  commands the agent runs directly via the shell are not auto-
  redacted; scripts/redact_stderr.py provides an opt-in pipe
  (gh <cmd> 2>&1 | python scripts/redact_stderr.py). Best-effort only.
• No credentials stored by the plugin. Authentication reuses the
  existing gh CLI token; the plugin requests no scopes and stores nothing.
• No telemetry, no third-party services. Every API call goes to
  your GitHub host via the user's own gh CLI.

Network and data

• All API access is through the user's authenticated gh CLI
  (REST, search, and GraphQL; git remotes only for
  clone/fork). Quota limits apply (search ~30/min, core ~5000/hr) and
  the scripts stay within them (--max-workers 2 default, retry on
  403/429).
• GH_HOST / GitHub Enterprise changes the network destination.
  Default is github.com. GH_HOST=github.acme.com (GHES on-prem) or
  GH_HOST=acme.ghe.com (GHEC tenancy) reroutes all gh API traffic
  there (pure git ops still follow git remote). --hostname is not
  a global flag — it exists only on ~11 subcommands; the universal
  switch is GH_HOST=... gh <cmd>. Credentials are per-host
  (hosts.yml / keyring keyed by host): a PAT for one host does not
  authenticate to another. Env-var tokens follow a strict scope:
  GH_TOKEN/GITHUB_TOKEN are read only for github.com + *.ghe.com
  • github.localhost; GHES on-prem requires
    GH_ENTERPRISE_TOKEN/GITHUB_ENTERPRISE_TOKEN. The skill does not
    validate GH_HOST — the user is responsible for confirming the target
    before any write command runs.
• Permission scope = whatever scopes the user's gh token already has; the
  plugin requests none and stores none.
• Remote side effects are limited to the opt-in write commands the user
  explicitly drives; discovery scripts cause no remote changes.

Test evidence

• node scripts/validate.mjs → OK plugin Fectivnfy112357/github-explore
• python scripts/run_tests.py → 26 tests, all passing
  • argv safety: run_gh uses argv list with shell=None; special
    characters pass through as a single argv element
  • rate limit / pagination: 403/429 retry, gives up at max_attempts,
    non-rate-limit errors return immediately, org_landscape paginates
    public_repos=250 into 100/100/50 in order
  • output schema: find_repos (plural camelCase top-level),
    repo_summary (singular fields under repo key), explore (repos
    nested under axes[i].repos[j]), --schema flag behaviour
  • secret redaction: 5 credential shapes (fine-grained PAT, classic PAT,
    Bearer, key=…, GH_TOKEN=…) redacted on every warn / die /
    gh_json error path; ordinary text passes through intact
• node --test test/github-explore.test.mjs → 1/1 pass (bridge to the
  Python suite, no network, no gh binary required)

[hetaoBackend]

暂不符合收录门禁，主要是 credential 与远端写操作边界：

1. Skill 把“直接 gh 管理操作”列为能力，references 又给出 gh auth token、gh auth status --show-token、secret set/delete、repo/issue/PR/workflow 等写命令。前两者会把凭据打印进 Agent transcript；后者可能改变远端状态，但当前 Skill 没有 preview、目标确认和执行前 consent 规则。
2. 请删除所有展示 token 的命令；认证诊断只允许不回显 token 的 gh auth status。对 create/update/delete/dispatch 等写操作必须明确目标、影响、最小数据和执行前确认；默认 discovery 脚本应保持只读。
3. README/PR 目前只披露 api.github.com 搜索和“no credentials stored”，没有披露 Skill 还覆盖 credential/secret/repository 管理。请把能力、权限范围、远端副作用和数据流写全。
4. 10 个脚本只有 py_compile 与个人日常使用声明，没有可复现回归测试。请至少覆盖参数到 gh argv 的安全构造、分页/限流失败、输出 schema 和错误时不泄露 stderr 中的敏感信息。

validator 通过只代表包形状合规，不能覆盖这些安全行为。

[Fectivnfy112357]

@hetaoBackend 谢谢这次的反馈，4 条都很到位 — credential 暴露面和写操作边界确实是我之前没充分考虑的部分。在 commit 268e020 里逐条修了，麻烦再审一下。

1. token 暴露面：commands-auth-config.md 删除了 gh auth token / --show-token / --with-token 等回显示例；ensure_auth() 只调 gh auth status；新增 _lib.redact_secrets()（5 种凭据形态）并接入 warn / die / gh_json 错误路径。

2. 写操作 consent + 默认只读：4 条纪律（目标 / 影响 / 最小数据 / 确认）抽到新文件 references/SECURITY-NOTES.md 作为唯一定义；3 个写操作 ref（cicd / misc / repo-issue-pr）改为引用该文件，去掉逐字复制；commands-auth-config 保持独立（认证类）；SKILL.md 安全边界小节明确 9 个 entry-point discovery 脚本只读。

3. 披露：README 新增 "Capabilities & permissions" + "Data and network" 两节；plugin.json description 同步；脚本计数统一为 9（与 scripts/ 实际 entry-point 一致）。

4. 测试：4 套 stdlib unittest（argv 安全 / 限流分页 / 输出 schema / stderr 脱敏），由 scripts/run_tests.py 入口 + test/github-explore.test.mjs 接入 node --test。

测试结果：Ran 19 tests in 0.007s — OK；node --test pass 1 fail 0；validate.mjs → OK plugin Fectivnfy112357/github-explore。（hello-mcode 的 FAIL 是上游 main 的 example 缺失 frontmatter，不属于本 PR。）

顺手把 format_table 改成 Column dataclass、redact_secrets 改单循环、is_low_quality 改名 is_excluded。diff 在 feat/github-explore 顶端 268e020，27 files / +598 / -93。

[hetaoBackend]

@Fectivnfy112357 这个 PR 是当前最接近收录的一批，最新 main 合成检查 27/27 通过；还需修复两个写操作安全边界：

1. SECURITY-NOTES.md 的确认规则排除了 commands-auth-config.md，但其中包含 login/logout、切换账号、扩大 scopes、credential helper 和配置写入；commands-search-format.md 也包含创建 issue 的 POST。请把所有 commands-*.md 中的写操作统一纳入“目标、影响、最小数据、用户显式确认”门禁。
2. 文档声称 raw gh 写命令的 stderr 会经过 _lib.redact_secrets()，实际 Agent 直接执行这些命令，并不经过 Python wrapper。请删除该保证，或让写命令真正通过安全 wrapper。

另外请补充 GH_HOST/GitHub Enterprise 会改变网络目的地的披露，并触发 CI/CodeQL。修复后可优先复审。

[Fectivnfy112357]

收到，两处写操作安全边界已修复，GH_HOST 披露也补上了：

1. 写操作门禁覆盖全部 commands-*.md。SECURITY-NOTES.md 适用范围从三个文件扩到全部五个，commands-auth-config.md 里的 login/logout/switch/setup-git/refresh --scopes（含权限提升）、gh config set 配置写入，以及 commands-search-format.md 里的 gh api --method POST/PUT/DELETE/PATCH 和 GraphQL mutation，都纳入"目标（含 host）/影响/最小数据/用户显式确认"四步门禁。五个 commands 文件头部都有指向 SECURITY-NOTES 的警告块。

2. redact 虚假保证已删除。文档不再声称 raw gh 写命令的 stderr 会自动脱敏——agent 直接执行 gh 时确实不经过 Python wrapper。SECURITY-NOTES 现在明确：9 个发现脚本内部走 _lib.redact_secrets()；agent 直接跑的 raw gh 命令，stderr 原样进 transcript，不经过任何 Python 层。

3. GH_HOST / Enterprise 披露。README、SKILL.md、SECURITY-NOTES 补充了：GH_HOST 会改变所有 gh 调用的网络目的地（纯 git 操作除外）、凭据按 host 隔离、GH_TOKEN 只对 github.com / *.ghe.com 生效而 GHES on-prem 需 GH_ENTERPRISE_TOKEN。

最新提交 8cb32f2，CI 与 CodeQL 均已通过。麻烦再复审，谢谢。

[hetaoBackend]

已复核当前 head 8cb32f2。此前的写入确认范围、鉴权配置修改和 stderr 披露问题均已修复；候选分支本地完整检查 13/13 通过，当前 CI 与 CodeQL 全绿。批准合入。