pull-requests - SKILL.md Agent Skill

name: pull-requests description: "Guide for creating, updating, and following up on pull requests in the Coder repository. Use when asked to open a PR, update a PR, rewrite a PR description, or follow up on CI/check failures."

Pull Request Skill

When to Use This Skill

Use this skill when asked to:

Create a pull request for the current branch.
Update an existing PR branch or description.
Rewrite a PR body.
Follow up on CI or check failures for an existing PR.

References

Use the canonical docs for shared conventions and validation guidance:

PR title and description conventions: .claude/docs/PR_STYLE_GUIDE.md
Local validation commands and git hooks: AGENTS.md (Essential Commands and Git Hooks sections)

Body Formatting

GitHub renders the PR description as Markdown and soft-wraps paragraphs to the viewport. Do not hard-wrap prose at 72 or 80 columns. Insert manual line breaks only where Markdown needs them: between paragraphs, around headings, lists, tables, code blocks, and blockquotes.

The commit message body is not the PR body. Commit messages are typically hard-wrapped; PR bodies are not. When deriving the PR body from a commit message, unwrap each paragraph into a single line before passing it to gh pr create --body or --body-file.

Lifecycle Rules

Check for an existing PR before creating a new one:
```
gh pr list --head "$(git branch --show-current)" --author @me --json number --jq '.[0].number // empty'
```
If that returns a number, update that PR. If it returns empty output, create a new one.
Check you are not on main. If the current branch is main or master, create a feature branch before doing PR work.
Default to draft. Use gh pr create --draft unless the user explicitly asks for ready-for-review.
Keep description aligned with the full diff. Re-read the diff against the base branch before writing or updating the title and body. Describe the entire PR diff, not just the last commit.
Never auto-merge. Do not merge or mark ready for review unless the user explicitly asks.
Never push to main or master.

CI / Checks Follow-up

Always watch CI checks after pushing. Do not push and walk away.

After pushing:

Monitor CI with gh pr checks <PR_NUMBER> --watch.
Use gh pr view <PR_NUMBER> --json statusCheckRollup for programmatic check status.

If checks fail:

Find the failed run ID from the gh pr checks output.
Read the logs with gh run view <run-id> --log-failed.
Fix the problem locally.
Run make pre-commit.
Push the fix.

What Not to Do

Do not reference or call helper scripts that do not exist in this repository.
Do not auto-merge or mark ready for review without explicit user request.
Do not push to origin/main or origin/master.
Do not skip local validation before pushing.
Do not fabricate or embellish PR descriptions.