pr-description
GitHub用于生成和维护符合规范的Pull Request描述,包括自动计算变更统计、编写前后对比表格及处理截图附件。
Trigger Scenarios
Install
npx skills add OrchestratorInc/agent-orchestrator --skill pr-description -g -y
SKILL.md
Frontmatter
{
"name": "pr-description",
"description": "Write and maintain pull request descriptions in this repository, including the required change-count header, the before-and-after section, and screenshots or recordings for visible changes."
}
PR description
Use the section order in .github/pull_request_template.md: change-count header,
What, Why, Before / After, How, Testing, Checklist. Preserve the rest of an existing
PR description when updating it.
Change-count header
Begin every PR description with these three lines, using Markdown hard line breaks so each renders separately:
Code changes: +<added> -<deleted>
Tests: +<added> -<deleted>
Others: +<added> -<deleted>
Calculate the numbers from the net diff against the PR's actual base. For a local
branch, use git diff --numstat <base>...<head>. After pushing, prefer GitHub's
per-file additions and deletions. Recalculate after the final push rather than
summing commit churn or estimating counts.
Count every changed file exactly once:
- Code changes: handwritten implementation, including SQL, migrations, styles, and executable scripts.
- Tests: test code, fixtures, snapshots, and test-only helpers.
- Others: generated or vendored files, lockfiles, documentation, configuration, and assets. Generated output belongs here even when it contains source code.
Show +0 -0 for empty categories. Binary files have no line count; mention their
count separately when present. Add a brief qualifier when useful, such as
Others: +11 -0 (generated sqlc).
Before / After
Every PR has a ## Before / After section with a two-column table, one row per
behavior that changed:
| Before | After |
| --- | --- |
|  |  |
| `ao session ls` exits 1 when a project has no sessions | Prints `No sessions` and exits 0 |
- UI changes need a screenshot of each changed state, before and after. Use a short recording for flows, animations, focus or keyboard behavior, and timing.
- Non-visual changes compare observable behavior: command output, API responses, errors, logs, or measured numbers with their units.
- No user-visible change: write
No user-visible changeand one line saying why, such as an internal refactor or a test-only change.
Capture both sides from the real app with the same screen, window size, and data,
so they compare directly. Take the before capture from the PR's base branch. The
ao-desktop-dev skill launches the desktop app from a checkout.
Screenshots and GIFs go in the table. GitHub renders a video player only for a bare attachment URL on its own line, so put MP4 or MOV recordings on their own line below the table, with one line saying what they show.
Never commit screenshots or recordings to the repository. Attach them in the PR description, or in a PR comment when the description gets long. If you cannot upload, give the capture file paths to the person who will attach them. Remove secrets, tokens, and personal data from every capture.
Verify
After creating or updating the PR, read the published description and verify that:
- its opening lines match the current GitHub diff counts and required order;
- every image and recording in Before / After, or in a PR comment, loads.
Version History
- aa6e65d Current 2026-11-16 19:56


