pr-description
Skill5 starsChanged 2 months agoApache-2.0View on GitHub
Write a concise PR description in Simplified Technical English. Explain the product, user task and changed result for a reader with no system context. Load before submitting any PR description.
100 other projects use a version of this.
Adopted by
Most recently taken up by
- oligot/claude-skillstheir own version, first seen Nov 16, 2026
- imtiazrayhan/agentscamp-librarytheir own version, first seen Nov 16, 2026
- antick/skillstheir own version, first seen Nov 16, 2026
- github/plugin-marketplace-startertheir own version, first seen Nov 15, 2026
- Kuan-AI-com/agent-skillstheir own version, first seen Nov 15, 2026
- pulore/claude-code-codex-configtheir own version, first seen Nov 15, 2026
Used with
Projects with it also use ao-desktop-dev, bug-triage and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
agentlab-inSkillao-desktop-dev
Launch, restart, or troubleshoot the real AO Electron desktop app from this repository; run a checkout against isolated or real local AO data; combine PR branches for local UI review; and diagnose stale Electron processes, port conflicts, or preload bridge mismatches. Use whenever asked to run, open, show, or visually verify AO frontend changes in the actual desktop app rather than ao preview, dev:web, or mock data.
Also in 4 projects that use this
jMertaSkillbug-triage
Use when the user reports a bug, regression, runtime error, failing build, or broken test and wants reproduction, diagnosis, root-cause analysis, or an authorized fix. Isolates the shared cause and verifies the smallest relevant change.
Also in 4 projects that use this
GitHubSkillcommit-message
Generate conventional commit messages - use when creating commits, writing commit messages, or asking for git commit help
Also in 12 projects that use this
AnthropicSkillincident-postmortem
Write the postmortem for an incident, in its incident channel, once it is mitigated or resolved. Use on "write up this incident", "postmortem", "incident summary", "what happened here for people who weren't around", "draft the retro", or when the oncall memory says incidents of this severity get one. Reads the incident channel (and the alert thread it came from), the investigation findings and the data behind them, and writes a one-screen, zero-context write-up: what happened, impact with numbers, detection, timeline with durations, why it happened, what fixed it, follow-ups with proposed owners, and one before/during/after chart. Posted and pinned in the incident channel as its final pinned post, with edit requests updating that one pinned post in place — unless the person or the team's conventions say write-ups live elsewhere, in which case it is written there and only a link is posted, nothing pinned. A person edits and publishes it; never assigns blame.
Also in 3 projects that use this
LangChainSkillapi-docs
OpenAPI documentation and REST API design patterns
Also in 3 projects that use this
srclightSkillrefactor-safely
This skill should be used when the user asks to "refactor", "rename", "move", "change a function signature", "extract a method", "delete unused code", "clean up", or any modification that could break callers or dependents. Provides a pre-change safety checklist using srclight's graph tools to assess blast radius before touching code.
Also in 3 projects that use this
Other versions100 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 100
- jdx/mise★ 36ksame name
- zulip/zulip★ 26ksame name
- Nagi-ovo/gemini-voyager★ 21ksame name
- pipecat-ai/pipecat★ 17ksame name
- AgentWrapper/agent-orchestrator★ 15ksame name
- ComposioHQ/agent-orchestrator★ 15ksame name
- OrchestratorInc/agent-orchestrator★ 15ksame name
- Untrivial-ai/agent-orchestrator★ 15ksame name
- sanity-io/sanity★ 6.4ksame name
- vimeo/psalm★ 5.9ksame name
90 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- address-review-findingsSkill
- code-review-and-qualitySkill
- doubt-driven-developmentSkill
- incremental-implementationSkill
- performance-optimizationSkill
- re-review-deltaSkill
- security-and-hardeningSkill
- spec-driven-developmentSkill
- test-driven-developmentSkill
The file
We split this skill into the rules it gives an agent
2 rules. 0 are common, 1 is distinctive, and 1 is very specific to this project.
0
Common
Most of the 95 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 13
Follow the shared writing rules supplied by use_skill.
- Distinctive: line 46
Never embed. A bare permalink on its own line makes GitHub inline the code as a block.
“Common” is measured: kept by at least 6 in 10 of the 95 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
The PR description
The description is the PrDescription object you submit through submit_pr_description; Switchboard renders the GitHub body from it at your pushed head. The body has two parts. Above the fold, the map: what a person reads in a minute and clicks from. Below the fold, collapsed: what agents and the record need. You write it right after implementing, when you have more context about the change than anyone will ever have again.
Language and product context
Follow the shared writing rules supplied by use_skill.
Assume the reader has no context about the product, system, repository or prior discussion. Start with what the product lets a person do. Name the affected user task and explain the result before and after this change. Use the product in the target repository, including when Switchboard writes a PR for another product. Include only the product context needed to understand this change.
Keep that context through the whole map. Explain each internal component by its role in the user task before naming its mechanism. Define an unfamiliar term at first use or replace it with concrete words. An issue link, file name or component name cannot supply the explanation.
For example: "Switchboard lets people ask an agent to review a pull request. This change explains each review finding in short, direct sentences so the author can understand the failure and fix it." This gives the product, task and result; "Add prose policy to skill hydration" does not.
Before submitting, read only the map as a new reader. It must answer: What does the product do here? Who uses this part? What happens today? What changes, and why does it help? Shorten repeated detail to meet the caps; preserve the context needed to answer those questions.
The map is the same size for a 3-file and an 80-file PR. The schema enforces that: every field has a cap and the tool refuses an object over it, naming every field over its cap with the count. Caps count visible characters; a markdown link's target is not counted, so link freely. When a refusal names a count, remove at least that many visible characters from that field: a link's target does not count, so shortening a URL removes nothing; the refusal quotes a prefix that fits, cut at a word boundary, which you may use as is.
The title
title (72): the changelog line and the squash subject, type(scope): what a reader can now do or expect, the whole line counted. One change, one clause, present tense; the type and the scope spend the same budget as the description, so the description is short and the body carries the rest. Judge it with npm run check:pr-title -- "<title>" before submitting: the same gate refuses the PR in CI, and the schema refuses a longer title naming the count.
The map (above the fold, in this order)
tldr(300): two sentences for a reader with zero system context. Name the product and affected user task, then state what changes and why it matters.why(400): the current user problem and its effect, with the triggering issue, the record and the stack position hyperlinked where applicable. Explain the problem in the body; links provide supporting detail.pointers(1 to 7): Where to look, in reading order. Each is{ label, text, risk?, anchor }:label(60) names the thing,text(160) is one sentence on what it does or why it is shaped so,risk(100) is set only where a mistake would matter and renders as⚠,anchoris the{ path, from, to }line range at your pushed head. Rendered asN. [label](permalink) text ⚠ risk, a link, never embedded code.feedbackWanted(200): the one or two things you want the reviewer's judgement on. An explicit ask gets engagement; "please review" gets none.risk(300): what user task can fail if this is wrong, who is affected, how to roll back. When the change exceeds 400 changed lines, say so here and name the split you considered.verified(200): one line for a person: which suites ran and passed, what is still human-gated.
Choosing the pointers
Point at the files a reviewer would open first: the entry point, then the core logic, then the test that pins the invariant, then the doc that changed. One pointer per idea, never per file; a helper and its caller that share one idea share one pointer. When the change has more than seven ideas, keep the seven whose mistake would cost most and let the Files tab carry the rest; the reviewer has the diff. Never stuff three files into one sentence to beat the cap.
Anchors
- An anchor is a line range
{ path, from, to }at your pushed head,pathrepo-relative,to ≥ from, at most about 25 lines: the click lands on highlighted lines, so point at the lines that matter. Switchboard renders the permalinkhttps://github.com/<owner>/<repo>/blob/<head sha>/<path>#L<from>-L<to>with the FULL 40-char sha it observes from your pushed branch; you never write a URL or a sha. - Never write an anchor from memory. Line numbers recalled from a file are usually wrong, and a wrong range sends the reader to the wrong code under a correct sentence, which is worse than no pointer. Derive every anchor mechanically against the commit you pushed (
git rev-parse HEADafter pushing): locate the lines withgrep -n <landmark> <path>, then verify withgit show <sha>:<path> | sed -n '<from>,<to>p'. The printed lines must be the code the sentence describes. If they are not, fix the range, not the prose. Checkgit cat-file -e <sha>:<path>when a rename is possible. - Never embed. A bare permalink on its own line makes GitHub inline the code as a block; the renderer writes every pointer as a link so the body stays a map. Do not paste code or permalinks into any prose field.
Below the fold (collapsed by the renderer)
decisions(0 to 10, rationale 400 each): the non-obvious choices, each{ title, rationale }: the alternative rejected and the fact that decided it. A two-line fix has none.validation.criteria(1 to 30, criterion 200, proof 300): what you ran and the real result, one row per criterion, the proof a test id or a command with its outcome. Never fabricate; a criterion you could not prove says so and is marked human-gated.agentNotes(2,000, optional): what a reviewing agent needs that a person does not: the rebase you did, the generated files to skip, the command that reproduces the bug.
Resubmit on every repush that moves the code
An anchor is a line range at the pushed head. On every push that changes the head (amend, rebase, force-push, review fix-ups), any pointer whose lines moved points at the wrong code; stale anchors are a lie about the PR. Re-verify the ranges and resubmit the description; the last valid submission wins and Switchboard re-renders the body at the new head. Never edit the PR body directly. A push that moves no ranges needs no new anchors: the same object renders correctly at the new head.
What not to write
No section that restates the diff: no file catalog, no per-hunk walkthrough, no "Changes" list. No embedded code. No hedges in verified: a suite either ran and passed or it did not. No jargon a stranger to the package cannot follow in the map; the map is for a reader who has never opened the package.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

