Skip to content
Back to search

oss-contrib

SkillWorks with Claude CodeGitHub

Run KhomDev's open-source contribution program across 15 repos (x402, near/intents, near/mpc, nearcore, near/docs, OutLayer, near-api-js, OpenZeppelin, foundry, MCP rust-sdk, agave, cargo-near, near-sdk-rs, near-token-rs, near-gas-rs). The orchestrator (Opus or Fable) sends Haiku agents to pick up reported issues AND to discover new, unreported problems; agents research, build and test on CI. The orchestrator verifies every claim itself, then gives the operator a one-click approval in chat for each PR, issue, comment or review reply. Use when the user asks to contribute to, open PRs or issues in, find bugs in, review or handle PRs in, or run a census or agent round on any of these repos, or says "keep contributing".

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/khomdev--agentic-contribution/badge.svg)](/listings/khomdev--agentic-contribution)

HTML

<a href="/listings/khomdev--agentic-contribution"><img src="/api/listings/khomdev--agentic-contribution/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/KhomDev/agentic-contribution "$HOME\.claude\skills\oss-contrib"
cd "$HOME\.claude\skills\oss-contrib"
mkdir local; copy config\local.example.json local\config.json   # then edit it
python -m unittest discover -s tests

The overlay holds the private parts:

- the state file and notes root; - the signing key path; - a knowledge-search command over your own notes; - per-repo knowledge paths and held items; - extra banned terms for PR text; - the terms that must never appear in this repo.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 141 lines
  1. ---
  2. name: oss-contrib
  3. description: Run KhomDev's open-source contribution program across 15 repos (x402, near/intents, near/mpc, nearcore, near/docs, OutLayer, near-api-js, OpenZeppelin, foundry, MCP rust-sdk, agave, cargo-near, near-sdk-rs, near-token-rs, near-gas-rs). The orchestrator (Opus or Fable) sends Haiku agents to pick up reported issues AND to discover new, unreported problems; agents research, build and test on CI. The orchestrator verifies every claim itself, then gives the operator a one-click approval in chat for each PR, issue, comment or review reply. Use when the user asks to contribute to, open PRs or issues in, find bugs in, review or handle PRs in, or run a census or agent round on any of these repos, or says "keep contributing".
  4. ---
  5. # OSS contribution program
  6. You are the **orchestrator**. You plan, verify and prepare; you do not delegate judgement.
  7. ```
  8. operator ──approves──▶ public action (PR, issue, comment, reply) ▲ one click each
  9. ▲ │
  10. │ gate packet (exact text + evidence + lint) │
  11. orchestrator ──verifies every claim──◀── draft ◀── Haiku agent
  12. │ issue lane: pick up a reported issue
  13. │ discovery lane: find a new problem
  14. └── census, state file, prompts (brief.py), CI (oss-ci) ─────────┘
  15. ```
  16. - **Haiku agents** research (upstream plus the operator's private knowledge), reproduce, build, run
  17. CI and write a draft. They never publish.
  18. - **You** re-check each draft against upstream, triage security, re-sign the commits, lint the text
  19. and write a gate packet.
  20. - **The operator** reviews each packet in chat and clicks. Nothing public happens without that click:
  21. [references/operator-gate.md](references/operator-gate.md).
  22. ## Setup (once per machine)
  23. Copy `config/local.example.json` to `local/config.json` (gitignored) and fill in the private paths,
  24. the knowledge sources and the private terms. Scripts merge it over `config/repos.json`. Without it,
  25. `brief.py` refuses to build a prompt. See
  26. [references/knowledge-sources.md](references/knowledge-sources.md).
  27. ## Start of every session (and after a compaction)
  28. 1. Read the state file (`state_file` in the overlay): the live state.
  29. 2. `python scripts/census.py`: open PRs per repo against each budget.
  30. 3. Run the review sweep (below) before starting any new work.
  31. 4. If it's been a week since the last check: `python scripts/rules_drift.py`. If a repo changed its
  32. rules, update its card and `config/repos.json`, then run with `--update`.
  33. Scripts live in this skill's folder. Run them as `python <skill-dir>/scripts/<name>.py` from any
  34. directory; below they're shortened to `scripts/<name>.py`. They need only the Python stdlib and an
  35. authenticated `gh`.
  36. ## The loop
  37. 1. **Review sweep, first.** For every open PR: new reviews, bot comments, CI status, merge state.
  38. Draft each fix or reply, verify it and gate it. Replies to maintainers go out within a day.
  39. 2. **Pick slots and a lane.** A repo with `free > 0` in the census, and no PR opened there today,
  40. can take an agent. Choose the lane per repo:
  41. - **Issue lane**: an unclaimed issue fits, ideally one with a maintainer-stated fix.
  42. - **Discovery lane**: the tracker has nothing unclaimed, which is common in fast repos, or a
  43. surface looks under-tested. Agents use the playbook in
  44. [references/discovery.md](references/discovery.md): docs vs. API, edge inputs, test health,
  45. sibling bugs, spec conformance, error paths.
  46. - Issue-first repos (mpc, near-api-js, OpenZeppelin, rust-sdk) get an issue draft first; the PR
  47. waits for a maintainer's reply. Discovery findings in any repo usually start as an issue with a
  48. minimal repro.
  49. 3. **Launch agents.** Build each prompt with
  50. `python scripts/brief.py --repo <key> [--discover] --task-file <task.txt>`, write it to a file,
  51. and start `Agent(model: "haiku", run_in_background: true)` telling it to read that file first.
  52. Run at most **4 at once**, launched 2-3 minutes apart, each only with at least 1 GB of free RAM.
  53. Record each agent and its task in the state file.
  54. 4. **Wait well.** Never poll CI faster than every 5 minutes, and never use `gh run watch`. When an
  55. agent finishes you get a notification. Don't check on it.
  56. 5. **Verify** each draft with [references/verification.md](references/verification.md), all 10
  57. points. For discovery findings, re-run the repro yourself and do the security triage in
  58. [references/discovery.md](references/discovery.md). Fix or reject. Never forward an agent's claim
  59. you haven't checked.
  60. 6. **Gate.** Write the packet, run `pr_lint.py` (0 errors; `--comment` for issues, comments and
  61. replies) and `signed_check.py` (OK), then ask the operator with `AskUserQuestion`, at most 4 items
  62. per call, each with the exact text in `preview`.
  63. 7. **Execute exactly what was approved**, verify it on GitHub, and record it in the state file.
  64. 8. **Learn.** Corrections, quirks, dead ends and "techniques tried, nothing found" go into
  65. `<oss_root>/<oss_dir>/RESEARCH.md` or the repo card.
  66. ## Rules that never bend
  67. - **Operator click before anything public.** Approval in chat only, per item. Silence or a timeout
  68. means "no".
  69. - **Evidence or it didn't happen.** A fix needs a test that is red without it and green with it. A
  70. discovery finding needs a repro that was actually run. A flaky test needs a 20-seed shuffle. A
  71. "doesn't exist" claim needs a grep under three names. See
  72. [references/ci-and-evidence.md](references/ci-and-evidence.md).
  73. - **Prior art gets credit, never a copy.** If a stale PR fixes it, comment crediting the author.
  74. - **Budget.** Stay within `budget` open PRs per repo (`config/repos.json`), one new PR per repo per
  75. day, quality over count. x402's CONTRIBUTING forbids batch-generated low-effort PRs, and
  76. OpenZeppelin closes them.
  77. - **Security channel.** Anything with security impact goes only to
  78. `<oss_root>/<oss_dir>/PRIVATE-SECURITY-NOTE.md`, then through the project's own security process.
  79. Never into a branch, test name, issue, body or comment. The public `oss-ci` repo carries no private
  80. material.
  81. - **Public text** follows [references/public-text.md](references/public-text.md): first person
  82. singular, no internal terms, the footer, and the AI disclosure where required.
  83. - **Commits** follow the repo's format, are signed and authored as KhomDev, and carry exactly one
  84. Claude co-author trailer, the orchestrator's: [references/signing.md](references/signing.md).
  85. - **Off limits.** Consensus, networking, crypto and validator code in nearcore, agave and mpc
  86. (tooling, tests and docs only), plus every held item in the private overlay (`private_rules`).
  87. - **Knowledge is read-only.** Never write into the overlay's knowledge paths, and never quote them
  88. publicly.
  89. - **This skill is public.** Private paths, names and held items live only in `local/config.json`.
  90. `tests/test_no_private_leaks.py` must pass before every push of the skill.
  91. ## Repo cards
  92. Each card has an **agent rules block**: the project's own contributor rules, written in the style
  93. of x402's sample agent prompt. x402's card uses that sample verbatim. The card also holds
  94. orchestrator notes such as template, draft-first, CLA, CI command and lessons learned.
  95. | key | card | key | card |
  96. |---|---|---|---|
  97. | x402 | [repos/x402.md](repos/x402.md) | foundry | [repos/foundry.md](repos/foundry.md) |
  98. | intents | [repos/intents.md](repos/intents.md) | rust-sdk | [repos/rust-sdk.md](repos/rust-sdk.md) |
  99. | mpc | [repos/mpc.md](repos/mpc.md) | agave | [repos/agave.md](repos/agave.md) |
  100. | nearcore | [repos/nearcore.md](repos/nearcore.md) | cargo-near | [repos/cargo-near.md](repos/cargo-near.md) |
  101. | docs | [repos/docs.md](repos/docs.md) | near-sdk-rs | [repos/near-sdk-rs.md](repos/near-sdk-rs.md) |
  102. | outlayer | [repos/outlayer.md](repos/outlayer.md) | openzeppelin | [repos/openzeppelin.md](repos/openzeppelin.md) |
  103. | near-api-js | [repos/near-api-js.md](repos/near-api-js.md) | near-token | [repos/near-token-rs.md](repos/near-token-rs.md) |
  104. | near-gas | [repos/near-gas-rs.md](repos/near-gas-rs.md) | | |
  105. ## Scripts
  106. | Script | Does |
  107. |---|---|
  108. | `census.py [--json]` | Open KhomDev PRs per repo against each budget (one search call) |
  109. | `brief.py --repo K [--discover] --task-file F` | The complete Haiku agent prompt; `--discover` adds the discovery playbook |
  110. | `pr_lint.py --repo K --title T --body-file B --commit-file C` | Repo title format, template sections, footer, disclosure, private-term scan; exit 1 on errors. Add `--comment` for issues, comments and replies |
  111. | `signed_check.py --repo K --pr N` | GitHub-verified signatures and the KhomDev noreply author on every commit |
  112. | `ci.py dispatch / mpc / status / grep` | Quota-guarded runs on `KhomDev/oss-ci`; no watch by design |
  113. | `rules_drift.py [--update]` | Detects upstream changes to the files each card was written from |
  114. Tests: `python -m unittest discover -s tests -v` from the skill folder (offline, about 1 s).
  115. ## More
  116. - [references/discovery.md](references/discovery.md): the discovery lane, its playbook and security triage
  117. - [references/agent-brief.md](references/agent-brief.md): the common brief and its placeholders
  118. - [references/knowledge-sources.md](references/knowledge-sources.md): the private overlay and the rules for private knowledge
  119. - [references/state-and-host.md](references/state-and-host.md): the state file, compaction, Windows traps
  120. - [README.md](README.md): the human guide (setup, a worked example, maintenance)
README.md · README · 152 lines
  1. # agentic-contribution
  2. A Claude Code skill (`oss-contrib`) for contributing to open source with an AI team, **under human
  3. control**.
  4. A senior model (Opus or Fable) orchestrates. Cheap Haiku agents do the legwork. They pick up
  5. reported issues, and they **discover new, unreported problems**: broken examples, wrong docs, edge
  6. cases, flaky tests, spec gaps. They reproduce, build and run tests on CI. The orchestrator re-checks
  7. everything an agent claims and prepares each public action as a gate packet. **The operator**
  8. approves each one with a click in the chat. Nothing appears on GitHub under the operator's name
  9. without that click.
  10. It's written for one contributor (KhomDev) and 13 repositories, but the engine is generic. Swap the
  11. repo cards and `config/repos.json` for your own.
  12. ## Why it's built this way
  13. | Problem we hit | What the skill does about it |
  14. |---|---|
  15. | Agents state false things confidently ("no mock network exists") | A 10-point verification checklist the orchestrator runs on every draft |
  16. | One agent nearly re-posted someone else's stale PR | Prior-art search is mandatory twice: by the agent and again right before the gate |
  17. | Maintainers close low-effort AI PRs (x402 and OpenZeppelin say so) | Budgets per repo, one new PR per repo per day, red/green evidence on every fix |
  18. | Fast repos have no unclaimed issues left | A discovery lane with a six-technique playbook for finding new problems, each needing a repro that was actually run |
  19. | A new finding might be a security issue | Security triage by the orchestrator; security-relevant findings go only through the project's security process |
  20. | Each repo has different rules (titles, templates, changesets, CLA, AI disclosure) | A card per repo with an agent rules block from the project's own docs, plus `pr_lint.py` to enforce it |
  21. | Repos change their rules | `rules_drift.py` hashes the upstream rule files and flags changes |
  22. | Parallel `gh run watch` drained the 5000/h GitHub quota | `ci.py` has no watch, refuses to start under 300 remaining, and polls at most every 5 minutes |
  23. | Private knowledge must never leak | Private paths, sources and held items live in a gitignored overlay; `pr_lint.py` and a leak test guard both the PR text and this repo |
  24. ## Layout
  25. ```
  26. oss-contrib/ (clone this repo to ~/.claude/skills/oss-contrib)
  27. ├── SKILL.md entry point Claude loads (orchestrator instructions)
  28. ├── README.md this file
  29. ├── CHANGELOG.md changes and the validation log
  30. ├── config/
  31. │ ├── repos.json per-repo public rules as data (single source of truth)
  32. │ ├── local.example.json template for the private overlay
  33. │ └── rules-snapshot.json hashes of the upstream rule files the cards were written from
  34. ├── local/config.json YOUR private overlay (gitignored, never committed)
  35. ├── repos/<key>.md one card per repo: agent rules block + orchestrator notes
  36. ├── references/
  37. │ ├── discovery.md discovery lane: playbook and security triage
  38. │ ├── agent-brief.md the common prompt every Haiku agent gets
  39. │ ├── operator-gate.md what needs a click, packet format, how the operator is asked
  40. │ ├── verification.md the orchestrator's checklist for agent drafts
  41. │ ├── ci-and-evidence.md CI workflows, quota rules, proof standards
  42. │ ├── signing.md SSH signing, re-signing, trailers, AI disclosure
  43. │ ├── public-text.md voice, banned terms, body skeleton, review replies
  44. │ ├── knowledge-sources.md the private overlay and the rules for private knowledge
  45. │ └── state-and-host.md state file, compaction, Windows traps
  46. ├── scripts/ stdlib-only Python, all GitHub access through `gh`
  47. └── tests/ offline unit tests (python -m unittest)
  48. ```
  49. ## Setup
  50. ```powershell
  51. git clone https://github.com/KhomDev/agentic-contribution "$HOME\.claude\skills\oss-contrib"
  52. cd "$HOME\.claude\skills\oss-contrib"
  53. mkdir local; copy config\local.example.json local\config.json # then edit it
  54. python -m unittest discover -s tests
  55. ```
  56. The overlay holds the private parts:
  57. - the state file and notes root;
  58. - the signing key path;
  59. - a knowledge-search command over your own notes;
  60. - per-repo knowledge paths and held items;
  61. - extra banned terms for PR text;
  62. - the terms that must never appear in this repo.
  63. ## Using it
  64. In a Claude Code session, say something like:
  65. - "Keep contributing to the 13 repos." This runs the full loop: review sweep, census, agent rounds,
  66. verification, gate.
  67. - "Find new bugs in near-api-js." This starts the discovery lane.
  68. - "Handle the review comments on our open PRs."
  69. - "Census: which repos have free PR slots?"
  70. ### What the operator sees
  71. When items are ready, Claude asks up to four questions at a time, like this one:
  72. > **x402 PR**: Open the x402 PR 'fix(near): evict expired settlement entries' as a draft?
  73. > ○ Open as draft (Recommended): *preview shows the exact title, body, CI evidence and lint result*
  74. > ○ Open ready ○ Revise ○ Hold
  75. **Revise** takes free-text notes; Claude applies them, re-lints and asks again. No answer means
  76. nothing is posted. Each gate packet is also saved under `<oss_root>/<repo>/gate/`.
  77. ## Two worked examples
  78. **Issue lane: a flaky test in near/mpc (near/mpc#5260).**
  79. 1. The census shows a free slot.
  80. 2. `brief.py --repo mpc` combines the common brief, mpc's own rules (`<sut>__should_<assertion>` test
  81. names, no `as` casts, no filler comments) and the task.
  82. 3. The agent proves the test is order-dependent with a 20-seed shuffle on CI: 13/20 fail on main,
  83. 0/20 on its branch.
  84. 4. The orchestrator re-checks both runs, re-signs the commit, lints it, and asks the operator, who
  85. clicks **Open PR**.
  86. **Discovery lane: a broken docs example (near/docs#3191).**
  87. 1. A docs agent compared snippets with the real API and found `NEAR.fromDecimal`, a method that
  88. doesn't exist.
  89. 2. The orchestrator ran the old snippet against the published package
  90. (`TypeError: NEAR.fromDecimal is not a function`) and the fixed one (correct output).
  91. 3. It re-signed the commit, linted it, and the operator clicked **Open PR**.
  92. ## Maintenance
  93. | When | Do |
  94. |---|---|
  95. | Weekly | `python scripts/rules_drift.py`. On a change, re-read the file, update the card and `config/repos.json`, then `--update` |
  96. | A repo joins or leaves | Edit `config/repos.json` (with `examples` of real merged titles), add or remove `repos/<key>.md`, run the tests |
  97. | A repo's title format changes | Update `title.regex` and `examples`; the tests check each good example matches and each bad one doesn't |
  98. | Before every push of this repo | `python -m unittest discover -s tests` must pass, including the leak test against your real overlay |
  99. | The orchestrator model changes | Nothing to edit: the trailer pattern accepts any `Claude <model>` |
  100. ## Testing
  101. ```powershell
  102. python -m unittest discover -s tests -v
  103. ```
  104. The tests are offline: GitHub calls go through a fake `gh` runner, and the config tests use
  105. `config/local.example.json`, never the private overlay. They cover:
  106. - the linter, with real merged titles as positive and negative cases;
  107. - the census tally and signing checks;
  108. - CI argument building and the quota floor;
  109. - drift detection;
  110. - prompt assembly, with no placeholder left unfilled, in both lanes;
  111. - the docs: frontmatter, links, and a rules block in every card;
  112. - a **leak test** that fails if any private term from your overlay, or any user path or email,
  113. appears in a tracked file.
  114. The skill was also run end to end with real Haiku agents (see "Validation log" in `CHANGELOG.md`).
  115. ## Limits and honest caveats
  116. - The repo cards summarise each project's rules as of the "read" date in each card. Upstream is the
  117. authority, which is why `rules_drift.py` exists.
  118. - `pr_lint.py` catches format problems and leaks. It doesn't judge whether a change is correct; the
  119. verification checklist and the operator's review do that.
  120. - The banned-term lists can't anticipate every leak. Read the preview before you click.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.