Skip to content
Skills Library
Programming · Writing

pull-request-authoring

/pull-request-authoring

Use when opening a pull request — writing the description, sizing the change, and making it easy and fast to review. Covers PR structure, what reviewers need, and how to keep PRs small enough to actually get good review.

Repository
md-files ↗
Licence
MIT
Last repository change
03.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 03.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when opening a pull request — writing the description, sizing the change, and making it easy and fast to review. Covers PR structure, what reviewers need, and how to keep PRs small enough to actually get good review.

Original author description

Use when opening a pull request — writing the description, sizing the change, and making it easy and fast to review. Covers PR structure, what reviewers need, and how to keep PRs small enough to actually get good review.

How it works

  1. Size it to be reviewable
  2. Description structure
  3. Before you open it
  4. Reviewer experience
  5. Stacked pull requests
  6. Anti-patterns
Original SKILL.md headings · 69 lines, 399 words
SKILL.md preview
---
name: pull-request-authoring
description: >-
  Use when opening a pull request — writing the description, sizing the change, and
  making it easy and fast to review. Covers PR structure, what reviewers need, and
  how to keep PRs small enough to actually get good review.
---

# Pull Request Authoring

A PR is a request for someone's time and trust. Make it cheap to grant: small, clearly
motivated, and easy to verify.

## Size it to be reviewable

Small PRs get better review and merge faster. Aim for a focused change a reviewer can
hold in their head — roughly under ~400 lines of meaningful diff. If it's bigger, split
by concern: refactor separately from behavior change; mechanical changes (renames,
formatting) in their own PR so the substantive diff stands out.

## Description structure

```text
## What
<one-paragraph summary of the change>

## Why
<the problem or motivation; link the issue/ticket>

## How
<the approach, and any non-obvious decisions or trade-offs>

## Testing
<how you verified it — tests added, manual steps, before/after>

## Screenshots / output
<for UI or CLI changes>

## Notes for reviewers
<where to focus, known limitations, follow-ups deliberately left out>
```

Lead with *what* and *why* — a reviewer who understands the intent reviews the diff far
better. Don't make them reverse-engineer the goal from the code.

## Before you open it

- Self-review the diff first; you'll catch the obvious stuff and spare the reviewer.
- Ensure CI is green: build, tests, lint, format.
- Remove debug output, commented-out code, and unrelated changes.
- Confirm the PR does one thing. Scope creep is the most common review-killer.

## Reviewer experience

- Call out the riskiest part and where to focus attention.
- Explain non-obvious choices inline as PR comments so reviewers don't have to ask.
- Respond to feedback by fixing or discussing — don't relitigate settled decisions.
- Keep the branch up to date but don't force-push over in-progress review threads.

## Stacked pull requests

When a feature cannot stay reviewable as one PR, use the `stacked-changes` skill. Each PR
must target its immediate parent, represent one independently understandable step, and
include stack position/navigation. Review and land from the trunk-adjacent PR upward.

Do not calculate a stacked PR against trunk: that repeats every downstack change and
misstates ownership. Use `<parent>...HEAD`. After changing a lower branch, restack and
reverify every affected incremental diff. Rewriting a pushed stack requires explicit
ownership, recovery refs, and `--force-with-lease`.

## Anti-patterns

A 2,000-line PR titled "updates." Mixing a dependency bump with a feature. A description
that just says "see commits." No testing notes. These all push cost onto the reviewer
and slow everyone down.

Versions

The database has no other skills named pull-request-authoring.

Database snapshot: 13.11.2026 · package version 19286c15cfa5 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100pull-request-guide
    Use when authoring a pull or merge request - writing the description, sizing and splitting the change, documenting how it was tested, surfacing tradeoffs, and getting it review-ready before assigning reviewers. Triggers on opening a PR/MR, PR descriptions or templates, large or…
  • 90pr-authoring
    Shape pull requests a reviewer can actually hold in their head, through small size, a why-first description, and a self-review pass. Use when opening a pull request or preparing a change for review.
  • 100comprehensive-review-pr-enhance
    Create high-quality pull requests with comprehensive descriptions, automated review checks, and a size and structure that keep them easy to review. Use when preparing or improving a pull request.
  • 96small-prs-review
    Use when reviewing any complete diff immediately before opening a pull request.
  • 95create-pull-request
    Create and manage pull requests following this codebase's conventions. Use this skill when creating PRs, opening PRs for review, writing PR descriptions, or asked about PR workflows and best practices.
  • 100descriptions
    Draft or revise a pull-request description. Use when a user asks for a "PR description", "pull request summary", or "change description".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.