# Create Pr > Create a GitHub pull request with a structured description linked to its issue, with acceptance criteria coverage and reviewer assignment. Embeds visual proof that was captured beforehand by /validate-implementation (single asset, or a before/after pair for bug fixes) by reading the proof manifest; create-pr is a consumer and does not capture recordings itself. If no proof was captured, it omits… - **Type:** Skill - **Install:** `agentstack add skill-tomzx-agents-create-pr` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [tomzx](https://agentstack.voostack.com/s/tomzx) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [tomzx](https://github.com/tomzx) - **Source:** https://github.com/tomzx/agents/tree/main/skills/create-pr ## Install ```sh agentstack add skill-tomzx-agents-create-pr ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Create Pull Request Opens a GitHub pull request for the current branch with a structured description that maps implementation changes to acceptance criteria, links the originating issue, and requests reviewers. It is a pure consumer of visual proof: it reads the manifest written by [`/validate-implementation`](../validate-implementation/SKILL.md) and embeds any captured asset inline so reviewers see proof the moment the PR opens. It does not capture recordings itself; recording happens at human-review time, before the PR exists. ## Prerequisites - Apply the shared SDLC conventions in `skills/sdlc/references/shared.md`. - If no argument is provided, use `$REPO` and link `$ISSUE_NUMBER`. - `gh` CLI authenticated with write access to the target repository - Current branch has commits not on the base branch - A related GitHub issue number (strongly recommended; omit only for housekeeping PRs) - Tests passing locally before the PR is opened - For visual proof (captured beforehand): run [`/validate-implementation`](../validate-implementation/SKILL.md) on the branch first. It records a CLI demo (via [`/record-asciinema`](../record-asciinema/SKILL.md)) or a web screenshot (via [`/record-playwright`](../record-playwright/SKILL.md)) and writes `$PROOF_DIR/captured-proof.json`. If that manifest is absent, `create-pr` omits the Visual proof section and suggests running `/validate-implementation` first (it never captures on its own). > **Note:** This skill uses `gh` (GitHub CLI) directly. For a Graphite-based workflow that diffs against the Graphite parent branch, use `/create-pr-description` instead. ### Skill attribution (GitHub) Before creating the PR with `gh pr create`, read [`github-post-attribution/SKILL.md`](../github-post-attribution/SKILL.md) and append the **Created with** footer for `SKILL_DIR` = `create-pr` to the PR body. ## Workflow ``` Verify branch has commits + tests pass | v Compute diff (base..HEAD) | v Issue provided? ($1 $2) / \ Yes No | | v v Fetch issue Skip AC + map ACs coverage | | +--------+--------+ | v Pre-captured proof? ($PROOF_DIR/captured-proof.json) / \ Yes No | | v v Read manifest Before-only state? (proof-manifest.txt (mode + assets) exists, captured-proof.json absent) | / \ | Yes No | | | | v v | Embed before Omit Visual proof; | alone, note suggest /validate- | after pending implementation first | | | +--------+-------+------------+ | v Embed proof in description (single, or before/after pair) | v Upload resolved assets to branch | v gh pr create (draft if incomplete) | v Assign reviewers (if known) ``` ## Steps 1. Confirm the branch has commits ahead of the base: ``` git log origin/$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null | sed 's|origin/||')..HEAD --oneline ``` If no commits, stop and inform the user. 2. Confirm tests pass before opening: Run the project's test command. If tests fail, stop and list the failures. 3. Compute the diff against the base branch: ``` git diff $(git merge-base HEAD origin/main)..HEAD ``` 4. If `$1` (repository) and `$2` (issue number) are provided, fetch the issue: ``` ghx issue view $2 --repo $1 ``` Map each acceptance criterion to the changes in the diff. Note any ACs not yet addressed (to call out in the description). 5. Resolve the visual proof to embed. `create-pr` consumes proof captured beforehand by [`/validate-implementation`](../validate-implementation/SKILL.md); it does not capture recordings itself. Resolve the proof directory and detect what is available: ```bash REPO="${1:-$REPO}" ISSUE_NUMBER="${2:-$ISSUE_NUMBER}" PROOF_DIR="/tmp/$REPO/${ISSUE_NUMBER:-housekeeping}" # /tmp/// ``` **Authoritative source — `captured-proof.json`** (written by `/validate-implementation`): ```bash test -f "$PROOF_DIR/captured-proof.json" ``` If present, read it. It is authoritative for which assets to embed: ```json { "captured_at": "", "surface": "cli" | "web" | "none", "mode": "single" | "bugfix-pair" | "bugfix-before-only", "assets": ["pr-demo.gif"] | ["before-bug.gif", "after-fix.gif"] } ``` Embed exactly the files listed in `assets` (resolved against `$PROOF_DIR`), in listed order. Render Before / After layout when `mode` is `bugfix-pair` (or `bugfix-before-only`, embedding just the before with a note that after is pending via `/validate-implementation`). Render the single-asset block when `mode` is `single`. **Partial state — before only, no manifest yet:** If `captured-proof.json` is absent but `$PROOF_DIR/proof-manifest.txt` exists (reproduce-issue captured a before, but `/validate-implementation` has not yet produced the after), embed the existing `$PROOF_DIR/before-bug.*` alone with a note that the after recording is pending, and suggest running `/validate-implementation` to complete the pair. **No proof captured:** If neither manifest exists, omit the Visual proof section entirely and note in the PR description (or in console output before creation) that `/validate-implementation` can capture proof. Do not attempt to capture here. This is a representative proof, not a claim-by-claim demonstration (that is `/validate-pr`'s job). 6. Upload the resolved asset(s) (from step 5) to the branch and note their raw URLs for the description. Upload only the assets chosen in step 5, not everything in `$PROOF_DIR`: ``` for asset in "$PROOF_DIR"/; do [ -f "$asset" ] || continue gh api repos/$1/contents/.create-pr-proof/$(basename "$asset") \ --method PUT \ -f message="Add visual proof" \ -f content="$(base64 -w 0 "$asset")" \ -f branch="$(git rev-parse --abbrev-ref HEAD)" done ``` When `captured-proof.json` is the source, iterate its `assets` list rather than a glob, so unrelated files in `$PROOF_DIR` are not uploaded. Omit `--repo` if the repository can be inferred from the current working directory. For each uploaded asset, derive its raw URL as `https://raw.githubusercontent.com/$1//.create-pr-proof/`. 7. Draft the PR description following the output format below, embedding the proof if one was captured. Do not line wrap the description; each paragraph/bullet should be a single long line. 8. Create the PR. Use `--draft` if any acceptance criteria are unmet: ``` gh pr create --repo $1 --title "" --body "$(cat EOF )" [--draft] ``` Omit `--repo` if the repository can be inferred from the current working directory. 9. If reviewer GitHub handles are known from context, assign them: ``` gh pr edit --add-reviewer ``` ## PR Description Format ```markdown # What # Why # How to test 1. 2. # Visual proof *Captured beforehand by `/validate-implementation`. Run `/validate-pr` for claim-by-claim validation. Omit this section entirely if no proof was captured.* For a bug fix with a paired before/after recording, use the Before / After layout instead of the single-asset block above: ```markdown # Visual proof **Before (bug reproduces):** **After (fixed):** *Before captured by `/reproduce-issue`; after captured by `/validate-implementation`. Run `/validate-pr` for claim-by-claim validation.* ``` If only the before asset exists (after not yet captured), keep the Before block and note that the after will be added once `/validate-implementation` is run. Omit the section entirely if no proof was captured. # Acceptance criteria coverage - [x] - [x] - [ ] # References - Closes # --- Created with [create-pr]({SKILL_FILE_URL}) (`SKILL_SHORT_SHA`) ``` Resolve `SKILL_FILE_URL` and `SKILL_SHORT_SHA` per [`github-post-attribution/SKILL.md`](../github-post-attribution/SKILL.md). Use `Closes #N` to auto-close the issue on merge. Use `Related to #N` if the PR only partially addresses the issue. ## Example Usage **Scenario 1: Feature PR linked to an issue** ``` /create-pr owner/myrepo 42 ``` Diffs branch, fetches issue #42, maps all 4 ACs to changes, creates PR with "Closes #42" and requests reviewers. **Scenario 2: PR covering only part of an issue** ``` /create-pr owner/myrepo 88 ``` Issue has 5 ACs; this branch addresses 3. Creates a ready-for-review PR, marks the 2 unmet ACs as unchecked with a note, uses "Related to #88". **Scenario 3: Housekeeping PR without an issue** ``` /create-pr ``` No issue provided. Creates PR with What/Why/How-to-test sections; omits AC coverage and References sections. **Scenario 4: Incomplete implementation** ``` /create-pr owner/myrepo 100 ``` One AC not yet met. Opens as a draft PR so it is not accidentally merged. **Scenario 5: Web UI PR with embedded visual proof** ``` /create-pr owner/myrepo 130 ``` `/validate-implementation` was run first and wrote `/tmp///130/captured-proof.json` listing `pr-demo-1280x720.png`. `create-pr` reads the manifest, uploads that PNG to `.create-pr-proof/`, and embeds it in a "Visual proof" section so reviewers see the change immediately. It does not start the dev server or capture anything itself. **Scenario 6: PR where no proof was captured** ``` /create-pr owner/myrepo 130 ``` No `$PROOF_DIR/captured-proof.json` exists (the user skipped `/validate-implementation`). `create-pr` omits the "Visual proof" section and notes that `/validate-implementation` can capture proof first. The PR opens with the standard sections. **Scenario 7: Bug-fix PR with paired before/after recordings** ``` /create-pr owner/myrepo 42 ``` Branch is `fix/42-null-pointer-login`. `/validate-implementation` was run after the fix: it found `/tmp///42/proof-manifest.txt` (written earlier by `/reproduce-issue`, `surface: cli`), replayed that command on the fixed code into `after-fix.gif`, and wrote `captured-proof.json` with `mode: bugfix-pair` listing both `before-bug.gif` and `after-fix.gif`. `create-pr` reads the manifest, uploads both to `.create-pr-proof/`, and renders a Before / After section in the PR body so reviewers see the bug and the fix side by side. ## Completion Checklist Before requesting review, confirm: - [ ] Issue linked (Closes vs Related to #N) with acceptance criteria mapped to coverage checkboxes - [ ] Visual proof embedded if `/validate-implementation` captured it, the section omitted entirely if not (no placeholder left) Self-check the PR against the [`review-pr` checklist](../review-pr/SKILL.md) and fix what you can, so review finds less to flag. ## Next Step After the PR is open, use `/handle-pr-ci` if CI is failing, `/handle-pr-feedback` to address reviewer comments, and `/merge-pr` once CI is green and the PR is approved. Run `/validate-pr` for claim-by-claim runtime validation with per-claim recordings (the proof embedded here is a single representative asset captured by `/validate-implementation`). Close the loop with `/create-learnings` after the feature is merged. ## Useful Commands Reference | Command | Description | |---|---| | `git log origin/..HEAD --oneline` | List commits ahead of the base branch | | `git diff $(git merge-base HEAD origin/main)..HEAD` | Diff against the merge base | | `ghx issue view --repo ` | Fetch issue details (cached) | | `gh pr create --repo --title "..." --body "..." [--draft]` | Open the pull request | | `gh pr edit --add-reviewer ` | Assign a reviewer after creation | | `gh api repos//contents/ --method PUT -f content="$(base64 -w 0 )"` | Upload a visual-proof asset to the branch | ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [tomzx](https://github.com/tomzx) - **Source:** [tomzx/agents](https://github.com/tomzx/agents) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-tomzx-agents-create-pr - Seller: https://agentstack.voostack.com/s/tomzx - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.