agentleFS
coreplanelabscoreplanelabs/switchboard/skills/pr-description/SKILL.md

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

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-inSkill

    ao-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

  • jMertaSkill

    bug-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

  • GitHubSkill

    commit-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

  • AnthropicSkill

    incident-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

  • LangChainSkill

    api-docs

    OpenAPI documentation and REST API design patterns

    Also in 3 projects that use this

  • srclightSkill

    refactor-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

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
  1. Very specific:

    Follow the shared writing rules supplied by use_skill.

    line 13
  2. Distinctive:

    Never embed. A bare permalink on its own line makes GitHub inline the code as a block.

    line 46

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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)

  1. 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.
  2. 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.
  3. 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 ⚠, anchor is the { path, from, to } line range at your pushed head. Rendered as N. [label](permalink) text ⚠ risk, a link, never embedded code.
  4. feedbackWanted (200): the one or two things you want the reviewer's judgement on. An explicit ask gets engagement; "please review" gets none.
  5. 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.
  6. 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, path repo-relative, to ≥ from, at most about 25 lines: the click lands on highlighted lines, so point at the lines that matter. Switchboard renders the permalink https://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 HEAD after pushing): locate the lines with grep -n <landmark> <path>, then verify with git 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. Check git 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.