Local-only OSS contribution command center. Auto-refreshes the user's
in-flight PR and issue state on invoke so conversations start with full
context — no need to brief Claude on what's in flight. Helps the user
find issues to contribute to on GitHub, builds per-repo dossiers of what
each upstream expects (CLA, DCO, branch convention, AI policy, draft-first,
review bots, issue templates), runs deterministic gates before any
external action so AI-assisted contributions don't reach maintainers as
slop. State is markdown-only: candidate files at
~/.contribute-system/candidates/, repo dossiers at
~/.contribute-system/research/, append-only event log at
~/.contribute-system/log.jsonl. No database, no cloud calls.
Use when the user asks about their PRs / issues / contributions, wants to
find new work to take on, claim an issue, build/refresh a repo's dossier,
or draft a Design Issue or PR. Trigger with "/contribute", "what's my PR
status", "find a contribution", "claim issue X", "draft a Design Issue
for Y", "refre
Local-only OSS contribution command center. Auto-refreshes the user's
in-flight PR and issue state on invoke so conversations start with full
context — no need to brief Claude on what's in flight. Helps the user
find issues to contribute to on GitHub, builds per-repo dossiers of what
each upstream expects (CLA, DCO, branch convention, AI policy, draft-first,
review bots, issue templates), runs deterministic gates before any
external action so AI-assisted contributions don't reach maintainers as
slop. State is markdown-only: candidate files at
~/.contribute-system/candidates/, repo dossiers at
~/.contribute-system/research/, append-only event log at
~/.contribute-system/log.jsonl. No database, no cloud calls.
Use when the user asks about their PRs / issues / contributions, wants to
find new work to take on, claim an issue, build/refresh a repo's dossier,
or draft a Design Issue or PR. Trigger with "/contribute", "what's my PR
status", "find a contribution", "claim issue X", "draft a Design Issue
for Y", "refresh dossier for Z".
Local-only OSS contribution workflow. The skill itself is the system — there is no separate CLI binary, dashboard, or cloud backend. State lives in three places:
GitHub itself — fetched live via gh for any PR/issue state question. Never cached long-term.
Markdown candidate files at ~/.contribute-system/candidates/<owner>__<repo>__issue<N>.md — one per issue we're tracking. Frontmatter is the queryable layer (status, scout_score, repo, research_path, overrides). Body holds claim drafts, PR drafts, scope notes.
Markdown repo dossiers at ~/.contribute-system/research/<owner>__<repo>.md — one per upstream repo we contribute to. Built by the @researcher subagent. Frontmatter is canonical for every gate (CLA, DCO, branch convention, AI policy, draft-first, review bots, issue templates). Body holds curated knowledge: pet peeves, failure log, free-form notes that survive refresh.
Append-only event log at ~/.contribute-system/log.jsonl — every gate run, transition attempt, override, scout/researcher invocation lands here with a UTC timestamp. Filterable via jq.
Use this skill when the user wants to:
Know what's in flight (open PRs, claimed issues, candidate queue)
Find a new issue to contribute to on GitHub
Build or refresh a per-repo dossier (delegates to @researcher)
Run gate-checked transitions (claim, work, submit) — every external action passes through transition.sh first
Draft a claim comment, Design Issue, or PR description (default: Design Issue, NOT a PR)
Run an upstream repo's test suite
The pre-2026-04-30 version of the skill used a SQLite tracker (~/.contribute-system/contribute.db, 32 tables) plus a separate contribute-system/ monorepo (Next.js dashboard, TS CLI, Cloud Functions). Both were deleted because they were never used in practice. The skill now reads markdown directly. That tradeoff is deliberate: human-readable, greppable, git-trackable, survives any tool, no daemon process.
Prerequisites
gh CLI, authenticated as the user (gh auth status should show "Logged in")
jq on PATH (used by gates + log filtering)
Workspace at ~/000-projects/contributing-clanker/ containing upstream clones (each clone has its own for project conventions)
CLAUDE.md
Runtime state dir at ~/.contribute-system/ — created on first scout/researcher run if missing
Run this DCI check at activation (output is auto-injected into the prompt):
Before answering anything contribution-related, surface current state. Run these in parallel with the Bash tool:
# Upstream PRs in flight (filtered to outside-org repos only —# the system tracks contributions INTO repos the user does not own;# own-repo PRs are out of scope and must be excluded).## OWN_ORGS is the prefix list of repos to exclude. Update if the user# adds a new org. (Discoverable via `gh api user/orgs --jq '.[].login'`# plus the user's own login from `gh api user --jq '.login'`.)
OWN_ORGS='jeremylongshore/ intent-solutions-io/'
gh search prs --author=@me --state=open --limit=50 \
--json number,title,url,repository,isDraft,createdAt | \
jq --arg own "$OWN_ORGS"'
($own | split(" ")) as $excl |
map(select(.repository.nameWithOwner as $r |
($excl | map(. as $p | $r | startswith($p)) | any) | not))
'# Recently-merged + closed upstream PRs (last 30, same scope filter)
gh search prs --author=@me --state=closed --limit=30 \
--json number,title,url,repository,closedAt,createdAt | \
jq --arg own "$OWN_ORGS"'
($own | split(" ")) as $excl |
map(select(.repository.nameWithOwner as $r |
($excl | map(. as $p | $r | startswith($p)) | any) | not))
'# Local candidate tracker — markdown frontmatter is the queryable layer.# Candidates are upstream-only by construction (scout never enqueues# own-repo issues), so no scope filter needed here.for f in ~/.contribute-system/candidates/*.md; do
awk -v f="$(basename "$f" .md)"'
/^---$/ { fm = !fm ? 1 : 2; next }
fm == 1 && /^(repo|issue_number|status|scout_score|research_path|pr_number):/ { print f, $0 }
'"$f"done 2>/dev/null
# Recent activity from the event logtail -50 ~/.contribute-system/log.jsonl 2>/dev/null \
| jq -c "select(.event | test(\"transition_|gate_|researcher_|scout_\"))" 2>/dev/null
Scope rule (non-negotiable): this skill applies only to contributions made INTO repos the user does not own. Own-org PRs (jeremylongshore/*, intent-solutions-io/*) are out of scope — they are personal-project work, not anti-slop OSS contributions. The whole architecture (gates, dossiers, lifecycle) exists because upstream maintainers need protection from low-quality AI work; that concern doesn't apply to the user's own repos. If a candidate file ever references an own-org repo, it's a scout bug — flag it.
Then summarize for the user:
N open / draft PRs (and any blocked on review)
N candidates in claimed or working status but not yet submitted
N candidates in open / shortlist status (sorted by scout_score desc)
Any contradictions between gh (PR state) and the candidate's status: field (e.g., PR merged but candidate still says submitted) — flag for cleanup
N candidates whose research_path: is empty or stale (>14d) — flag for @researcher build/refresh
Skip Step 0 only when the user asks about something unrelated to their own contributions.
Step 0.5 — Ensure dossier exists for any repo we'll touch
Every repo we contribute to needs a dossier at
~/.contribute-system/research/<owner>__<repo>.md — that's where every gate
in ~/.contribute-system/gates/ reads its rules from (branch convention,
CLA/DCO, AI policy, draft-first preference, review bots, etc.).
Before any lifecycle transition (claim, work, submit) for a candidate at
repo <owner>/<repo>:
DOSSIER=~/.contribute-system/research/$(echo <owner>/<repo> | tr'/''_').md
DOSSIER=${DOSSIER/__/__}# ensure double underscoreif [[ ! -f "$DOSSIER" ]]; thenecho"no dossier — invoking @researcher"# delegate to the researcher subagentfi# Also check staleness — refresh if >14 days old
LAST=$(awk '/^last_refreshed:/{print $2; exit}'"$DOSSIER")
if [[ -n "$LAST" ]]; then
AGE_DAYS=$(( ( $(date +%s) - $(date -d "$LAST" +%s) ) / 86400 ))
[[ "$AGE_DAYS" -gt 14 ]] && echo"stale ($AGE_DAYS d) — invoking @researcher refresh"fi
Delegate dossier build/refresh to the @researcher subagent (defined
at ${CLAUDE_SKILL_DIR}/agents/researcher.md). It runs in its own context window so
the verbose CONTRIBUTING.md fetch + depth-1 link follows stay out of your
main conversation. It writes the dossier to disk and reports back a
one-paragraph summary.
If the user already invoked @researcher earlier in the session for this
repo, skip — don't re-build.
Step 1 — Discover
Find issues worth contributing to. Sources, in priority order:
Existing candidates with status: open or status: shortlist already in ~/.contribute-system/candidates/ — already discovered + vetted, ranked by scout_score: frontmatter field
Fresh GitHub label searches scoped to repos / languages in ~/.contribute-system/profile.md: gh search issues "label:'good first issue' state:open language:<lang>" --limit 50
Delegate discovery to the @scout subagent (defined at ${CLAUDE_SKILL_DIR}/agents/scout.md). It runs in its own context window so the verbose gh search output stays out of your main conversation. Pass it a mode: baseline (full per-tier sweep), refresh (re-evaluate existing candidates for momentum), or an ad-hoc query like "TypeScript repos at mainstream tier with no competing PRs." Scout writes ranked candidate markdown files to ~/.contribute-system/candidates/ and appends events to ~/.contribute-system/log.jsonl. Summarize the top picks for the user from those files; do not re-run the search yourself.
Step 2 — Qualify
Before claiming any issue, run these in parallel against the target repo:
gh pr list --repo <owner>/<repo> --search "<issue#>" --state=all
gh api repos/<owner>/<repo>/commits --jq '.[0:3] | map({date: .commit.author.date, msg: .commit.message[0:60]})'
gh api repos/<owner>/<repo>/contents/CONTRIBUTING.md --jq '.content' | base64 -d 2>/dev/null
Quick-reject signals:
2+ active PRs already on the issue
Issue >90 days old with maintainer silence
CLA required for trivial work
Stack mismatch with the user's strengths
Use the bundled agents/repo-analyzer.md for the structured eligibility / CLA / rules check.
Step 3 — Claim
Draft a claim comment from assets/claim-template.md. Adapt to the upstream's tone (lowercase if they use lowercase). Show the draft to the user for approval. Never gh issue comment autonomously.
Gate-checked transitions — before showing the claim draft to the user,
run the gate-runner via transition.sh to catch traps (already-assigned,
already-shipped, stale labels, AI-policy strikes, etc.):
If gates BLOCK, surface the blockers + fix hints to the user. They can fix
the underlying issue, pick a different candidate, or use
--override-gate <ID> "reason" if they have a specific justification (the
reason is logged to ~/.contribute-system/log.jsonl).
After the user posts the claim and gates pass, the candidate's status:
field is bumped automatically by transition.sh (atomic write). No manual
SQLite update needed — the markdown candidate file IS the tracker.
Step 4 — Work
Each clone in ~/000-projects/contributing-clanker/ has its own CLAUDE.md. Read it first. Run the project's native test suite — common patterns:
This runs phase B (pre-PR), C (PR submission), E (identity), F (legal),
and G (infrastructure) gates against the local diff + dossier rules. BLOCK
gates refuse the transition; WARN gates surface in the briefing for the
user to acknowledge before proceeding.
After successful submission, transition.sh bumps the candidate's
status: to submitted atomically. Manually add the PR number to the
candidate's frontmatter:
# After PR is opened
sed -i "s/^pr_number:.*/pr_number: <num>/; s|^pr_url:.*|pr_url: <url>|" \
~/.contribute-system/candidates/<owner>__<repo>__issue<N>.md
Reconciliation
Periodically (or on user request "reconcile candidates"), check candidates with a pr_number: field against live GitHub state:
for f in ~/.contribute-system/candidates/*.md; do
PR=$(awk '/^pr_number:/{print $2; exit}'"$f")
REPO=$(awk '/^repo:/{print $2; exit}'"$f")
[[ -z "$PR" || "$PR" == "null" ]] && continue
gh pr view "$PR" --repo "$REPO" --json state,merged,closedAt
done
For each candidate whose actual PR state has moved on:
PR merged → set status: merged in the candidate (atomic write)
PR closed unmerged → set status: dropped and append a row to the dossier's ## Failure log section so we learn from it
PR still open → no change (status: submitted)
Mandatory: human approval before external submission
Copied verbatim from the repo's CLAUDE.md:
Before submitting ANYTHING to external repos:
Run all tests — ALL must pass
Run project-specific linters — no errors
ASK JEREMY FOR APPROVAL with test summary, file list, proposed body
Default to Design Issue, NOT a PR
NEVER auto-submit PRs. NEVER bypass human approval. Design issues > PRs.
Output
After Step 0, output a status block. After each subsequent step, output structured progress.
State summary (after Step 0)
PRs in flight: <N> open, <M> draft
- <repo>#<num>: <title> (state, age)
...
Claimed but not submitted: <N>
- <id>: <repo>#<issue> ($value)
...
Tracked opportunities: <N> (top 5 by value)
- <id>: <repo>#<issue> ($value, <competition flag>)
...
Drift: <N> rows where tracker disagrees with GitHub
- <id>: tracker says <X>, gh says <Y> — suggest <Z>
Per-step output
Step
Output
Discover
Three sections: Tracker queue / Fresh GitHub / Algora URLs. Top 3 picks highlighted.
Qualify
Verdict block: claim / wait / skip with one-sentence reason
Claim
Markdown draft of the comment, with placeholders filled. Awaits user approval.
Work
Test summary: pass/fail counts, duration, coverage %, log path
Submit
Markdown draft of the PR or Design Issue body. Awaits user approval.
Audit subcommands
When the user asks "what gates am I overriding most?" or "audit my contribution
history" or "show me override frequency":
${CLAUDE_SKILL_DIR}/scripts/audit-overrides.sh # all-time${CLAUDE_SKILL_DIR}/scripts/audit-overrides.sh --since=30 # last 30 days${CLAUDE_SKILL_DIR}/scripts/audit-overrides.sh --scope=org:posthog # one org${CLAUDE_SKILL_DIR}/scripts/audit-overrides.sh --gate=A05 # one gate${CLAUDE_SKILL_DIR}/scripts/audit-overrides.sh --json # JSON
Output is a per-gate table with [overrides, blocks, override_rate, top_reason],
sorted by override_rate desc. Gates overridden ≥50% of the time get flagged for
investigation — either the gate is too strict (false-positive heavy) or it's
catching real risk that's being consistently dismissed. Either way, surface it.
Wait 60s and retry; check gh auth status token scopes
Candidate's status: submitted but PR is merged
Reconciliation drift
Run reconciliation step (above)
User asks to claim, but competing PR exists
Risk
Surface the competing PR explicitly; gate A2 already-shipped will BLOCK if it's a merged dupe
Test suite hangs (e.g., posthog without flox)
Wrong env
Wrap in flox activate -- bash -c "..." for flox-managed repos
gh issue comment permission denied
Repo private or token missing scope
Show the comment text to the user; they post manually
Gate run BLOCKs unexpectedly
Stale dossier or wrong rule
@researcher refresh <owner>/<repo>; if the rule itself is wrong, edit the dossier (manual sections survive refresh) or override with transition.sh ... --override-gate <ID> "reason"
Dossier missing for a candidate's repo
First time touching this repo
@researcher build <owner>/<repo> (auto-invoked by Step 0.5 anyway)
If any external submission would happen without human approval, stop and ask. This is non-negotiable.
Examples
Example 1: "What's my PR status?"
User invokes /contribute or asks "what's in flight?"
Run Step 0 (parallel gh pr list + gh issue list + candidate-frontmatter scan + recent log events)
Output the State Summary block
Stop. The user can drill into any PR with a follow-up question.
Example 2: "Find me a new contribution to work on"
User asks "what should I work on next?" or "scout opportunities."
Run Step 0 first (state summary)
Delegate to @scout (the user-scope subagent at ${CLAUDE_SKILL_DIR}/agents/scout.md)
Optional: per top pick, run Step 2 (Qualify) to surface CLA / competing-PR signals
Example 3: "Draft a claim for screenpipe#1234"
User asks to claim a specific issue.
Run Step 2 (Qualify) on mediar-ai/screenpipe#1234
If verdict is claim, read assets/claim-template.md
Fill placeholders (approach in 1-2 bullets, ETA, CLA status)
Show draft to user
On user approval, post via gh issue comment AND update tracker (Step 3 SQL)
Example 4: "Reconcile the tracker"
User asks to sync local state with GitHub.
Read all tracker rows where pr_number IS NOT NULL
For each, run gh pr view <repo> <pr_number> --json state,merged
Update tracker rows whose status disagrees with GitHub state
Output a diff summary: N rows updated, M unchanged
Example 5: "Run tests on cortex"
User asks to verify a working branch.
Read agents/test-runner.md
Detect cortex stack (Python + pyproject.toml)
cd ~/000-projects/contributing-clanker/cortex && pytest -v 2>&1 | tee ~/.contribute-system/test-logs/$(date +%Y%m%d-%H%M%S)-cortex.log
Output test summary block (pass/fail counts, log path)
Resources
Bundled subagents (load with Read agents/<name>.md)
@scout (user-scope subagent at ${CLAUDE_SKILL_DIR}/agents/scout.md) — discovery sweep, GitHub-only, ranked by star-tier brackets. Each candidate it writes carries a research_path: frontmatter field pointing at the matching dossier (or empty if not yet built).
@researcher (user-scope subagent at ${CLAUDE_SKILL_DIR}/agents/researcher.md) — build / refresh the per-repo dossier at ~/.contribute-system/research/<owner>__<repo>.md. Auto-invoked when a candidate's dossier is missing or older than 14 days.
agents/repo-analyzer.md — DEPRECATED. Most of its function is now in the dossier system. Keep until Slice 3 retires it.
agents/draft-writer.md — draft a Design Issue or PR body from a working branch's diff
agents/test-runner.md — detect upstream stack and run the native test suite, log to disk
The repo's own CLAUDE.md at ~/000-projects/contributing-clanker/CLAUDE.md for project conventions and per-clone build commands
Old patterns (deprecated, do not reintroduce)
The pre-2026-04-30 skill referenced a contribute CLI binary, EV scoring, judge gates, slack notifications, asciinema work-session recording, evidence bundles, and competition risk scoring. The underlying contribute-system/ monorepo was deleted because it was never used.
The pre-2026-05-03 skill used a SQLite tracker at ~/.contribute-system/contribute.db (32 tables, bounties-keyed schema) plus an Algora/Gumroad/Cortex bounty-board framing. That DB was wiped; the framing is gone. The system is now markdown-only: candidate files + dossiers + JSONL event log. The skill is a contribution tool — not a tracker, not a payouts system, not a portfolio.
If a feature from those eras is wanted back, recover code from git log in ~/000-projects/contributing-clanker/. The bar to re-add is "Jeremy actually uses it daily."
