English · 简体中文

auto-github-contributor

A Claude Code skill + slash command that takes any GitHub repo and drives a full OSS contribution pipeline end-to-end: discover a quick-win candidate (labeled issues + repo scan), run a TDD dev-loop until lint/typecheck/tests all pass, then open a PR via gh and print the URL.

One slash command, full pipeline, any repo.

---

Overview

When you invoke /auto-contribute inside Claude Code, the skill runs an 11-step interactive playbook:

1. Prereqs — verify gh, git, jq are installed and gh auth status is green.
2. Target repo — accept owner/name or a GitHub URL (or ask interactively).
3. Discover candidates in parallel:
   • Labeled issues (good first issue, help wanted, documentation, …)
   • Repo-scan quick wins: typos, missing tests, i18n gaps, actionable TODOs
4. Ranked picklist with estimated time + LLM cost per item.
5. Wait for explicit user confirmation before touching anything.
6. Isolate a workdir + feature branch under $AGC_WORK_ROOT.
7. Write SPEC.md + TODO.md from templates.
8. TDD dev-loop per todo (red → green → refactor), capped at 20 iterations.
9. Final verification: clean install + lint + typecheck + tests + build.
10. Commit, push, open PR via gh pr create. Prefers TARGET_FORK over upstream.
11. Print the PR URL on its own line.

Safety rails: never force-push, never commit to main/master/develop, never rm -rf outside $AGC_WORK_ROOT, never post to external systems unasked.

Requirements

• gh (GitHub CLI) — authenticated (gh auth login, repo scope)
• git
• jq
• Claude Code

Optional but nice to have:

• rg (ripgrep) — the scanner falls back to grep when absent
• pnpm / yarn / npm / bun — autodetected from the target repo's lockfile
• python3 — used by create-pr.sh to render the PR body template

Installation

This repo ships the slash command (commands/auto-contribute.md) and the skill (skills/auto-github-contributor/) as plain files — no plugin manifest, no marketplace registration. Drop them into Claude Code's user or project directory and they're live.

A. User-level (recommended — available in every project)

git clone https://github.com/nexu-io/auto-github-contributor.git /tmp/auto-github-contributor
mkdir -p ~/.claude/commands ~/.claude/skills
cp    /tmp/auto-github-contributor/commands/auto-contribute.md  ~/.claude/commands/
cp -R /tmp/auto-github-contributor/skills/auto-github-contributor ~/.claude/skills/

Restart Claude Code. /auto-contribute appears as a slash command, and Claude can also invoke the auto-github-contributor skill by name.

B. Project-level (scoped to one repo)

From the target repo's root:

git clone https://github.com/nexu-io/auto-github-contributor.git /tmp/auto-github-contributor
mkdir -p .claude/commands .claude/skills
cp    /tmp/auto-github-contributor/commands/auto-contribute.md  .claude/commands/
cp -R /tmp/auto-github-contributor/skills/auto-github-contributor .claude/skills/

The command and skill are then available only inside that project.

C. Skill-only (no slash command)

If you don't want the /auto-contribute command — just the skill — drop skills/auto-github-contributor/ into ~/.claude/skills/ (or .claude/skills/) alone. Invoke it by asking Claude to "auto-contribute to <repo>" or similar; the description in SKILL.md handles trigger words.

Usage

/auto-contribute                               # skill will ask for the repo
/auto-contribute cli/cli                       # owner/name form
/auto-contribute https://github.com/cli/cli    # URL form

Override defaults via env vars before launching Claude Code (or export them in your shell profile):

Variable	Default	Purpose
TARGET_REPO	(prompted)	owner/name of the upstream
TARGET_FORK	(empty → push to origin)	Where to push the feature branch
AGC_BASE_BRANCH	main	Base branch for the PR
AGC_WORK_ROOT	$HOME/auto-gh-contrib-work	Where workdirs get cloned
AGC_LABELS	good first issue,help wanted,documentation,good-first-issue	Issue labels to search
AGC_ISSUE_LIMIT	30	Max issues per label
AGC_INSTALL_CMD / AGC_LINT_CMD / AGC_TYPECHECK_CMD / AGC_TEST_CMD / AGC_BUILD_CMD	pnpm-flavored	Fallback dev-loop commands (overridden by lockfile detection)
AGC_DEV_URL	http://localhost:5173	URL for browser-verify stub

How to test

The skill has three testable layers. Start with Layer 1 — it's cheap, deterministic, and covers most of the real surface area.

Layer 1 — Script smoke tests (read-only, safe)

All scripts live in skills/auto-github-contributor/scripts/ and emit KEY=VAL lines or JSON. You can drive each one directly.

SKILL_DIR=skills/auto-github-contributor/scripts

# 1. Prerequisites
bash "$SKILL_DIR/check-prereqs.sh"
# expect: ✓ gh / ✓ git / ✓ jq / ✓ gh authed as <you>; exit 0

# 2. Issue discovery against a real repo
TARGET_REPO=cli/cli AGC_ISSUE_LIMIT=3 bash "$SKILL_DIR/fetch-issues.sh" \
  | jq '.[] | {number, title, score, labels}'
# expect: ranked array of open issues matching the configured labels

