| name | top-contributor-finder |
| description | Find and segment top external open-source contributors for relationship-building, weekly reporting, recognition, or contributor strategy. Use this whenever the user asks to identify "top contributors", "best OSS contributors", "contributors to thank", "who should we thank", "who is contributing meaningfully", "weekly top contributors", "contributor report", or asks for a GitHub contributor shortlist. This skill analyzes merged and open PRs, filters out employees/org members/bots and typo-only contributors, inspects open PR status for contributor-actionable concerns, enriches candidates with GitHub profile/repo context, and returns a practical contributor analysis with linked PRs/issues.
|
Top Contributor Finder
Identify external GitHub contributors who are doing meaningful work. The output can support simple relationship-building outreach, weekly Slack reports, recognition, contributor strategy, or ecosystem/partner discovery. This is not a formal contributor-program workflow.
Default target repo: your-org/your-repo.
When to use this skill
Use this skill when the user wants to:
- find top OSS contributors
- identify contributors for outreach, thank-you notes, or recognition
- create weekly top-contributor Slack reports
- produce recurring contributor recognition summaries
- understand which external contributors are doing meaningful work
- segment merged and open PR authors
- evaluate whether open PRs show contributor-actionable concerns, stale work, or low quality
- spot contributors who may also be maintainers, ecosystem partners, or relevant OSS builders
Core principles
- Prioritize meaningful contribution substance over raw PR count.
- Include open PRs as signal, but do not treat them as equivalent to merged work.
- Exclude bots, repo-owner employees, org members, and obvious internal contributors.
- Exclude typo-only, comment-only, formatting-only, and low-substance docs-only contributors from the top outreach list.
- Do not prioritize issue-only contributors unless the user explicitly asks for issue reporters.
- Keep the recommendation practical: who is contributing meaningfully, who merits outreach, who should be monitored, who should be skipped, and what the report/outreach implication is.
- Outreach framing should feel like “we noticed and appreciate you,” not “please join our program.”
Required tools and auth
Prefer the GitHub CLI:
gh auth status
The script writes generated JSON for the current analysis run. By default this goes under the system temp directory, not the repo:
/tmp/top-contributor-finder/<repo-owner>__<repo-name>/<generated-at>__<since>_to_<until>.json
Use --output when you want a specific disposable path. Use --output-dir only if the user explicitly asks to save the JSON somewhere else. Do not commit generated contributor JSON unless the user explicitly requests it.
Do not use --max-candidates for full top-contributor analysis unless the user explicitly wants a smaller sample; the default stores the full qualifying candidate set for that run.
Generated JSON shape
Each run produces JSON for the agent or human to inspect while writing the current report. Important top-level fields:
generated_at: UTC timestamp for the runrepo, since, until, excluded_orgs, and run_parameters: enough metadata to reproduce or compare the runsearch_notes: GitHub Search totals and cap notescandidate_count_before_limit, candidate_limit, and candidate_count: whether the run was limitedskipped_low_signal_logins: contributors skipped before expensive enrichment because they did not meet configured meaningful merged/open PR thresholdsrun_parameters.min_meaningful_merged, run_parameters.min_meaningful_open, run_parameters.issue_activity_mode, and run_parameters.issue_activity_top_n: performance/scope knobs used for the runcontributor_rollups: compact per-contributor records for ranking cumulative top contributors and identifying recent activity from PR timestampscandidates: full nested candidate details with profiles, PRs, issues, contributor-actionable concerns, normal open-PR states, and evidence
Use contributor_rollups for cumulative analysis because it is compact and easy to scan. It includes:
loginhuman_context.summaryhuman_context.contribution_themeshuman_context.contribution_stylehuman_context.issue_vs_pr_activityhuman_context.collaboration_signalshuman_context.relationship_contexthuman_context.what_to_watch_nextrecommended_action, such as outreach, monitor, or manual review; treat this as draft memory, not a final ranking- supporting contribution counts
- first and last observed PR timestamps in the run
- merged/open/closed-unmerged PR numbers
- recent PR titles and URLs
open_pr_concern_summary for contributor-actionable open PR problemsopen_pr_normal_state_summary for normal process states retained as metadata
Use candidates when writing the qualitative report or checking evidence. It keeps representative PRs/issues, recent comments/reviews, profile details, and the same human_context fields. Treat numbers as supporting evidence, not the point of the generated JSON.
Stateless cumulative weekly model
Weekly reports should not depend on retained repo artifacts. Instead, run a cumulative analysis for the full relevant period every time, then use PR and issue dates inside the generated JSON to understand what changed recently.
For , the default cumulative period starts at your project's launch or open-source date and ends at the report date. For other repos, use the full relevant OSS period or a broad enough date window to represent top contributors overall.
Use the current cumulative run to classify contributors roughly as:
newly important: the contributor appears to have crossed into top-contributor territory recently based on the dates of their meaningful merged/open workestablished and active: already has a strong cumulative record and also has meaningful recent activityestablished but quiet: remains a top contributor overall but has little or no recent activitymonitor: has promising open or issue activity but does not yet stand out relative to the current cohort
For outreach, prefer contributors who stand out relative to the current cumulative cohort. Do not treat one or two meaningful merges as automatically sufficient; use merged PR counts as evidence in context with PR substance, issue activity, profile/ecosystem signals, and how active other contributors are in the same period.
The helper script uses gh api, gh pr view, and GitHub GraphQL via gh api graphql. If gh is unavailable, use GitHub web/API tools manually and follow the same analysis steps.
Do not log or hardcode tokens.
Default analysis scope
Use sensible defaults unless the user says otherwise:
- Repo:
your-org/your-repo
- Since date: your project's launch or open-source date for ; otherwise last 30 days
- Internal org exclusions: the repo owner org is excluded by default; add extra orgs only when the user explicitly identifies them as internal
- Include PRs that are:
- merged since the start date
- open and created or updated since the start date
- closed/unmerged if they provide useful quality or contributor-concern context
- Include linked issues plus authored/commented issues in the date window so the generated JSON can capture whether someone is PR-heavy, issue-heavy, helping with triage, or turning discussion into implementation.
Recommended workflow
Step 1: Collect candidate data
Run the bundled script from the repository root:
python3 .agents/skills/top-contributor-finder/scripts/find_top_contributors.py \
--repo your-org/your-repo \
--since <YYYY-MM-DD>
The script gathers:
- merged PRs
- open PRs
- closed-unmerged PRs
- GitHub profile details
- owned repositories
- recently contributed repositories
- open PR status, review decision, mergeability, checks, labels, linked issues, recent comments, and recent reviews
- authored and commented issues in the date window for top-ranked candidates by default
The script intentionally does cheap PR-title/state prefiltering before profile, detailed PR, and issue enrichment. Defaults require either 2 likely meaningful merged PRs or 2 likely meaningful open PRs before expensive enrichment. This keeps one-off low-signal contributors from making full runs slow. To broaden the net for a one-time historical audit, lower the thresholds and collect issues for all candidates:
python3 .agents/skills/top-contributor-finder/scripts/find_top_contributors.py \
--repo your-org/your-repo \
--since <YYYY-MM-DD> \
--min-meaningful-merged 1 \
--min-meaningful-open 1 \
--issue-activity-mode all
GitHub Search rate limits are waited and retried by default when the reset is within --max-rate-limit-wait-seconds (default one hour). Use --no-rate-limit-wait only for a quick smoke run where partial issue context is acceptable. If the script still times out, narrow the date scope and output size with:
python3 .agents/skills/top-contributor-finder/scripts/find_top_contributors.py \
--repo your-org/your-repo \
--since <YYYY-MM-DD> \
--until <YYYY-MM-DD> \
--max-candidates 40 \
--issue-activity-mode none
Use --exclude-org for any additional organization the user says should be treated as internal. The repo owner org is excluded by default.
Use --until YYYY-MM-DD when the user wants a bounded report period such as one week. Without it, the script analyzes through today.
Repo collaborator filtering (recommended)
By default (--exclude-repo-collaborators, on by default), the script fetches the full list of repo collaborators via /repos/{owner}/{repo}/collaborators before any PR analysis. This deterministically excludes all users with write/admin/maintain access — including those with private org membership that the per-user org membership API cannot see. This is the most reliable internal-contributor filter when the authenticated gh token has sufficient repo permissions.
To disable this behavior (e.g. for public repos where you lack collaborator list access), pass --no-exclude-repo-collaborators. The script will fall back to per-user org membership checks and profile/company/bio heuristics.
The excluded collaborators are recorded in the generated JSON under excluded_repo_collaborators and excluded_repo_collaborators_count.
GitHub may still hide private org membership for non-collaborator contributors unless the authenticated account can see it, so the script also filters visible org membership plus profile/company/bio hints as a secondary layer.
Example when the user names another extra internal org:
python3 .agents/skills/top-contributor-finder/scripts/find_top_contributors.py \
--repo your-org/your-repo \
--since <YYYY-MM-DD> \
--exclude-org another-internal-org
Step 2: Review automated ranking and prefiltering
Read the generated JSON and understand what the script included or skipped before doing deeper evaluation. This step is about checking the automated triage, not making the final recommendation.
Useful fields include:
human_context.summary: one-sentence summary of what the contributor appears to be doinghuman_context.contribution_themes: inferred areas such as core features, integrations, platform support, security/privacy, docs/tooling, or UI polishhuman_context.contribution_style: whether the contributor is merged-PR heavy, open-PR heavy, issue-discussion heavy, or mostly low-substance so farhuman_context.issue_vs_pr_activity: supporting counts and a plain-language issue-vs-PR readhuman_context.collaboration_signals: contributor-actionable signals such as requested changes, failing checks, merge conflicts, CLA identity issues, or issue-readiness guidancehuman_context.relationship_context: profile/repo/ecosystem hints useful for outreach or partnership contexthuman_context.what_to_watch_next: weekly follow-up prompts, such as whether open PRs landed or whether issue discussion turned into implementationrecommended_action: the script's draft action category (outreach, monitor, or manual review), to confirm or revise after reviewing all evidencecheap_prefilter_counts: the cheap merged/open signal used before expensive enrichmentskipped_low_signal_logins: contributors skipped before expensive enrichmentissue_activity: representative authored/commented issuesopen_pr_concern_summary: contributor-actionable open PR problems worth surfacingopen_pr_normal_state_summary: normal process states retained as metadata, such as review required or final reviewopen_pr_blocker_summary: raw/backcompat summary of inferred open PR statesinferred_blockers: per-PR state hints inferred from metadata, checks, and recent comments/reviewssearch_notes: GitHub Search result counts and any cap/incompleteness notescontributor_rollups: compact records intended for ranking cumulative top contributors and identifying recent activity from PR timestamps
Confirm that the defaults did not exclude a contributor the user explicitly cares about. If the user wants a broader audit, rerun with lower thresholds before making recommendations.
Step 3: Evaluate open PR concerns
For open PRs, surface only concerns that suggest the contributor may need guidance or needs to take action. The script keeps raw inferred_blockers, but report-writing should distinguish contributor-actionable concerns from normal repo process states.
Contributor-actionable concerns to surface:
- draft PR
- merge conflicts
- failing or incomplete checks
- changes requested
- issue not marked
ready-to-implement or ready-to-spec when the contributor appears to be outside the expected process
- CLA identity issue
Normal states to retain as metadata but not report as blockers by default:
- review required
- waiting for final review or merge
- manual testing proof, screenshots, or video requested as part of normal PR review
Open PRs are positive signal only when the contributor appears responsive and the work is meaningful. Do not frame normal maintainer review queues as a contributor problem.
Step 4: Review profile and ecosystem context
For each serious candidate, review:
- GitHub display name, bio, company, location, website, Twitter/X if present
- owned repositories with stars and descriptions
- organizations
- recent repositories contributed to
Look for relationship/partner signals:
- maintains a relevant OSS project
- contributes to relevant open-source ecosystems, frameworks, or developer tools in your product's space
- works at a relevant devtool, AI, infra, or open-source-friendly company
- has public projects that could become collaborator/grantee/sponsorship conversations later
Do not overstate profile findings. Say “potential signal” unless the profile clearly establishes maintainership or project ownership.
Step 5: Apply final human judgment
After reviewing PR evidence, issue activity, profile/ecosystem context, and the current contributor cohort, decide whether each candidate's draft recommended_action should stand or be revised. The script is a starting point; it cannot fully judge product importance, reviewer sentiment, whether a PR is strategically important, whether the contributor stands out relative to others this period, or whether relationship context changes the outreach priority.
Prefer contributors with:
- a meaningful merged track record that stands out relative to the current cohort
- fewer but deep PRs in strategic areas such as core features, integrations, platform support, i18n, security/privacy, or workflow reliability
- open PRs that are close to merge or clearly promising
- good review behavior: responds to feedback, rebases, clarifies scope
- profile/repo signals suggesting relevant product-space experience, OSS maintainership, or ecosystem credibility
Deprioritize contributors whose PRs are mostly:
- typo fixes
- comment-only cleanup
- formatting-only docs changes
- unmerged PRs with repeated unaddressed review feedback
- open-only activity that is not yet notable relative to the current cohort
For the final report, treat human_context and recommended_action as draft memory that should be refined with this full evidence review.
Report format
Use this structure:
Executive recommendation
State:
- recommended first outreach batch size
- who should be highlighted or contacted first
- who should be monitored briefly
- who should be skipped
Ranked contributor list
Use one ranked list rather than separate “strong outreach” and “watchlist” lists unless the user explicitly asks for separate buckets. For each candidate, include:
- GitHub handle with profile link
recommended_action from the generated JSON, with a short human explanation- why they are ranked where they are
- strongest merged PRs with inline links, e.g.
[PR #<PR_ID>](https://github.com/your-org/your-repo/pull/<PR_ID>)
- open PRs with inline links and contributor-actionable concern only when there is one; omit normal review/final-review/manual-testing states from the main report
- profile/repo/ecosystem signal
Interpret recommended_action as draft memory only:
outreach: likely relationship-building candidate after final human judgmentmonitor: visible signal worth keeping in the generated JSON for the current run, but the agent should decide whether it is notable enough to mentionmanual review: passed thresholds but needs human judgment
Do not use action labels as the final ranking. Decide who counts as a top contributor by comparing contribution substance, merged/open activity, issue participation, profile/ecosystem context, and the strength of the current cohort.
Skip for this batch
List contributors excluded because they are internal, issue-only, typo-only, docs-only, not enough merged signal, or have unresolved contributor-actionable quality/process concerns.
Suggested outreach
Include this section only when the user wants outreach or relationship-building. Keep the action generic: recommend outreach, recognition, or a thank-you. Do not prescribe specific offers such as swag or credits unless the user asks.
Optional Slack thread to a report channel
Only post to Slack when the user explicitly asks to post or send the report. Do not create or rely on a dedicated Slack-posting script; the agent should decide the most valuable thread from the current generated JSON and post it directly using the available Slack credentials. Never print, echo, or store Slack tokens in plaintext.
Default destination: a configured report channel (e.g. #your-report-channel). Resolve the channel ID from available environment/configuration or Slack context before posting; if it cannot be resolved, ask the user for the channel ID rather than guessing. Use Slack mrkdwn and avoid accidental pings by formatting GitHub handles in backticks, e.g. @contributor_handle.
Weekly comparison approach
Before drafting the Slack thread, use the current cumulative generated JSON as the source of truth. Do not require previous artifacts. Identify recent changes from each contributor's PR and issue dates, especially mergedAt, createdAt, and updatedAt.
Use these practical groups for the Slack report:
- New or newly important top contributors: contributors who now stand out enough for the team to know about, especially if their meaningful activity is recent. Give these contributors full thread replies.
- Established and active top contributors: cumulative top contributors who also have meaningful recent work. Summarize them briefly; do not repeat the full profile every week.
- Established but quiet top contributors: cumulative top contributors with little or no recent activity. Surface them briefly only if the quiet period is useful context.
- Low-signal or unchanged contributors: omit them or group them in a very short parent-note count. Do not create thread replies for unchanged known contributors or low-signal open-only contributors.
Do not create a separate Slack category for “not outreach yet.” Do not include contributors merely because their open PRs have concerns. Open PR concerns can inform judgment, but the Slack report should focus on contributor relationship and repo-health signal, not PR triage.
Parent message
Keep the parent message concise and useful for teammates skimming Slack. Do not lead with analysis-window mechanics such as “since project launch,” “analysis period,” or “stateless cumulative run” unless the user explicitly asks for audit details. Include:
- repo being summarized
- 1-2 sentence summary of the most important contributor findings
- new/newly important top contributors worth knowing about
- established active top contributors in one short line
- established quiet top contributors, if useful
- suggested action, using generic wording such as
outreach, monitor, or no action
- a link to the agent session/conversation so teammates can continue the analysis with the agent
Thread replies
Create one thread reply per contributor only for contributors worth surfacing. Use full detail only for new or newly important top contributors. A full reply should include:
- GitHub handle and profile link
- why they matter now
- 1-3 strongest PR links
- concise contribution themes
- suggested action, usually
outreach or monitor
For established top contributors, use short replies only when there is meaningful recent activity. Otherwise mention them in the parent summary only when useful.
Posting mechanics
When posting is requested:
- Draft the parent message and thread replies first.
- Post the parent with Slack
chat.postMessage and capture its ts.
- Post each contributor reply with the same channel and
thread_ts set to the parent ts.
- Use
unfurl_links: false and unfurl_media: false.
- Include the agent session/conversation link in the parent message or final thread reply. Use a /<CLOUD_PRODUCT>-provided conversation or run link when available; do not fabricate a link. If no session link is available, say that instead of guessing.
- After posting, report the Slack permalink or parent timestamp to the user.
If posting fails partway through, tell the user which messages posted and which failed.
Quality checklist
Before finalizing:
- Every referenced PR or issue has an inline link.
- Merged and open PRs are clearly distinguished.
- Open PR concerns are described only when they are contributor-actionable and visible from GitHub.
- Internal contributors, bots, and org members are filtered out.
- Typo-only and issue-only contributors are not in the top outreach list.
- Profile/repo claims are grounded in GitHub profile data.
- Recommendations are concise enough to act on immediately.
Performance guidance
The slowest operations are, in order: detailed gh pr view calls for every PR search hit, GraphQL profile/repository enrichment for every contributor, org membership checks, and issue author/commenter searches. Avoid pulling all of those for contributors with only one likely meaningful merged PR and little or no open work unless the user explicitly wants an exhaustive audit. Contributor profile/internal checks and detailed PR enrichment run concurrently via --enrichment-workers (default 4; use 1 for serial execution). GitHub Search collection remains mostly sequential to avoid making Search rate limits worse. GitHub rate limits are waited and retried by default up to --max-rate-limit-wait-seconds; if the reset is beyond that, the generated JSON records the missing issue-search context in search_notes.
Validation
This skill does not bundle formal evals because the final output is judgment-heavy and depends on live GitHub state. Validate changes with a Python compile check, a small smoke run of the helper script, and qualitative review of the generated candidate output.
