serhiy-bzhezytskyy
UserClaude Code skills for contributing to someone else's repo — each rule backed by a real receipt. Bring help, not noise.
Categories
Indexed Skills (31)
comments-about-code-not-change
Source comments explain what the DELIVERED code does, in the present tense — never the change history: no issue/PR numbers, no maintainer @handles, no "the previous code did X", no "confirmed by", no "aligned per". Change-narrative in source is a top AI tell, and it rots in the codebase; that context belongs in the PR body and commit message. Grep the diff's added comment lines before every push. Use before committing any code change to a repo you don't own. Trigger terms: code comment, "// previously", issue number in comment, @handle in source, over-explaining, AI smell, delivered documentation.
consolidate-a-scattered-thread
When a maintainer says "unclear where this should live" or "unclear where to further that conversation," the high-value move is not to reply in place — it's to do the consolidation FOR them. Traverse the JIRA/GitHub link graph across every linked ticket, read ALL comments plus related PRs, commits, and mail, untangle the conflated concerns into distinct threads each with a home, verify each claim in code, and hand back a map: "here's where each sub-thread belongs." This is a SOURCING/communication move — it turns a maintainer's "where do I continue?" into a delivered map. Use when a discussion is fragmented across many tickets/PRs and a maintainer signals they can't see the shape. Trigger terms: unclear where this belongs, fragmented discussion, scattered across tickets, link graph, issuelinks, consolidate, untangle, which issue tracks this, where should this live.
match-the-house-shape
Before shaping a PR, mine what ACTUALLY merges in this house — the median churn, changed-file count, title convention, and test-touch rate of recently merged PRs — and size/shape your contribution to that median. A reviewer's implicit expectation is set by what they routinely merge, not by what CONTRIBUTING.md states; a PR in the house's usual shape is cheaper to review and so more likely to land as help. Measured on Apache Solr: 3,510 merged PRs settle on a clear median shape (churn 58, 4 changed files, 67.6% JIRA-key titles, 4.0 d to merge). Use before opening a PR, after picking the work. Trigger terms: house shape, median PR size, right-size the PR, split the PR, title convention, what actually merges.
no-force-push-a-reviewed-pr
On a PR that already has reviewers, push follow-up changes as plain new commits only — never `git commit --amend`, never `git push --force` / `--force-with-lease`. Force-push rewrites the commits reviewers' inline comments anchor to, resets the GitHub review state, and forces a cold re-read — the opposite of the incremental trust you are building. Use whenever you push any change to a PR someone has already looked at. Trigger terms: force-push, --amend, --force-with-lease, rebase, "clean up history", pushing to an under-review PR.
obey-the-houses-own-tooling
Before generating any project artifact a repo has a generator for (changelog, formatted source, build/lock files, license lists), create it with the repo's OWN documented tooling — never hand-craft a file a task owns. A maintainer detects careless or AI-assisted work by tool BYPASS, not by code style: a hand-made file doesn't match the pattern the generator produces. Use before writing any file the project ships a task/command for, and before saying "done". Trigger terms: changelog, AGENTS.md, gradle task, tidy, formatter, generated file, lock file, "it compiles and tests pass".
offer-dont-grab
To work an issue that's assigned to a maintainer, is the maintainer's own design, or has a dormant prior attempt: check whether the assignment is actually dormant (last activity, has the assignee ever commented, any linked PR), build a TDD-verified fix, then OFFER it — credit the prior work, ask the design question, open the PR on the maintainer's nod. Do NOT silently open a PR that grabs owned work. Assigned ≠ actively-worked; the rule is offer-don't-grab, not avoid-don't-touch. Use when the best-fit issue is already owned or has a stalled attempt. Trigger terms: assigned issue, dormant, stalled PR, "I'll take this", credit predecessor, revive, take over.
one-fix-one-pr-then-coordinate
Use when one investigation produced fixes for several related issues and you are deciding how to package them. Split by ISSUE — one PR per issue, each proven to stand alone on a clean base — rather than shipping the branch you happened to develop on. Then coordinate the cluster instead of flinging PRs: answer any open reviewer concern on the live PR FIRST, open the spin-offs, credit each reporter's own dig, and post ONE hub comment on the neutral root ISSUE linking the whole web. Never bundle independent fixes because they share a branch, and never bump a contested PR with cross-links. Trigger terms: several fixes one branch, split the PR, one PR per issue, bundle, cluster of issues, related PRs, spin-off, hub comment, cross-link, how do I package this, stacked fixes.
sign-off-the-house-way
Before opening a PR, know which contributor sign-off THAT house requires and make sure it's present — the contracts differ by house and a missing one is an instant, automated "didn't read the rules" bounce. Eclipse projects (e.g. Jetty) gate every PR on an ECA plus a DCO `Signed-off-by` trailer on each commit; Apache projects (Solr/Lucene) use a CLA with the committer resolving on merge and need no per-commit trailer; other houses need neither. Check the house's contract first, not after a bot rejects you. Use at front-gate, before the first commit. Trigger terms: DCO, ECA, CLA, Signed-off-by, sign-off, `git commit -s`, eca check, contributor agreement.
write-in-your-own-voice
The PROSE you put in front of humans — PR body, issue text, review replies — should read as your own terse voice, not the generic-LLM register maintainers spot instantly ("comprehensive", "robust", "leverages", "this PR addresses the issue where…", over-hedged padding). AI-register prose gets flagged; house-voice prose lands. Cut the jargon, say what changed in one plain line, and match the house's short PR-body length; optionally few-shot from your OWN merged PRs to calibrate. Use when drafting any human-facing text on a repo you don't own. Trigger terms: PR body voice, AI tell, generic LLM prose, comprehensive/robust/leverages, press- release tone, write plainly, own voice.
port-the-report-upstream
Use when the repo you found a bug in is a fork or port of another project and you are asking whether the original still has the same bug — or whether to report it there too. A port inherits its parent's bugs, so a defect found downstream is probably still live upstream, and vice versa. Check it, then report in both houses with each artifact cross-referencing its counterpart. But re-derive every anchor against the OTHER repo's own origin/main: line numbers drift, subcommands get deprecated, issue numbers autolink to the wrong project, label sets differ, and one house requires a DCO sign-off the other doesn't. Never copy a claim across a fork. Trigger terms: fork, port, upstream, downstream, vendored, same code, inherited bug, does upstream have this, does the original have this, is this fixed upstream, report it upstream too, cross-reference.
track-whose-court
To answer "is anything waiting on me?", run a channel-complete status check across EVERY channel a maintainer can reach you on — GitHub PR issue-comments, GitHub inline review-comments, GitHub reviews, watched-issue comments, ASF JIRA, and the dev@ mailing list — plus git diffs as a seventh source. Compare the last HUMAN commenter (filtering commit-bot authors) to you to decide whose turn it is. Hand-checking one channel silently misses the others. Use on any "check status" / "whose turn" / "anything waiting on me" request. Trigger terms: check status, whose court, turn tracking, ball on me, follow-up, did they reply, nudge vs wait.
use-the-tool-for-its-purpose
To find real bugs in an unfamiliar project, don't audit its code hunting for smells — USE the tool for its actual purpose, on real data, at realistic N. The defects that survive green CI live in the step everyone skips: the gap between "it ran" and "you have a result" (aggregate, compare, report, export, the second run). Then reproduce each finding against the REAL method with a passing control, rule out your own setup, and check whether the thing you call missing is actually documented. Use when picking what to contribute in a repo you don't know. Trigger terms: find a bug, what should I fix, unfamiliar repo, where to contribute, audit the code, N=1, test-mode, demo path, real data.
verify-before-a-committer-comment
Before asserting a technical claim in a public JIRA/PR/committer-facing comment — "PR X fixes Y", "the bug is in layer Z", "test T still fails", "commit C did D" — verify it by reading the actual code path and running the test on clean state. Do NOT infer from PR titles, commit messages, or the issue link-graph. State your confidence (verified / inferred / open). A confident-wrong claim to a committer, especially about your OWN PR's scope, costs trust fast. Use before any committer-facing technical assertion. Trigger terms: post a comment, "this fixes", root cause, which layer, still fails, commit did X, assumed or checked.
discuss-in-issue-first
For a non-trivial change, open or comment on the tracking issue and get the approach discussed BEFORE opening the PR — to make the change land FASTER, not to make it more likely to be accepted. Measured on Apache Solr: PRs with prior issue discussion merged at a median 3.4 days vs 5.8 days for cold PRs (~1.7× faster, p<0.001), with NO difference in merge rate (both ~83%). So discuss first to move faster, not to get in. Use before opening a PR for anything beyond a trivial typo/dep-bump. Trigger terms: issue-first, discuss first, open an issue, cold PR, RFC, design before code, faster merge.
follow-the-thread
When a red CI test, a failing check, or a single bug crosses your path, follow it instead of dismissing it — one thread reliably sources many issues worth working. A failing test maps to an existing issue whose root cause is often an existing UPSTREAM bug; fixing that means reading the surrounding subsystem, where adjacent open issues surface; searching near it seeds the next. A convenient "it also fixes X" is a hypothesis, not a finding — verify the mechanism. A SOURCING method: it finds where the help actually is, before any PR. Use when you hit a red CI, a flake, or one bug — and equally when a MAINTAINER hands you a lead in passing ("not fully related to this issue, but…", "years ago I…", "that's always been fragile"), the same method from the other end. Trigger terms: red CI, flaky test, follow the thread, upstream root cause, adjacent issue, sibling bug, "not my bug", where's the real work, reviewer mentioned something unrelated, offhand remark in a review, act on that comment.
read-the-houses-agent-file-first
Before applying ANY skill in this repo, look for the house's own agent instructions — AGENTS.md (or CLAUDE.md, or any other agent-instruction file the house ships) — read it, and treat it as the higher authority. Where the house's file contradicts a skill here, the HOUSE wins: these skills are cross-house defaults, its file is local law. A house that ships an AGENTS.md has told you exactly how it wants agent-assisted work done; ignoring it while following a generic rulebook is the fastest way to read as noise. This is the meta-skill that runs first, before the rest of the front-gate. Use when starting on any repo you don't own, before invoking any other skill here, or when two rules conflict. Trigger terms: AGENTS.md, CLAUDE.md, agent-instruction file, agent instructions, house conventions, which rule wins, precedence.
nudge-with-new-information
Use when a PR or issue has gone quiet and you are deciding whether to post a reminder, ping, or "any update?" — and what to put in it. Many houses explicitly invite reminders, so the question is not whether nudging is rude but whether this nudge will land: is it genuinely their turn, is the silence actually past the house's own measured response time, and does the message carry a fact the reader does not already have. A bare reminder can still work where the house invites one, but a reminder carrying a fact costs you nothing extra and cannot be resented, sent to the wrong thread, or burn the single follow-up you have. Never batch one sentence across several threads. Trigger terms: nudge, ping, follow up, any update, bump, reminder, chase a review, no response, gone quiet, stalled PR, how long should I wait, is it too early to ask.
read-the-projects-origin-story
Use when you are about to PROPOSE something to a young project or subproject — a design, a new capability, a discussion thread — and want to know why it is the way it is: who built it, what it was chosen over, what its authors already called incomplete, and which design arguments are still unresolved. Read the discussion arc that CREATED the repo before proposing to it. Its founding threads name the known-incomplete edges (so you don't report them as discoveries), the objections its own committers recorded (so you don't reopen them), and who actually cares about your area — none of which git history or CONTRIBUTING can tell you. For "does the ORIGINAL of this fork still have the same bug?" use port-the-report-upstream: that is code lineage, this is decision history. Trigger terms: new subproject, young repo, why does this exist, what did they already decide, project history, founding thread, VOTE thread, was this discussed before, prior discussion, before I propose, am I repeating something, is this wanted.
state-the-noise-floor
Before you put a NUMBER in front of a maintainer — "N tickets affected", "X% of cases", "this run is 13% slower" — establish what that same number would be if nothing were wrong, and report the ratio. Build the floor by comparing against something that SHOULD be identical: repeat the measurement (N≥5), or shuffle the one variable your claim depends on and keep everything else fixed. If the signal is under ~2x the floor, say so yourself before the reviewer does. Use when you are about to quote a count, a percentage, or a performance delta in an issue, PR description or mailing-list post. Trigger terms: benchmark, regression, faster, slower, N tickets, X percent, how many, count, delta, improvement, is this significant, noise, variance, baseline.
answer-only-what-was-asked
Use when a maintainer asks for something mechanical — rebase, squash, rename, drop a file, apply a suggestion — and you are about to write a comment about having done it. The verification you run before pushing is for you; it is not the reply. GitHub already shows the force-push, the new commit and the green check, so a comment restating them adds reading cost and nothing else. Worse, a report of your own thoroughness reads as seeking credit for the request itself. The rule: do the mechanical thing, say at most that it is done, and say nothing when the timeline already says it. Comment only when you carry something the diff cannot show. Trigger terms: rebase, squash, force-push, "can you rebase", "needs a rebase", applied the suggestion, addressed the comments, done, updated, pushed, "I have verified", test summary in a comment, replying to a review comment.
measure-before-you-widen
A fix has landed in one component, and a second component calls the same routine, so it looks like it has the same defect. Do NOT widen on the strength of the reading: measure the second component on the same axis as the first — same input or corruption method, same outcome buckets, both results reported side by side — and let the numbers decide. The structure around a shared call decides the exposure, not the call itself, and the measurement usually finds something the reading missed. Use when about to extend a fix, a format change, or a hardening pass to a neighbouring component "because it's the same problem". Trigger terms: same vulnerability, also affected, extend the fix, third commit, consistency argues for, while we're here, same code path.
build-the-alternative-before-you-choose
When a design decision is defended in prose — "the alternative is a bigger design", "arguably correct", "that's out of scope", "that's the maintainer's call" — build the alternative (or measure the deferred claim) before recording the choice. A rejected-by-argument option costs a paragraph and settles nothing; a rejected-by-measurement option costs an hour and ends the debate, including the future re-litigation in review. Words that trigger this: arguably, probably, bigger design, out of scope, their call, we assume. Use when you are about to record a design choice whose alternative was rejected in prose rather than measured, or to defer a claim to someone else's judgement. Trigger terms: design trade-off, alternative considered, out of scope, arguably, defer to maintainer, prototype, spike, measured choice.
do-the-work-before-you-offer-it
A reviewer's comment reveals more work than the PR covers, and the courteous-looking reply is "I can extend it to those too if you prefer". That offer spends the one thing a reviewer has least of — a round-trip of attention — to authorise something you could already have finished and measured. Do the work, verify it, then report it; ask only when the answer changes what you build in a way you cannot cheaply undo. A finished patch with numbers is a smaller ask than a question. Use when a draft reply contains a conditional offer, a "whichever you prefer", or a request for permission to do something no one is blocking. Trigger terms: if you prefer, whichever you'd like, shall I, should I also, let me know if, worth fixing, I can extend, happy to, want me to.
fuzz-before-you-claim-done
Before declaring a runtime-semantics change "done and verified", run a seeded property sweep over randomized inputs (graph shapes, schedules, interleavings) with invariants instead of expected outputs, plus instrumentation (TRAP logs) on the mechanism under test — because your hand-picked tests encode your own assumptions, and a design can be green on every one of them and still wrong. Two prior designs in the same arc were green on 1,638 tests and both double-fired. Make failures reproducible by seed alone. Use for schedulers, barriers, retry logic, caches, state machines — anything whose input space is combinatorial. Trigger terms: done and verified, all tests pass, edge cases covered, chaos test, property test, seeded fuzz, invariant, interleaving, crash test.
grep-the-types-statics-first
Before writing any logic over a type the project owns — merging, defaulting, unwrapping, normalizing, converting — grep that type's own static/factory methods and search the codebase for the verb you need. A mature codebase has already solved it, with the edge cases handled and a name the reviewer reads fluently. A plausible hand-rolled helper is worse than a bug: it compiles, it passes, and it reads to a maintainer as unfamiliarity with the house. When you do find the helper, check its RETURN TYPE against your call site before swapping, and verify by running rather than reading. Use before writing any utility loop over a house type. Trigger terms: helper method, merge params, apply defaults, unwrap, convert, write a small utility, is there an existing, reinvent, "I'll just loop over".
point-the-cheap-probes-at-young-code
Use when you need to FIND work in an unfamiliar repo rather than pick it off a tracker — a new house, or one whose issue backlog is claimed faster than you can read it. Four probes cost minutes each and need no domain knowledge: does any test fail when run alone, does the suite survive a shuffled order, does the race detector fire, does a fuzz target crash. Each one asserts on the SELECTOR'S YIELD, never on the exit code, because every runner treats "matched nothing" as success. And the yield of these probes is a function of the codebase's age and hardening, not of your effort: four probes over a thirteen-year-old repo with OSS-Fuzz integration found nothing in an hour, and the same shuffle probe found a real defect on a three-year-old fork in one run. Trigger terms: new repo, where do I start, find a bug, no good first issues, backlog is claimed, flaky, test isolation, order dependent, -shuffle, -race, go test, cargo test, runtest.
price-the-door-before-you-enter
A repo has thousands of open issues, a friendly CONTRIBUTING and an obvious defect you could fix, and none of that tells you whether a contribution can land. Open issues measure demand; the merge path measures supply. Before reading a single issue, price the door with four queries — open PRs and how many are stale, merged vs closed-unmerged over the same window, created-to-merged latency, and the author spread of recent merges — then read the licence and the CLA acceptance mechanism, because in some houses opening the PR *is* the signature. Two houses with the same open-issue count can differ by a factor of fifty in whether an outsider's PR merges. Use before forking, before writing code, and before promising anyone a contribution in a repo you have not landed in. Trigger terms: can we contribute to, scout this repo, first PR into, new house, is the door open, worth entering, good first issue, they have lots of open issues.
red-team-your-own-diff
A revision is written, the tests are green, and the temptation is to push. Attack it first as the specific reviewers would — from their recorded rules, not from generic good practice — and resolve each objection with a measurement rather than an argument. Their standing asks are enumerable from what they have written on other PRs: never force-push, a test must hit the changed line, no unrelated changes, comment every test, minimise the diff for cherry-picking. Attack the packaging too: the title after a widened scope, comment symmetry, the shape of the helper, how the commits split. Use before pushing a revision, before replying to a review, and whenever a change grew past what the reviewer asked for. Trigger terms: ready to push, address the review, before I send this, self-review, is this mergeable, did I miss anything.
run-a-control-before-you-trust-the-number
Use when a harness, script or query has just produced a number you are about to act on — put in a PR body, use to rank options, or use to decide a change is unnecessary. A broken measurement almost never raises an error; it returns a plausible answer. So before trusting the instrument, run a probe whose correct output you already know and that the broken state CANNOT produce. Also check the three silent distortions: a suppressed error read as an absence, a window of N items read as a window of time, and a cross-product reported as coverage. Trigger terms: benchmark, A/B, measured, the numbers say, 0 hits, no difference, nothing found, last N commits, N x M, ranked by, harness, probe, sweep, no measurable cost, tests pass so it works.
run-the-bots-review-before-it-does
Many repos now run an automated reviewer that comments before any human does — Cursor Bugbot, Copilot, Sourcery, a CodeQL bot. It is not authority and it is not noise: its findings are public across the whole repo, so its rulebook is harvestable, and it lands first, which means an unanswered Medium-severity comment is what the human reviewer sees first too. Harvest what it has flagged on other PRs, derive the checklist, run that checklist yourself before pushing, and when it does find something, answer with a measurement rather than an opinion. Use before pushing into a repo with an automated reviewer, and whenever a bot finding needs a reply. Trigger terms: bugbot, cursor bot, copilot review, automated review, bot comment, medium severity, the bot found, AI reviewer.
run-the-validators-ci-runs
A green local build does not mean a green CI. Projects skip expensive validators (errorprone, RAT, forbidden-apis, license checks) on developer machines and enable them only in CI, where the same warning becomes a hard failure under -Werror. So "check passed locally" can be true while CI is red on the very file you just changed. Before claiming a change is done, find the project's opt-in flags for the validators its CI enables, and run with them. And when a validator does fire, fix the RULE across the whole diff — not the one line the reviewer pointed at. Use before saying "done", "green", or "ready for review". Trigger terms: check passed, build is green, CI is red but it works locally, errorprone, -Werror, lint failure, skipped on builds not running inside CI, warnings found.
Bio shown is the top-scored skill's repo description as a fallback — real GitHub bios land in a future update.