engineering-small-prs — Claude Code skill: what it does
engineering-small-prs turns a large feature, refactor or migration into small pull requests, with a merge order and a rollback plan.
MIT 133 installs ★ 635 updated 2026-09-29
npx skills add agentara/skills --skill engineering-small-prs -a claude-codeWhat engineering-small-prs does
The skill picks up where a single review can't hold the change: a big feature, a refactor, a migration. It doesn't write the code. It lays out the plan instead: the end goal in one line, the separate pieces of work, the dependencies between them, and a merge order that keeps the build green after each step.
Split strategies come with it. Tests around current behavior before a risky refactor, a behavior-preserving cleanup first, vertical slices that ship one visible piece end to end, config and mechanical rewrites kept apart. Migrations follow expand/contract: compatible schema first, backfill with progress tracking, cutover, then a cleanup PR. The answer arrives as a table of PRs with purpose, dependencies, tests and notes for the reviewer.
A reviewer is allowed to reject a PR for size alone, and that rule is what the skill builds on. It stays out of full code review, PR descriptions and single-file edits. When something truly can't be split, it asks for the reviewer's agreement before the PR goes out.
What it helps with
- split an oversized diff into reviewable pull requests
- order the merge so no PR breaks the build
- plan an expand/contract schema migration with rollback
- separate a refactor from the behavior change hiding in it
- get reviewer sign-off before an unavoidable large PR
Example prompts for the agent
- Split this diff into reviewable chunks, it's too big to review as one PR.
- Plan a stacked PR sequence for the schema migration, with deploy order and rollback.
- How should I break this refactor up, and in what order do the PRs land?
How to install engineering-small-prs
1Skills CLI (Vercel)
npx skills add agentara/skills --skill engineering-small-prs -a claude-code2Manually: put the files in place
~/.claude/skills/engineering-small-prs/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/engineering-small-prs/
1Skills CLI (Vercel)
npx skills add agentara/skills --skill engineering-small-prs -a codex2Manually: put the files in place
.agents/skills/engineering-small-prs/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add agentara/skills --skill engineering-small-prs -a cursor2Manually: put the files in place
.cursor/skills/engineering-small-prs/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install agentara/skills skills/engineering/engineering-small-prs2Manually: put the files in place
.github/skills/engineering-small-prs/SKILL.md1Skills CLI (Vercel)
npx skills add agentara/skills --skill engineering-small-prs -a gemini-cli2Platform CLI
gemini skills install https://github.com/agentara/skills --path skills/engineering/engineering-small-prsManually: put the files in place
.devin/skills/engineering-small-prs/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add agentara/skills --skill engineering-small-prs -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about engineering-small-prs
How do I install engineering-small-prs in Claude Code?
Run npx skills add agentara/skills --skill engineering-small-prs -a claude-code. The skill lands at ~/.claude/skills/engineering-small-prs/SKILL.md.
What does engineering-small-prs do?
It plans how to cut a large feature, refactor or migration into small self-contained PRs and returns a table with the merge order, tests and dependencies.
Does it review code or write PR descriptions?
No. Full code review, PR description writing and tiny one-file edits sit outside its trigger conditions. It handles the split and the sequence.
Source text
SKILL.md · MIT
--- name: engineering-small-prs description: > Use when planning, splitting, shrinking, or sequencing large features, refactors, migrations, or pull requests into small reviewable PRs or CLs. TRIGGER on "split this PR", "this diff is too large", "stacked PRs", "change sequence", "reviewable chunks", "migration plan", "how should I break this up?", or implementation scope too broad for one review. DO NOT TRIGGER for full code review, PR description writing, or tiny one-file edits that already form one self-contained change. --- # Engineering Small PRs Small PRs are easier to review thoroughly, safer to merge, easier to roll back, and less likely to waste work if the direction changes. "Small" means conceptually focused and self-contained, not merely a low line count. Adapted from Google Engineering Practices Documentation, especially "Small CLs." Source: <https://google.github.io/eng-practices/review/developer/small-cls.html>. License: CC-BY 3.0. ## Definition of a Good Small PR A good PR: - Makes one self-contained change. - Includes the tests needed to validate that change. - Leaves the system working after merge. - Gives reviewers enough context in the PR, description, existing code, or earlier reviewed PRs. - Is not so tiny that the behavior cannot be understood. A new API usually needs at least one usage in the same PR. - Separates large refactors from behavior changes unless the cleanup is very local. Reviewers may reasonably reject a PR solely because it is too large to review well. ## Splitting Workflow 1. Name the final outcome in one sentence. 2. List independent behavior changes, refactors, schema/config changes, tests, and docs. 3. Identify dependencies that must land earlier. 4. Choose split strategies from the section below. 5. Build a merge sequence where every PR keeps the build green. 6. Add context notes so reviewers understand how each PR fits into the larger work. 7. For risky or unavoidable large changes, get reviewer consent before sending the PR. ## Split Strategies - Preparatory tests first: add missing tests around existing behavior before risky refactors. - Refactor first: move, rename, extract, or simplify code without changing behavior. - Vertical slices: deliver one small user-visible or API-visible behavior end-to-end. - Horizontal slices: add shared interfaces, protocol definitions, or adapters only when paired with a real first usage in the same PR or a clearly linked dependent PR already under review. - File or owner groups: split files by reviewer expertise when the changes are otherwise self-contained. - Config separately: keep rollout configuration, experiments, or deployment wiring separate from code when rollback timing differs. - Generated or mechanical changes separately: isolate trusted automated rewrites from hand-written logic. - Deletions separately when useful: removing dead code can be a compact, easy-to-review PR. ## Migration Safety For schema, data, API, or infrastructure migrations, prefer an expand/contract sequence: 1. Expand: add backward-compatible schema/API/config support without removing old behavior. 2. Dual path: write or read both paths only when needed, with observability for divergence. 3. Backfill: migrate existing data with progress tracking, retry behavior, and validation. 4. Cut over: switch traffic or callers after validation proves both paths are safe. 5. Contract: remove old schema, code paths, flags, and compatibility shims in a cleanup PR. Each migration PR should state deployment order, rollback behavior, validation signal, and what must not happen until the next PR lands. ## Output Template ```markdown ## Goal [Final outcome] ## Proposed PR Sequence | # | PR | Purpose | Depends On | Tests | Reviewer Notes | |---|----|---------|------------|-------|----------------| | 1 | Add characterization tests for ... | Protect existing behavior before refactor | None | ... | ... | | 2 | Extract ... without behavior change | Prepare smaller implementation | 1 | ... | ... | | 3 | Implement ... vertical slice | User-visible behavior | 2 | ... | ... | ## Migration Safety - Expand/contract phase: - Backfill/validation: - Observability: - Rollback: ## Build Safety - Each PR keeps: - Rollback notes: ## Large-Change Risk - What could not be split: - Reviewer consent needed: ``` ## Heuristics - Prefer a PR that is smaller than you think necessary; reviewers rarely object to focused changes. - If a PR spreads a small logical change across many files, treat it as larger than the line count suggests. - If the reviewer needs substantial future context to understand the PR, the sequence is probably missing an earlier preparatory PR or a better description. - If you cannot split the PR, make it extra easy to review: stronger tests, clearer description, explicit risk, and prior reviewer agreement. ## Common Mistakes - Mixing broad formatting changes with functional logic. - Landing a new abstraction with no real usage. - Creating a stacked sequence where intermediate PRs break the build. - Hiding risky behavior change inside a "refactor" PR. - Waiting for one PR to merge before starting the next when a safe stacked workflow is available.
© agentara · MIT · agentara/skills