Skip to content

feat(skills): add anonymous-first GitHub research skill (#4267 item 4) - #4739

Closed
liugddx wants to merge 1 commit into
apache:mainfrom
liugddx:feat/github-research-skill
Closed

feat(skills): add anonymous-first GitHub research skill (#4267 item 4)#4739
liugddx wants to merge 1 commit into
apache:mainfrom
liugddx:feat/github-research-skill

Conversation

@liugddx

@liugddx liugddx commented Sep 4, 2026

Copy link
Copy Markdown
Member

What

Adds an anonymous-first GitHub research skill (skills/maka-github-research/) that gives Maka one dependable route for inspecting public repositories — issues, PRs, discussions, comments, timelines — without local CLI credentials, HTML scraping, or several custom parsers.

Delivers item 4 ("Structured public GitHub research") of the harness friction umbrella #4267, which is marked "Open; no focused delivery issue yet" and asks specifically for "an unauthenticated-first GitHub research skill/plugin before promoting a forge adapter into core."

Why (evidence from #4267)

A real extended Maka session had to improvise this chain for ordinary public research:

gh search401 → anonymous REST → discover Maka-Agent/maka-agentapache/maka redirect → REST issue fetch → Discussions GraphQL required auth → scrape GitHub HTML → extract Discussion links → fetch each page → extra REST calls for author/state/labels/comments.

Each symptom was reproduced against apache/maka while writing this skill:

Symptom in #4267 Reproduced Skill's answer
Repo redirect Maka-Agent/maka-agentapache/maka 301 → resolves to full_name: apache/maka Resolve canonical repo as step 0
gh search returned 401 (stale local token) — (documented failure-classification row) Drop to anonymous REST immediately
Discussions via GraphQL required auth anonymous POST /graphql403 Sanctioned auth exception + escalation, not scraping
No predictable anonymous budget /rate_limitX-RateLimit-Limit: 60, headers present Record Remaining/Reset evidence in every answer
Metadata scattered / scraped /issues/4267 returns state, labels, comments: 5 as JSON Read metadata from the API, never HTML

(Notably, the REST API reports comments: 5 on #4267 where a WebFetch of the page reported "no comments" — the API is authoritative, which is exactly the skill's point.)

Contents

  • SKILL.md — core principle (anonymous-first, escalate on 401/403 evidence), the resolve→pick-endpoint→paginate→collect→evidence workflow, the Discussions exception, and non-goals.
  • references/rest-recipes.md — copy-paste, tested anonymous recipes: canonical resolution, single issue/PR, comments, timeline (linked work / labels), repo-scoped search, PR files + unified diff, repo facts, and the authenticated Discussions GraphQL query.
  • references/rate-limits-and-escalation.md — anonymous budgets, an evidence-header table, a failure-classification table (rate-limited vs forbidden vs renamed vs empty), the escalation ladder, and how to add a token without leaking it.

Scope discipline (per #4267)

  • No new authority. Runs entirely on tools Maka already exposes (ShellRun/curl, gh, WebFetch). It is a research recipe layer, not a forge adapter and not a new permission/network surface.
  • No credentials in context. Tokens come from the environment / gh keyring and are never echoed.
  • Unauthenticated-first, exactly the precursor the umbrella wants before any adapter is promoted into core.

Test / verification

All recipes were exercised against apache/maka from an unauthenticated client (curl only). Endpoint behavior verified: canonical redirect, /issues/{n}, /search/issues (200), /pulls/{n}/files, /rate_limit headers, and anonymous /graphql (403). The reference notes jq-free fallbacks (gh api --jq, python3 -m json.tool) since jq is not guaranteed present.

Refs #4267

Delivers the "structured public GitHub research" item of the harness
friction umbrella (apache#4267, item 4). A real extended session had
to improvise a fragile chain for ordinary public research: gh search ->
401 -> anonymous REST -> repository redirect discovery -> REST fetch ->
GraphQL auth failure -> HTML scraping -> link extraction -> per-page
fetch -> extra metadata calls.

This skill replaces that with one dependable route:
- resolve canonical repository redirects first (Maka-Agent/maka-agent ->
  apache/maka) so every later call targets the real repo;
- prefer unauthenticated REST for issues, PRs, comments, timelines, and
  search; recover author/state/labels/linked-work from JSON instead of
  scraping HTML;
- treat GitHub Discussions as the sanctioned auth exception (anonymous
  GraphQL returns 403) with a documented escalation, not a scrape;
- record X-RateLimit evidence and classify 401/403/404/redirect failures
  so an empty result is never reported as "nothing found".

No new capability, permission, or network authority: it runs on tools
Maka already exposes (ShellRun/curl, gh, WebFetch) and never embeds
credentials in the model context. It is the unauthenticated-first
precursor the umbrella asks for before any forge adapter is promoted
into core.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@github-actions github-actions Bot added the effort/M Under 500 readable lines label Sep 4, 2026
@liugddx

liugddx commented Sep 4, 2026

Copy link
Copy Markdown
Member Author

Closing: a skill is not the right vehicle for this. Structured public GitHub research (issue #4267 item 4) may instead live in a separate repo or a public skill repo. Withdrawing to avoid adding low-value surface here.

@liugddx liugddx closed this Sep 4, 2026
@liugddx
liugddx deleted the feat/github-research-skill branch September 4, 2026 07:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

effort/M Under 500 readable lines

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant