agentleFS
Sign inStart free
vimeovimeo/psalm/.agents/skills/pr-description/SKILL.md

pr-description

Skill5.9k starsChanged yesterdayMITView on GitHub

Use when writing the description of a vimeo/psalm pull request (gh pr create / gh pr edit), or when asked to reformat, tidy or shorten an existing PR description, including PRs opened by other people. Defines the house format (one-line bug + Before/After code blocks taken from PR test cases that assert the fix) and how to verify them.

  • Commits and pushes

We split this skill into the rules it gives an agent

8 rules. 0 are common, 3 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 85 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Keep closing keywords for issues the PR fixes (Fixes #1234) on their own last line, so GitHub links and closes them.

    line 46
  2. Distinctive:

    Leave out: background and motivation, design notes, "stacked on / combines / merged

    line 48
  3. Very specific:

    If no test case makes a short, clear example, add one to the PR first.

    line 61
  4. Very specific:

    Only when asked, and only for PRs in repos you may edit (vimeo/psalm and the psalm org: editing someone else's PR body needs maintainer …

    line 73
  5. Very specific:

    Read the current body, title and diff: gh pr view <n> --repo vimeo/psalm --json title,body,author,files and gh pr diff <n> --repo …

    line 76
  6. Distinctive:

    Keep everything the author wrote that matters to reviewers in the new format: the bug summary, issue links / closing keywords, and any …

    line 84
  7. Very specific:

    Verify the examples by running each one's test case on master and on the PR head (gh pr checkout <n> in a separate worktree, or git fetch …

    line 87
  8. Distinctive:

    Don't touch the code, labels or reviews of the PR as part of this.

    line 92

“Common” is measured: kept by at least 6 in 10 of the 85 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

PR descriptions

Format

As brief as possible: the reader only cares which bug is fixed, shown with code. The shape (the bug below is made up, only the layout matters):

Psalm reports a false `PossiblyNullReference` after `assert($x !== null)` inside a closure.

**Before**
```php
<?php
function f(?Foo $x): void {
    $g = function () use ($x): void {
        assert($x !== null);
        $x->bar(); // PossiblyNullReference
    };
}
```

**After**
```php
        $x->bar(); // no issue
```
  • One sentence naming the bug, as the user sees it (wrong issue, missed issue, crash, wrong inferred type), not the implementation.
  • A Before block: the code of a test case of the PR that asserts the fix (see below), plus what master reports, written as trailing // IssueName (or // IssueName: short message when the message matters) comments on the lines where the issue appears.
  • An After block with only the lines whose result changes, commented with the new result (// no issue, // TaintedHtml, // InvalidReturnType, or the new inferred type).
  • Several bugs in one PR: one short ### heading per bug, each with its own one-line summary and Before/After pair.
  • No PHP example possible (CI, memory, performance, crash in tooling): one plain line, e.g. "Self-analysis no longer hangs in taint resolution." Numbers only if they are the fix ("cuts self-analysis memory from 20 GB to 3 GB").
  • Keep closing keywords for issues the PR fixes (Fixes #1234) on their own last line, so GitHub links and closes them.
  • Leave out: background and motivation, design notes, "stacked on / combines / merged #…", measurements that aren't the point, review follow-ups, checklists, test lists, changelog prose, and any AI attribution.

Every example is a test case that asserts the fix

  • Each Before/After example must correspond to a test case of the PR, and that test case must assert the fix: it fails on master and passes on the branch, because it checks exactly the result the After block shows (see "Tests must assert the change" in CLAUDE.md for how tests silently fail to do that).
  • The example is that test's code. If the test is long, the description may show only the lines that matter, as long as the test asserts what they show. Never show a snippet no test covers.
  • If no test case makes a short, clear example, add one to the PR first. Specific, easy-to-follow examples beat abstract ones (Foo/bar is fine; T1/T2 chains are not).
  • Verify by running that single test case (--filter 'testValidCode@caseName', or tests/Taint --filter '@caseName'; see CLAUDE.md) on master (must fail) and on the branch (must pass). Copy the issue names in the Before comments from master's actual output. Never write invented or "illustrative" output.
  • Taint PRs: the test case should show source and sink in a few lines (echo $_GET['x']; → // TaintedHtml).

Reformatting an existing description (including other people's PRs)

Only when asked, and only for PRs in repos you may edit (vimeo/psalm and the psalm org: editing someone else's PR body needs maintainer rights).

  1. Read the current body, title and diff: gh pr view <n> --repo vimeo/psalm --json title,body,author,files and gh pr diff <n> --repo vimeo/psalm.
  2. Work out the bug(s) actually fixed from the diff and the tests it adds, not only from the prose. Pick the examples from the PR's test cases, and check that those tests assert the fix. If none does, or none makes a usable example, tell the user and suggest a test case to add; don't push tests to someone else's PR unless asked.
  3. Keep everything the author wrote that matters to reviewers in the new format: the bug summary, issue links / closing keywords, and any explicit note about a BC break or a behaviour change users must know about (one line at the end). Drop the rest.
  4. Verify the examples by running each one's test case on master and on the PR head (gh pr checkout <n> in a separate worktree, or git fetch origin pull/<n>/head).
  5. Show the new body to the user before replacing someone else's. Then: gh pr edit <n> --repo vimeo/psalm --body-file <file>. Don't change the title unless asked; if it's misleading, suggest a new one.
  6. Don't touch the code, labels or reviews of the PR as part of this.

Download now (ZIP)

  • Other versions90 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 90

    1. jdx/mise★ 36ksame name
    2. zulip/zulip★ 26ksame name
    3. Nagi-ovo/gemini-voyager★ 21ksame name
    4. pipecat-ai/pipecat★ 17ksame name
    5. AgentWrapper/agent-orchestrator★ 14ksame name
    6. ComposioHQ/agent-orchestrator★ 14ksame name
    7. OrchestratorInc/agent-orchestrator★ 14ksame name
    8. Untrivial-ai/agent-orchestrator★ 14ksame name
    9. sanity-io/sanity★ 6.4ksame name
    10. pytorch/torchtitan★ 5.9ksame name

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

  • Used alongsideProjects 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 8 projects that use this

    • francogalfreSkill

      dependency-audit

      Audits package.json dependencies for outdated packages, security vulnerabilities, unnecessary deps, and version issues. Use when the user says "audit my dependencies", "check my packages", "what deps should I update", "clean up package.json", "are there security issues in my deps", or pastes a package.json.

      Also in 3 projects that use this

    • PydanticSkill

      i-have-adhd

      Shape every response for an ADHD reader who reviews the work but does not do the coding — the agent does. Use whenever responding to ANY message — coding, debugging, planning, casual. Lead with the result or the decision. Surface anything needing the user's input as a structured question, never buried in prose they'll skim past. No preamble, no recap, no closers. State errors matter-of-factly. Make finished work visible. Trigger even on casual messages and even when brevity wasn't requested.

      Also in 3 projects that use this

    • HashiCorpSkill

      changelog

      Add a `.changelog/<PR_NUMBER>.txt` entry for a GitHub Pull Request, commit, and push.

      Also in 5 projects that use this

  • In this repository8 other files it gives its agents.

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.

Check your setup, free