From github-author
Encodes PR authoring conventions including imperative titles with repository-capability verbs, motivation-focused descriptions, hidden context surfacing, and prose flow guidelines. Must be loaded before composing any pull request title or description, whether drafting interactively or creating programmatically with gh pr create.
npx claudepluginhub notorious-ai/claude-plugins --plugin github-authorThis skill uses the workspace's default tool permissions.
Effective pull requests communicate the **why** behind changes, not the **what**. Code diffs already show what changed; the PR title and description convey motivation, impact, and context that accelerates review.
Writes articles, guides, blog posts, tutorials, and newsletters in a voice from examples or brand guidance. For polished long-form content with structure, pacing, and credibility.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Executes repo commands, inspects git state, debugs CI failures, and pushes narrow fixes with exact proof of execution and verification. Use for command runs, repo checks, or evidence-based changes.
Effective pull requests communicate the why behind changes, not the what. Code diffs already show what changed; the PR title and description convey motivation, impact, and context that accelerates review.
The PR title describes how the repository changes when the PR merges. The verb targets the repository capability, not the developer action.
Complete this sentence with your title: "After this PR merges, the repository will _____."
The verb must make grammatical sense in this frame. Developer-action verbs fail the test:
| Verb | "The repository will _____" | Works? |
|---|---|---|
| Parse MAC addresses | "The repository will parse MAC addresses" | Yes |
| Add rate limiting | "The repository will add rate limiting" | No |
| Handle nil emails | "The repository will handle nil emails" | Yes |
| Implement caching | "The repository will implement caching" | No |
Developer-action verbs (add, implement, create, write, update, change) describe what the developer did. Repository-capability verbs (parse, handle, support, expose, enable, optimize, simplify, prevent, serialize, validate, extract) describe what the code does.
| Intent | Verbs |
|---|---|
| New capability | handle, parse, transform, validate, serialize, cache, pool |
| Improvement | optimize, simplify, consolidate, enhance |
| Fix | fix, correct, respect, prevent |
| Structural | extract, expose, define, introduce |
| Removal | remove, drop, deprecate |
| Configuration | configure, enable, disable |
| Documentation | explain, clarify, document |
For comprehensive verb guidance and rationale, see examples/bad-pr-examples.md.
PR titles follow imperative mood, beginning with a verb:
Format: <Verb> <what the repository now does>
Examples:
Parse MAC addresses without separatorsLimit authentication attempts to prevent brute-force attacksSerialize connection pool cleanup to prevent leaksExtract authentication into dedicated serviceBefore drafting a PR, gather context from multiple sources:
Analyze the working tree to understand the change scope:
Search for related context in the repository:
Use gh issue list and gh pr list to discover related work. Reference relevant issues in the PR description to connect the contribution to ongoing efforts.
Draw context from the discussion that led to the changes:
When context is missing, ask proactively. The motivation behind a change is essential for a good PR.
PRs live in the solution-space: the author has made decisions and the changeset reflects those decisions. The description must surface the context that led to this solution.
The diff shows what changed. The description must explain what the diff cannot convey:
Alternatives considered may be worth brief mention, but focus on constraints and exclusions over exhaustive comparison of rejected options.
Use intelligence to detect when essential context is missing. When gaps exist, ask targeted questions before drafting:
If the user cannot provide the information after being asked, insert actionable placeholders that specify exactly what information is missing and how to obtain it:
[FILL: Ask the original author why X was chosen over Y][FILL: Check git blame for commit message explaining this constraint][FILL: Review linked issue for context on why this approach]Placeholders must be specific enough that someone can act on them immediately.
When rationale is uncovered, check the changeset for appropriate places to embed it permanently. Respect existing project conventions - do not introduce new documentation patterns.
Preferred locations (in order of preference):
Do not:
If no trivial code location exists, include the rationale in the PR description. The PR is the fallback, not the first choice - but it's better there than nowhere.
Before drafting, check for repository-specific templates that encode team conventions.
Search these paths (first match wins):
.github/pull_request_template.md.github/PULL_REQUEST_TEMPLATE.mddocs/pull_request_template.mdpull_request_template.md (root).github/PULL_REQUEST_TEMPLATE/ (multiple templates)When a template exists, evaluate fit:
Templates are guides, not rigid forms.
PRs are solution-space documents. Issues define what needs solving (problem-space); PRs explain why this particular solution was chosen and what outcome it achieves.
The description explains why this solution exists and what outcome it delivers. The expected outcome must be verifiable: reviewers should be able to confirm the changeset achieves the stated intent.
The first paragraph immediately follows the title without a header. This opening carries the weight of explaining the change purpose.
When an issue is linked: The description can be brief since the issue provides problem-space context. Focus on the solution rationale: why this approach, what trade-offs were accepted.
When no issue exists: The description must compensate by providing both problem-space context (what prompted the change, who is affected) and solution-space rationale (why this approach over alternatives).
Keep PRs focused on a single logical change.
Signs of good scope:
Signs of scope creep:
When scope grows, split into stacked PRs or separate unrelated changes.
Complex changes benefit from proof that they work as expected:
Link proofs using trailer format: Proof: org/repo#123 (comment)
When creating a PR:
For detailed guidance, consult:
| File | Contains |
|---|---|
references/description-structure.md | Description format, prose flow, issue linking, post-merge patterns |
examples/good-pr-examples.md | Effective PR examples with probe tags showing context discovery |
examples/bad-pr-examples.md | Anti-patterns with detailed rationale for why they fail |
About probe tags: Example files use <probe> tags to demonstrate targeted questions that surface essential context. Each probe shows what to ask ("What constraint prevented the simpler solution?", "What's the proof?") and the information it reveals. Use this pattern when gathering context before drafting.
| Avoid | Why | Use Instead |
|---|---|---|
| add | Describes action of adding | handle, define, introduce |
| implement | Narrates development | handle, support, enable |
| update | Vague about what changed | optimize, fix, refactor (be specific) |
| change | Maximally vague | optimize, correct, simplify (be specific) |
| create | Focuses on creation not function | define, establish, introduce |
These describe what the developer did, not what the repository now does. See examples/bad-pr-examples.md for comprehensive analysis.
GitHub's markdown renderer treats hard newlines within a paragraph as literal line breaks. When composing --body content for gh pr create, write each paragraph as a single continuous line with no mid-sentence wraps. Newlines should only appear:
This differs from git commit -m, where hard wraps are conventional because terminals render them directly.
Before presenting the PR:
Process:
Title:
Description:
org/repo#123)