burn-usage-skill

A reusable skill + tooling for running an LLM-driven open-source contribution drive: burning otherwise-idle model-subscription quota on genuine, mergeable GitHub work.

It was extracted from a live run of ~40+ merged PRs across ~30 small repos, with 0 quality rejections — every rule in SKILL.md is scar tissue from that run, with the specific war-story inlined where it's load-bearing. It's written for an agent harness (e.g. Claude Code) where a lead session dispatches implementer and verifier subagents, plus the gh CLI authenticated as your contribution account.

What's here

File	Purpose
SKILL.md	The doctrine, in three sections — A (base idea and prose), B (allowed), C (disallowed): roles, picking rules, briefing/verification discipline, CI-watching, PR mechanics, monitoring, references, session succession.
pr-report-contract.md	The fixed section order and semantics every PR body must follow — read in full before writing any PR.
issue-filing-contract.md	The fixed section order and semantics every filed issue must follow — read in full before filing any issue.
agents/adversary.md	The adversarial-verifier persona: judges ONE claim and tries to refute it, returning refuted / survives / uncertain with evidence. Register it as an agent definition, or feed it to a second CLI agent via its persona/agent-file flag.
scripts/scout.py	Find freshly-active ~0–20⭐ repos with specific good-first-issues and no stale-external-PR rot. Read-only.
scripts/impact-picks.py	Build the ranked warm-repo list from your merge record (share-of-contribution across merged PRs and closed issues). Feeds the picker.
scripts/pick-next.py	The gate-walking repo picker: re-ranks, then walks the list gate by gate (manual block, archived, empty queue, dormant, PR cap) with evidence for every skip, stopping at the first candidate. --skip N walks past candidates you are already working. Never bypassed (§B1).
pick-gates.example.json	Template for the picker's gates file — the manual block list, the dormancy threshold, and the proven_by overrides that correct GitHub's undercount of landed work.
templates/	Skeletons for the per-repo and per-human reference notes and the per-repo review-feedback log (§B9).
scripts/notif-watch.py	The sole standing watcher: polls GitHub notifications with its own per-thread cursor, emits one line per updated thread.
scripts/usage_query.py	On-demand quota utilization for Claude and/or Kimi, with a constant-burn "pace ceiling" so you know the moving target — and, when you're over it, the coast-back-to-pace time (on pace in T).
LICENSE	MIT.

Placeholder legend

SKILL.md uses placeholders — wire them to your own setup:

• <GH_USER> — your GitHub username (the contribution account).
• <FORK_ORG> — the GitHub org/user where your forks live (can equal <GH_USER>).
• <GIT_EMAIL> — the git author email your commits carry (your machine default).
• <DRIVE_REPO> — the working repo/dir that holds your watchlist and references.
• <WORK_DIR> — scratch/clone workspace.
• <model> — the model that did a given layer of work (for disclosure footers).

How to adopt

1. Drop the skill in. Copy SKILL.md, pr-report-contract.md, and issue-filing-contract.md into .claude/skills/burn-usage/ (or your harness's skill location) together, in the same directory — SKILL.md references the two contracts by relative filename, so they need to stay alongside it. Replace the placeholders above with your own GitHub user, fork org, and git email.

2. Wire the scripts. Put scripts/ somewhere your sessions can invoke them and update the scripts/... references in SKILL.md to the absolute paths you chose. All five are stdlib-only Python 3. Four of them — scout.py, notif-watch.py, impact-picks.py, and pick-next.py — need the gh CLI on PATH, and it must be authenticated as your contribution account, not merely installed: run gh auth login (check with gh auth status) or every call fails with auth errors that read like repo problems. Only usage_query.py works without gh.

3. Seed the scout exclusion list. mkdir -p ~/.burn-usage, then create ~/.burn-usage/scout-exclude.txt (one owner login per line, lowercase) listing your own account/orgs plus anything you've already probed, frozen, or dropped — keeping it current is what stops the scout re-surfacing repos you've dispatched. Override the path with SCOUT_EXCLUDE_FILE.

4. Seed the pick gates. cp pick-gates.example.json ~/.burn-usage/pick-gates.json and replace the example entries as real blocks accrue (override the path with PICK_GATES_FILE). A proven_by entry must carry an evidence URL showing the work landed — the picker refuses the file otherwise, because that field exists to correct GitHub's accounting, not to talk you past a cap. The picker re-ranks via the sibling impact-picks.py by default; if you keep your own ranked list elsewhere, point PICK_NEXT_RERANK_CMD at whatever regenerates it.

   Cold start: the picker needs at least one merged PR of yours. The ranked list is built from your track record, so with zero merged PRs impact-picks.py exits with "no warm repos found" and the picker has nothing to walk — that is every new adopter's starting point, not a malfunction. Until your first PRs merge, pick manually: run scout.py, choose a repo from its results, and work that. The picker takes over once a track record exists.

   The default re-rank is not free: every pick costs one gh search call plus two gh ... list calls per warm repo, so repeated picking in a session burns API rate-limit budget — expect it, and don't treat the picker as a free retry button.

5. Run the watcher. Start notif-watch.py under your harness's persistent background mechanism at session start; it seeds silently on cold start and then emits NOTIF ... lines you fetch and act on. State lives under ~/.burn-usage/ (override with BURN_USAGE_STATE_DIR).

6. Check pace. usage_query.py prints a max* column — the utilization you'd be at under a constant linear burn. Treat it as a target to reach or exceed, not a ceiling to stay under: below it you are under-spending, and the response is to dispatch more in parallel and fan out across repos. An OVER PACE flag is not a stop signal. What still binds is the global concurrency cap, one working root per run, an adversary gating every push, and how many diffs you can actually verify, push, watch to green CI and defend in review (§A, §B2). It reads standard Claude Code (~/.claude/.credentials.json) and, optionally, kimi-cli (~/.kimi-code/...) credentials; use --claude if you only run one.

Tooling caveats

• usage_query.py assumes the Claude Code and/or kimi-cli credential-file layouts and refreshes/rotates those tokens the same way those clients do. The Kimi half needs kimi-cli installed; pass --claude to skip it. It can reuse a small temp cache written by an optional companion usage hook, but works standalone (fetches live when no cache is present). No secrets are embedded — the OAuth client IDs it uses are the public ones those clients ship.
• The scripts use ~/.burn-usage/ for state by default; nothing writes outside that dir and the repos you clone.

Standing ethics (non-negotiable)

• Genuine, mergeable work only. The scarce resource is legitimate work in repos that actually respond — not tokens, not a PR count. Any issue count is a floor.
• Disclose AI assistance exactly once: the PR footer + a Co-Authored-By trailer on each commit. Nowhere else.
• Never argue with an anti-AI policy. A repo that bans or rejects AI work gets a respectful drop — never ship there, never undisclosed, never debate.
• Never star-beg and never star on request — decline the ask silently; the code is the contribution.
• Bounty stand-down. Where humans are racing for reward/campaign labels or money, don't compete; spend capacity where you're not taking food off someone's plate.

License

MIT — see LICENSE. This is a sanitized, non-personal copy shared for reuse; all identity- and machine-specific details have been replaced with placeholders.