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
• The system will create a profile, check repo openness, and find issues for you.

1. Found an issue? Say: oss auto #12345
• End-to-end: implement -> open PR -> respond to bots -> ping maintainer.

1. Already have a PR? Say: oss check
• Checks CI, bot comments, stale status, and takes action.

1. Want a quality review? Say: oss pr review #12345
• Root cause analysis, diff check, description quality, bot response strategy.

How the System Works

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

Profile (./oss-pilot-data/profiles/.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--.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 ) 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)