Create Pull Request Skill
Opens a pull request for the current branch, or updates one that's already open. Unlike a read-only review skill, this one mutates: it can commit pending work, push the branch, and create or edit a PR on GitHub. It still never guesses on a genuine judgment call — base branch, an existing repo PR template, and an unavailable screenshot are all resolved by evidence or by asking, never assumed.
Mutation posture. Committing, pushing, and creating/editing the PR are the point of this skill, so they don't need a separate confirmation once the user has asked for a PR — but stop and confirm before pushing or opening anything if the request was ambiguous about whether to actually ship (e.g. "help me write a PR description" is not "open the PR").
Preflight — Do This First
git branch --show-current # never open a PR while standing on the base branch
git status # anything pending that needs a commit first?
gh pr view --json number,url,baseRefName 2>/dev/null # a PR may already exist for this branch — edit, don't duplicate
gh --version # gates screenshot attachment: needs >= 2.99.0, see references/screenshots.md
If gh pr view succeeds, this is an edit, not a create — see references/workflow.md → "When a PR already exists".
Base Branch
Never guess. In order: (1) an already-open PR's actual base; (2) .eagerworks/create-pr.json → baseBranch; (3) git config branch.<current>.gh-merge-base; (4) the branch's fork point via git reflog, only if it resolves to exactly one candidate; (5) ask, listing real candidates. The repo's default branch is not the base by default — plenty of repos merge into staging or develop, not main. Full ladder and anti-patterns: references/base-branch.md.
Description
Default structure, in order: Summary → Problem → Solution → Screenshots/Demo (required when the change is UI-visible) → Test plan → Checklist. If the repo has its own .github/pull_request_template.md, ask whether to use it as-is or replace it with this structure — never decide silently either way. Every paragraph is one line in the source (GitHub wraps it for display); never hand-wrap at 80/100 columns. The checklist has no fixed core — it's derived from tooling actually detected in the repo, or from .eagerworks/create-pr.json. Full detail: references/description.md.
Screenshots
Required when the diff touches a UI path and none is available yet. Look for one in this order: a path the user gave, an e2e artifact already on disk, a live capture (only with confirmation), then ask and leave an explicit placeholder. Attach with the GitHub CLI's --attach flag (gh ≥ 2.99.0) — reference the file in the body so the URL lands in place. Never fabricate an image URL and never use an undocumented upload endpoint. Full detail, version gate, and the exact commands: references/screenshots.md.
Reference Files (read these on demand)
| Task |
Read |
| End-to-end flow: preflight, commit, push, create, fix up assignee/labels, editing an existing PR |
references/workflow.md |
| Resolving which branch to open the PR against |
references/base-branch.md |
| Description structure, PR-template handling, the no-hand-wrap rule, deriving the checklist |
references/description.md |
Getting and attaching screenshots, the gh version gate, the placeholder rule |
references/screenshots.md |
The optional .eagerworks/create-pr.json config schema |
references/config.md |
Copyable templates live in assets/:
assets/create-pr.example.json — starter config, with a Rails and a Node exampleassets/pr-description.template.md — copyable description skeleton
Critical Gotchas
- This skill mutates, unlike a read-only review skill — but only in service of the PR the user actually asked for. If it's unclear whether they want it opened now or just drafted, ask before pushing or calling
gh pr create.
- Never open a PR while standing on the base branch. Check
git branch --show-current first.
- Never guess the base branch. If the open PR, the config,
gh-merge-base, and the fork point don't converge on one branch, ask — see references/base-branch.md.
- Never hand-wrap paragraphs. Always pass the body with
--body-file; never --body "...\n..." with escaped newlines.
- Never tick a checklist box for something that wasn't actually run or added. An inapplicable item keeps its own wording and appends
— N/A, <reason>; it's never silently deleted or replaced with a bare N/A — <reason>.
- Never invent an image or video URL, and never commit a screenshot into the repo just to reference it. No screenshot available yet means an explicit placeholder and a question to the user, not a guessed link or a binary added to git history — see
references/screenshots.md.
- A PR already open for this branch gets edited, never duplicated.
gh pr edit, not a second gh pr create.
- Never invent labels. Pick only from
gh label list; an empty label set beats a wrong one.
- Don't paste the whole diff into the description. Summarize what matters;
git diff --stat and git log --oneline are for your own context, not the PR body.
- PR title and description language is configured, not inferred. Write in
pr.language (default English) regardless of what language the conversation is in, unless the user explicitly names a language for this one PR — see references/config.md.
1---2name: create-pr3description: Opens (or updates) a pull request with a conventional title, an evidence-backed description, and a real verification checklist — resolving the base branch from evidence, attaching screenshots via the GitHub CLI when the change is visible in the UI, and asking rather than guessing at every genuine judgment call. Use when asked to "open a PR", "create a pull request", "push this and make a PR", "ship this branch", or to fix up an existing PR's title, description, or checklist.4---56# Create Pull Request Skill78Opens a pull request for the current branch, or updates one that's already open. Unlike a read-only review skill, this one **mutates**: it can commit pending work, push the branch, and create or edit a PR on GitHub. It still never guesses on a genuine judgment call — base branch, an existing repo PR template, and an unavailable screenshot are all resolved by evidence or by asking, never assumed.910**Mutation posture.** Committing, pushing, and creating/editing the PR are the point of this skill, so they don't need a separate confirmation once the user has asked for a PR — but stop and confirm before pushing or opening anything if the request was ambiguous about whether to actually ship (e.g. "help me write a PR description" is not "open the PR").1112## Preflight — Do This First1314```bash15git branch --show-current # never open a PR while standing on the base branch16git status # anything pending that needs a commit first?17gh pr view --json number,url,baseRefName 2>/dev/null # a PR may already exist for this branch — edit, don't duplicate18gh --version # gates screenshot attachment: needs >= 2.99.0, see references/screenshots.md19```2021If `gh pr view` succeeds, this is an **edit**, not a create — see `references/workflow.md` → "When a PR already exists".2223## Base Branch2425Never guess. In order: (1) an already-open PR's actual base; (2) `.eagerworks/create-pr.json` → `baseBranch`; (3) `git config branch.<current>.gh-merge-base`; (4) the branch's fork point via `git reflog`, only if it resolves to exactly one candidate; (5) ask, listing real candidates. **The repo's default branch is not the base by default** — plenty of repos merge into `staging` or `develop`, not `main`. Full ladder and anti-patterns: `references/base-branch.md`.2627## Description2829Default structure, in order: `Summary` → `Problem` → `Solution` → `Screenshots`/`Demo` (required when the change is UI-visible) → `Test plan` → `Checklist`. If the repo has its own `.github/pull_request_template.md`, **ask** whether to use it as-is or replace it with this structure — never decide silently either way. Every paragraph is one line in the source (GitHub wraps it for display); never hand-wrap at 80/100 columns. The checklist has no fixed core — it's derived from tooling actually detected in the repo, or from `.eagerworks/create-pr.json`. Full detail: `references/description.md`.3031## Screenshots3233Required when the diff touches a UI path and none is available yet. Look for one in this order: a path the user gave, an e2e artifact already on disk, a live capture (only with confirmation), then ask and leave an explicit placeholder. Attach with the GitHub CLI's `--attach` flag (`gh` ≥ 2.99.0) — reference the file in the body so the URL lands in place. Never fabricate an image URL and never use an undocumented upload endpoint. Full detail, version gate, and the exact commands: `references/screenshots.md`.3435## Reference Files (read these on demand)3637| Task | Read |38|---|---|39| End-to-end flow: preflight, commit, push, create, fix up assignee/labels, editing an existing PR | `references/workflow.md` |40| Resolving which branch to open the PR against | `references/base-branch.md` |41| Description structure, PR-template handling, the no-hand-wrap rule, deriving the checklist | `references/description.md` |42| Getting and attaching screenshots, the `gh` version gate, the placeholder rule | `references/screenshots.md` |43| The optional `.eagerworks/create-pr.json` config schema | `references/config.md` |4445Copyable templates live in `assets/`:46- `assets/create-pr.example.json` — starter config, with a Rails and a Node example47- `assets/pr-description.template.md` — copyable description skeleton4849## Critical Gotchas50511. **This skill mutates, unlike a read-only review skill** — but only in service of the PR the user actually asked for. If it's unclear whether they want it opened now or just drafted, ask before pushing or calling `gh pr create`.522. **Never open a PR while standing on the base branch.** Check `git branch --show-current` first.533. **Never guess the base branch.** If the open PR, the config, `gh-merge-base`, and the fork point don't converge on one branch, ask — see `references/base-branch.md`.544. **Never hand-wrap paragraphs.** Always pass the body with `--body-file`; never `--body "...\n..."` with escaped newlines.555. **Never tick a checklist box for something that wasn't actually run or added.** An inapplicable item keeps its own wording and appends `— N/A, <reason>`; it's never silently deleted or replaced with a bare `N/A — <reason>`.566. **Never invent an image or video URL, and never commit a screenshot into the repo just to reference it.** No screenshot available yet means an explicit placeholder and a question to the user, not a guessed link or a binary added to git history — see `references/screenshots.md`.577. **A PR already open for this branch gets edited, never duplicated.** `gh pr edit`, not a second `gh pr create`.588. **Never invent labels.** Pick only from `gh label list`; an empty label set beats a wrong one.599. **Don't paste the whole diff into the description.** Summarize what matters; `git diff --stat` and `git log --oneline` are for your own context, not the PR body.6010. **PR title and description language is configured, not inferred.** Write in `pr.language` (default English) regardless of what language the conversation is in, unless the user explicitly names a language for this one PR — see `references/config.md`.
eagerworks