# 3. Quick-win scanner against any clone
SCRATCH=/tmp/agc-smoke && rm -rf "$SCRATCH" \
  && git clone --depth 1 https://github.com/expressjs/express.git "$SCRATCH"
bash "$SKILL_DIR/scan-quick-wins.sh" --workdir "$SCRATCH" --max 20 \
  | jq 'group_by(.kind) | map({kind: .[0].kind, count: length})'
# expect: an array with some of {typo, missing-test, i18n, todo}

# 4. Parse-check the scripts that mutate state
bash -n "$SKILL_DIR/setup-workspace.sh"
bash -n "$SKILL_DIR/dev-loop-check.sh"
bash -n "$SKILL_DIR/create-pr.sh"
bash -n "$SKILL_DIR/browser-verify.sh"

Layer 2 — Slash command + skill loading

In a Claude Code session at the repo root, type /auto-contribute and verify:

• the slash command autocompletes (proves commands/auto-contribute.md is registered),
• Claude immediately invokes the auto-github-contributor skill,
• it runs check-prereqs.sh first,
• it asks for the target repo via AskUserQuestion,
• it fetches issues and scans quick-wins in parallel,
• it renders a picklist with time/cost estimates and stops for confirmation.

You can cancel at the picklist — no workdir is created beyond a _scratch shallow clone.

Layer 3 — End-to-end on a sandbox repo

Create a throwaway repo you own (e.g. your-handle/agc-sandbox) with a known quick-win seeded — for instance, write # Teh setup guide (note Teh) in README.md. Then:

/auto-contribute your-handle/agc-sandbox

Pick the typo from the list, approve, and let the skill drive through to a real PR. Close the PR once you've verified the flow.

Tip: set TARGET_FORK=your-handle/agc-sandbox so it pushes to the same repo (branch) instead of prompting about origin.

How it works

commands/auto-contribute.md         # /auto-contribute slash command (thin wrapper)
skills/auto-github-contributor/
  SKILL.md                          # orchestration playbook Claude reads
  scripts/
    config.sh                       # shared env + helpers
    check-prereqs.sh                # gh/git/jq + auth check
    fetch-issues.sh                 # label-based issue discovery + ranking
    scan-quick-wins.sh              # typo / missing-test / i18n / TODO scanner
    setup-workspace.sh              # clone + feature branch
    dev-loop-check.sh               # red/green/final phases, lockfile-aware
    browser-verify.sh               # visual-verification stub
    create-pr.sh                    # commit, push, open PR, render body
  templates/
    SPEC.template.md                # problem / acceptance / approach / risk
    TODO.template.md                # atomic todos mirrored to TaskCreate
    PR-BODY.template.md             # rendered into .auto-pr/PR-BODY.md

The skill file (SKILL.md) is the contract Claude follows. The scripts do the real work; Claude only orchestrates, reads their output, and makes decisions at the branching points.

How to contribute

Contributions welcome. The most valuable additions right now:

1. New quick-win kinds — extend scan-quick-wins.sh. Good targets:
   • broken markdown links
   • unused exports (ts-prune-style)
   • missing JSDoc on public APIs
   • outdated dependency pins in a package.json section
2. Browser-verify backend — browser-verify.sh is a deliberate stub. Wire up a Playwright / Puppeteer / chrome-devtools MCP backend so UI changes get screenshotted before the PR.
3. Language/framework dev-loops — dev-loop-check.sh currently detects JS package managers. Add Python (uv/poetry/pip), Go, Rust, etc.
4. Cost estimator — the picklist cost numbers are hand-waved rules of thumb. A smarter estimator (token-weighted file size × action kind) would help users pick more confidently.

Guidelines

• Scripts emit machine-readable output. Stdout is KEY=VAL lines or JSON. Human logs go to stderr via agc::log / agc::err. Don't mix them.
• No silent stubs. If a feature isn't wired up yet, print stub: <reason> so the PR body can surface the caveat.
• Safety rails stay on. Never force-push, never commit to main/master/develop, never rm -rf outside $AGC_WORK_ROOT. If you add a new mutation path, add the guard too.
• Config via env vars. New tunables go into config.sh with a sensible default and an entry in the README table above.
• Shell style. set -euo pipefail (relax only where explicitly justified, as in scan-quick-wins.sh). Prefer $(...) over backticks. Quote expansions.

Local dev loop

# parse-check all scripts
for f in skills/auto-github-contributor/scripts/*.sh; do bash -n "$f" || exit 1; done

# smoke the scanner against a local clone
bash skills/auto-github-contributor/scripts/scan-quick-wins.sh --workdir /path/to/some/repo | jq .

# run shellcheck if you have it installed
shellcheck skills/auto-github-contributor/scripts/*.sh

Filing issues

• Include the Claude Code version, OS, and gh --version.
• Paste the stderr log from the failing script (the [auto-gh] lines are the useful ones).
• If the issue is in discovery, include TARGET_REPO — different repos expose very different label sets.

PR checklist

• bash -n passes for every touched script
• Script output still follows the stdout-is-data / stderr-is-log split
• New env vars documented in README.md and defaulted in config.sh
• Safety rails not weakened
• If you touched SKILL.md, re-read it end-to-end — Claude follows it literally

License

MIT — see LICENSE.