OSS Contribution System#

A complete system for contributing to open-source repos. Four skills work together in a learning loop --each contribution makes the next one better.

Quick Start#

1. First time? Just say: oss discover <repo-url-or-name>
   • The system will create a profile, check repo openness, and find issues for you.
2. Found an issue? Say: oss auto <repo> #12345
   • End-to-end: implement -> open PR -> respond to bots -> ping maintainer.
3. Already have a PR? Say: oss check <repo>
   • Checks CI, bot comments, stale status, and takes action.
4. Want a quality review? Say: oss pr review <repo> #12345
   • Root cause analysis, diff check, description quality, bot response strategy.

How the System Works#

text

discover --> auto --> pr --> check --> retrospective
   ^                   ^       |              |
   |                   +-------+              |
   |              (human review loop)         |
   |                                          v
   |                              profile grows (lessons, patterns)
   |                                          |
   +---- checks archived history -------------+
         (avoid past mistakes)

Profile ( ./oss-pilot-data/profiles/<repo>.md): Stores repo-specific knowledge --build commands, maintainer styles, bot behavior, lessons learned. Grows with each contribution. See _template.md for the schema.

Context files ( ./oss-pilot-data/context/pr-<repo>-<N>.md): Track each PR's approach, bot decisions, and outcome. Archived after merge/close for future reference.

The Four Skills#

oss-discover (find.md)#

Find high-value issues with the highest merge probability.

• Checks repo openness (external contributor merge rate)
• Checks issue velocity (how fast issues get claimed)
• Scans 8 sources: high-signal labels -> bugs -> CI failures -> reclaimable PRs -> merged PR gaps -> scoped modules -> area merge rate -> codebase cleanup
• Verifies bugs still exist, checks comments for signals, evaluates fix feasibility

Read: discover.md

oss-auto (auto.md)#

One command from issue to opened PR. Orchestrates discover + pr.

• Cold start: auto-creates profile for new repos
• Feasibility check -> implement -> open PR -> respond to bots -> mark ready -> ping maintainer
• Auto-detects build tooling (Node/Python/Go/Rust/Make)
• Reads CONTRIBUTING.md and CLAUDE.md for repo conventions

Read: auto.md

oss-pr (pr.md)#

Quality gate for PRs. Validates before requesting review.

• Root cause analysis (right layer? blast radius? semantic contracts?)
• Common mistake patterns and anti-patterns
• PR description with "What did NOT change" and "What I Did NOT Verify"
• Bot response strategy (accept/decline/repeat handling)
• CI failure triage template

Read: pr.md

oss-check (check.md)#

Morning check-in for all pending PRs.

• CI/bot/stale status monitoring
• Retrospective on merged/closed PRs (writes Outcome + routes lessons)
• Maintenance: prunes stale lessons, archives old context files
• Handles fork PR CI skipping (normal for external contributors)

Read: check.md

Prerequisites#

• gh CLI installed and authenticated ( gh auth status)
• GitHub account with a fork of the target repo
• Optional: local clone for codebase scanning (Source 8)

Security Model#

This skill instructs the agent to run build, lint, and test commands (e.g., pnpm install, make, cargo test) from the target repository. This is inherent to contribution automation --you cannot validate a fix without running the repo's toolchain.

Threat surface: If the target repo contains malicious build scripts (e.g., postinstall hooks), those commands execute on your machine. This is the same risk as manually cloning a repo and running npm install.

How risk is managed:

• User trust boundary: You choose which repo to target. The skill never picks repos autonomously.
• Runtime gating: OpenClaw's exec approval system prompts before executing shell commands. The skill issues instructions; the runtime decides whether to run them.
• Scope checkpoint: The skill stops and asks before committing to changes >5 files or >200 lines.

Recommended hardening:

• Run inside a container ( openclaw --container <name>) or VM when targeting unfamiliar repos.
• Review the repo's package.json scripts / Makefile targets before first run.
• Use a dedicated GitHub account for automation if you prefer isolation.

Data Directories#

The system creates and manages these directories:

• ./oss-pilot-data/profiles/ --one profile per repo
• ./oss-pilot-data/context/ --active PR context files
• ./oss-pilot-data/context/_archived/ --completed PR context files (for learning)