Creates GitHub pull requests with pre-flight validation, conventional title formatting, and structured summary generation. Runs parallel checks (tests, lint, type-check, security) before opening. Supports feature, bugfix, refactor, and hotfix PR types with milestone assignment via gh CLI. Invoke only if the operator named it; an everyday `gh pr create` stays plain tooling. Use when opening PRs or submitting code for review.
Claude Code 2.1.220+. Requires memory MCP server, gh CLI.
description
Creates GitHub pull requests with pre-flight validation, conventional title formatting, and structured summary generation. Runs parallel checks (tests, lint, type-check, security) before opening. Supports feature, bugfix, refactor, and hotfix PR types with milestone assignment via gh CLI. Invoke only if the operator named it; an everyday `gh pr create` stays plain tooling. Use when opening PRs or submitting code for review.
{"keywords":["create pr","create a pr","crate a","pull request","open pr","open a pr","make a pr","submit pr","push and pr","push this up"],"examples":["create a pull request for this feature","open a PR against the default branch","this is ready for review, make a PR"],"anti-triggers":["commit","review pr","merge","rebase","push"]}
Create Pull Request
Comprehensive PR creation with validation. All output goes directly to GitHub PR.
Quick Start
/ork:create-pr
/ork:create-pr "Add user authentication"
CC ≥ 2.1.119 multi-host note (M122): PR creation works against GitHub, GitLab, Bitbucket, and GitHub Enterprise. Detect the target host from the configured remote (git remote -v) and branch on the host family for the right CLI:
Host family
CLI
github / github-enterprise
gh pr create (with GH_HOST=<host> for GHE)
gitlab / gitlab-self
glab mr create
bitbucket
bb pr create
Custom enterprise URLs: prUrlTemplate setting (see src/skills/configure/ and src/skills/chain-patterns/references/pr-from-platform.md).
Argument Resolution
TITLE = "$ARGUMENTS"# Optional PR title, e.g., "Add user authentication"# If provided, use as PR title. If empty, generate from branch/commits.# $ARGUMENTS[0] is the first token (CC 2.1.59 indexed access)
Base Branch Resolution
Derive the base branch from the remote. Never hardcode dev or main; repos differ.
BASE=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')
BASE=${BASE:-main}# ref missing (fresh/shallow clone)? run: git remote set-head origin -a
Feature: Full Phase 2 with 3 parallel agents + local tests
Bug fix: Phase 2 with test-generator only + local tests
Refactor: Phase 2 with code-quality-reviewer only + local tests
Quick: Skip Phase 2, jump to Phase 3
Optional pre-flight: claude ultrareview (CC 2.1.120+, #1542)
If claude ultrareview --help succeeds, optionally run it before opening the PR and surface findings in the PR body's ## Pre-flight section. The CLI subcommand returns structured --json output that can be filtered to high/medium severity for the body and full results posted as a follow-up comment.
if claude ultrareview --help >/dev/null 2>&1; then
claude ultrareview "origin/$BASE..HEAD" --json > /tmp/ultra.json
# Bucket by severity, put HIGH in PR body, MEDIUM/LOW as commentfi
Skip on CC < 2.1.120 (the subcommand doesn't exist there). The .github/workflows/ultrareview.yml workflow runs the same command on PR open as a backstop, so this pre-flight is purely a feedback-loop accelerant.
Progressive Output (CC 2.1.76)
Output results incrementally during PR creation:
After Step
Show User
Pre-flight
Branch status, remote sync result
Each agent
Agent validation result as it returns
Tests
Test results, lint/typecheck status
PR created
PR URL, CI status link
For feature PRs with 3 parallel agents, show each agent's result as it returns — don't wait for all agents before running local tests.
STEP 1: Create Tasks (MANDATORY)
BEFORE doing ANYTHING else, create tasks to track progress:
# 1. Create main task IMMEDIATELY
TaskCreate(subject="Create PR for {branch}", description="PR creation with validation", activeForm="Creating pull request")
# 2. Create subtasks for each phase
TaskCreate(subject="Pre-flight checks", activeForm="Running pre-flight checks") # id=2
TaskCreate(subject="Run validation agents", activeForm="Validating with agents") # id=3
TaskCreate(subject="Run local tests", activeForm="Running local tests") # id=4
TaskCreate(subject="Create PR on GitHub", activeForm="Creating GitHub PR") # id=5
TaskCreate(subject="Generate PR playground", activeForm="Generating playground") # id=6# 3. Set dependencies for sequential phases
TaskUpdate(taskId="3", addBlockedBy=["2"]) # Agents need pre-flight to pass
TaskUpdate(taskId="4", addBlockedBy=["3"]) # Tests run after agent validation
TaskUpdate(taskId="5", addBlockedBy=["4"]) # PR creation needs tests to pass
TaskUpdate(taskId="6", addBlockedBy=["5"]) # Playground after PR (needs title/summary)# 4. Update status as you progress
TaskUpdate(taskId="2", status="in_progress") # When starting
TaskUpdate(taskId="2", status="completed") # When done — repeat for each subtask
Workflow
Phase 1: Pre-Flight Checks
Load: Read("${CLAUDE_PLUGIN_ROOT}/skills/create-pr/rules/preflight-validation.md") for the full checklist.
Before creating the PR, check for the branch activity ledger at .claude/agents/activity/{branch}.jsonl.
If it exists, generate agent attribution sections for the PR body:
Read .claude/agents/activity/{branch}.jsonl (one JSON object per line, full branch history)
Deduplicate by agent type (keep the entry with longest duration for each agent)
Generate the following sections to append to the PR body:
Badge row: shields.io badges for agent count, tests generated, vulnerabilities
Agent Team Sheet: Markdown table with Agent, Role, Stage (Lead/⚡ Parallel/Follow-up), Time
Credits Roll: Collapsible <details> section grouped by execution stage (Lead/Parallel/Follow-up)
If the ledger doesn't exist or is empty, skip this step — create PR normally.
CC 2.1.183 — attribution.sessionUrl: Web and Remote Control sessions append a claude.ai session link to the PR body. For public repos where that link should not be exposed, set attribution.sessionUrl: false (/config attribution.sessionUrl=false) before creating the PR. ork's agent-attribution sections above are independent of this setting.
Phase 4: Create PR
Follow Read("${CLAUDE_PLUGIN_ROOT}/skills/create-pr/rules/pr-title-format.md") and Read("${CLAUDE_PLUGIN_ROOT}/skills/create-pr/rules/pr-body-structure.md"). Use HEREDOC pattern from Read("${CLAUDE_PLUGIN_ROOT}/skills/create-pr/references/pr-body-templates.md").
Include agent attribution sections (from Phase 3b) after the Test Plan section in the PR body.
First classify the archetype — a feature PR must not ship as a flat dashboard.
Read("${CLAUDE_PLUGIN_ROOT}/skills/shared/rules/playground-visual-standard.md") and apply its §0 routing rule:
Visual PR (adds/changes a user-facing feature, flow, or a prioritization/decision surface) →
USER-STORY PLAYER or DECISION BOARD. Build to the standard: adapt the matching exemplar at
${CLAUDE_PLUGIN_ROOT}/skills/shared/assets/playground-exemplars/ (user-story-player.template.html
or decision-board.template.html), and bring full design firepower (the frontend-design skill /
the ork:frontend-ui-developer agent). When delegating to playground:playground, brief it with the
archetype + persona + tokens — never hand it a pre-built HTML blob.
Non-visual PR (infra/CI/refactor/config/docs) → DASHBOARD — the default summary below is fine.
BRANCH=$(git branch --show-current)
BRANCH_DIR = BRANCH.replace("/", "--") # feat/foo → feat--foo# Invoke the playground skill with a summary of the PR changes.# For a VISUAL PR, set archetype/persona/exemplar per playground-visual-standard.md instead of this default.
Skill("playground:playground", args=f"""
{PR_TITLE} — visualize the key changes in this PR.
Archetype: <user-story-player | decision-board | dashboard> per playground-visual-standard.md §0.
For visual archetypes: follow that standard's tokens/glass/motion and adapt the matching exemplar.
Show: architecture/data flow, before/after, key components changed; presets for the main change areas.
Dark glass theme, OrchestKit brand accents.
""")
# The playground skill writes to a temp path — move it to the correct location# Ensure file lands at: docs/{branch-dir}/<name>.html
Bash(f"mkdir -p docs/{BRANCH_DIR}")
Bash(f"mv /tmp/*.html docs/{BRANCH_DIR}/playground.html 2>/dev/null || true")
# Force-add (docs/feat--*/ is gitignored by design)
Bash(f"git add -f docs/{BRANCH_DIR}/")
Bash(f'git commit -m "docs: add PR playground for {BRANCH}"')
Bash(f"git push origin {BRANCH}")
Resolve the head SHA first, and pin the link to it:
Bash("git rev-parse HEAD") # -> {HEAD_SHA}
Add a "Live Preview" section to the PR body:
## Live Preview**[Open Interactive Playground](https://htmlpreview.github.io/?https://github.com/{OWNER}/{REPO}/blob/{HEAD_SHA}/docs/{BRANCH_DIR}/playground.html)**
Pin the SHA, never the branch. GitHub deletes the head branch on merge, so a
blob/{BRANCH}/ URL returns 404 the moment the PR lands. That silently broke the
playground link on every merged PR through #3147. A commit SHA stays reachable
indefinitely because GitHub retains refs/pull/<N>/head, so the same URL works
during review and after merge. Verified: branch form 404, SHA form 200, on a PR
whose branch was already deleted.
Why required: CI Stage 1d (playground-check) blocks merge if docs/{branch-dir}/*.html is missing. Bot PRs (dependabot, release-please) are exempt.
# Guard: Skip cron in headless/CI (CLAUDE_CODE_DISABLE_CRON)# if env CLAUDE_CODE_DISABLE_CRON is set, run a single check instead
CronCreate(
schedule="*/5 * * * *",
prompt="Check CI for PR #{pr_number}: gh pr checks {pr_number} --repo {repo}.
All pass → CronDelete this job, report success.
Any fail → alert with failure details."
)
Run validation locally — Don't spawn agents for lint/test
All content goes to GitHub — PR body via gh pr create --body
Keep it simple — One command to create PR
Respect the gh rate-limit hint (CC ≥ 2.1.116) — when the Bash tool surfaces a GitHub rate-limit hint after a gh call (e.g. in a /loop 5m gh pr checks … watcher), stop the loop and wait for reset — do not blind-retry. See ork:github-operations for the full guidance.
Next Steps (suggest to user after PR creation)
/ork:review-pr {PR_NUMBER} # Self-review before requesting reviews
/loop 5m gh pr checks {PR_NUMBER} # Watch CI until green
/loop 1h gh pr view {PR_NUMBER} --json reviewDecision # Monitor review status
Verification Gate
Before claiming PR is ready, apply: Read("${CLAUDE_PLUGIN_ROOT}/skills/shared/rules/verification-gate.md"). All tests must pass with fresh evidence. All CI checks green. No "should be fine."
Quality Bar
Done means all of these hold:
PR opened from a feature branch with a clean working tree against the correct base ($BASE, derived from origin/HEAD, or the detected host equivalent)
Title uses conventional type(#issue): ... format matching the change
Body carries Summary, Changes, and Test Plan sections; every closed issue has its own Closes #N keyword
Pre-flight validation for the chosen PR type passed locally before creation (skipped only for the Quick type)
Playground HTML exists at docs/{branch-dir}/*.html and the body links it (required for non-bot PRs)
gh pr view --json url returns the created PR URL
Related Skills
ork:commit — Create commits before PRs
ork:review-pr — Review PRs after creation
Picker fallback (#1795)
If the AskUserQuestion picker stalls (schema break, not a CC input bug — orchestkit#1795, now guarded by tests/skills/structure/test-askuserquestion-schema.sh), set ORK_ASK_FALLBACK=text before starting CC. The lifecycle/ask-fallback-injector hook injects a reminder telling the assistant to pose options inline as a numbered list and ask the user to reply with the option number.
References
Load on demand with Read("${CLAUDE_PLUGIN_ROOT}/skills/create-pr/references/<file>"):
