Skill v2.5.0
currentAutomated scan100/100name: create-pr license: MIT compatibility: "Claude Code 2.1.139+. 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. Use when opening PRs or submitting code for review." argument-hint: "[title]" context: fork version: 2.5.0 author: OrchestKit tags: [git, github, pull-request, pr, code-review] user-invocable: true disable-model-invocation: true allowed-tools: [AskUserQuestion, Bash, Task, TaskCreate, TaskUpdate, Skill, mcp__memory__search_nodes, CronCreate, CronDelete] skills: [commit, review-pr, memory, chain-patterns] complexity: medium persuasion-type: guidance metadata: category: workflow-automation mcp-server: memory triggers: 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 dev"
- "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(withGH_HOST=<host>for GHE) || gitlab / gitlab-self |glab mr create|| bitbucket |bb pr create|Custom enterprise URLs:prUrlTemplatesetting (seesrc/skills/configure/andsrc/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)
STEP 0: Verify User Intent
BEFORE creating tasks, clarify PR type:
AskUserQuestion(questions=[{"question": "What type of PR is this?","header": "PR Type","options": [{"label": "Feature (Recommended)", "description": "Full validation: security + quality + tests", "markdown": "```\nFeature PR\n──────────\n Pre-flight ──▶ 3 agents ──▶ Tests ──▶ PR\n ┌────────────┐ ┌─────────────────────┐\n │ Branch OK? │ │ security-auditor │\n │ Clean tree?│ │ test-generator │\n │ Remote? │ │ code-quality-review │\n └────────────┘ └─────────────────────┘\n Full validation, ~5 min\n```"},{"label": "Bug fix", "description": "Focus on test verification", "markdown": "```\nBug Fix PR\n──────────\n Pre-flight ──▶ test-generator ──▶ Tests ──▶ PR\n\n Agent: test-generator only\n Verifies regression test exists\n ~2 min\n```"},{"label": "Refactor", "description": "Code quality review, skip security", "markdown": "```\nRefactor PR\n───────────\n Pre-flight ──▶ code-quality ──▶ Tests ──▶ PR\n\n Agent: code-quality-reviewer only\n Checks: no behavior change,\n complexity reduction, patterns\n ~2 min\n```"},{"label": "Quick", "description": "Skip validation, just create PR", "markdown": "```\nQuick PR (~30s)\n───────────────\n Pre-flight ──▶ PR\n\n No agents, no tests\n Just create the PR\n```"}],"multiSelect": false}])
Based on answer, adjust workflow:
- 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; thenclaude 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 IMMEDIATELYTaskCreate(subject="Create PR for {branch}", description="PR creation with validation", activeForm="Creating pull request")# 2. Create subtasks for each phaseTaskCreate(subject="Pre-flight checks", activeForm="Running pre-flight checks") # id=2TaskCreate(subject="Run validation agents", activeForm="Validating with agents") # id=3TaskCreate(subject="Run local tests", activeForm="Running local tests") # id=4TaskCreate(subject="Create PR on GitHub", activeForm="Creating GitHub PR") # id=5TaskCreate(subject="Generate PR playground", activeForm="Generating playground") # id=6# 3. Set dependencies for sequential phasesTaskUpdate(taskId="3", addBlockedBy=["2"]) # Agents need pre-flight to passTaskUpdate(taskId="4", addBlockedBy=["3"]) # Tests run after agent validationTaskUpdate(taskId="5", addBlockedBy=["4"]) # PR creation needs tests to passTaskUpdate(taskId="6", addBlockedBy=["5"]) # Playground after PR (needs title/summary)# 4. Before starting each task, verify it's unblockedtask = TaskGet(taskId="2") # Verify blockedBy is empty# 5. Update status as you progressTaskUpdate(taskId="2", status="in_progress") # When startingTaskUpdate(taskId="2", status="completed") # When done — repeat for each subtask
Workflow
Phase 1: Pre-Flight Checks
Load: Read("${CLAUDE_SKILL_DIR}/rules/preflight-validation.md") for the full checklist.
BRANCH=$(git branch --show-current)[[ "$BRANCH" == "dev" || "$BRANCH" == "main" ]] && echo "Cannot PR from dev/main" && exit 1[[ -n $(git status --porcelain) ]] && echo "Uncommitted changes" && exit 1git fetch origingit rev-parse --verify "origin/$BRANCH" &>/dev/null || git push -u origin "$BRANCH"
Phase 2: Parallel Validation (Feature/Bug fix PRs)
Launch agents in ONE message. Load Read("${CLAUDE_SKILL_DIR}/references/parallel-validation.md") for full agent configs.
| PR Type | Agents to launch | |
|---|---|---|
| Feature | security-auditor + test-generator + code-quality-reviewer | |
| Bug fix | test-generator only | |
| Refactor | code-quality-reviewer only | |
| Quick | None |
After agents complete, run local validation:
# Adapt to project stacknpm run lint && npm run typecheck && npm test -- --bail# or: ruff check . && pytest tests/unit/ -v --tb=short -x
Phase 3: Gather Context
BRANCH=$(git branch --show-current)ISSUE=$(echo "$BRANCH" | grep -oE '[0-9]+' | head -1)git log --oneline dev..HEADgit diff dev...HEAD --stat
Phase 3b: Agent Attribution (automatic)
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)
- Each agent entry has:
agent(type),stage(0=lead, 1=parallel, 2=follow-up),duration_ms,summary
If the ledger doesn't exist or is empty, skip this step — create PR normally.
Phase 4: Create PR
Follow Read("${CLAUDE_SKILL_DIR}/rules/pr-title-format.md") and Read("${CLAUDE_SKILL_DIR}/rules/pr-body-structure.md"). Use HEREDOC pattern from Read("${CLAUDE_SKILL_DIR}/references/pr-body-templates.md").
Include agent attribution sections (from Phase 3b) after the Test Plan section in the PR body.
TYPE="feat" # Determine: feat/fix/refactor/docs/test/choregh pr create --base dev \--title "$TYPE(#$ISSUE): Brief description" \--body "$(cat <<'EOF'## Summary[1-2 sentence description]## Changes- [Change 1]- [Change 2]## Test Plan- [x] Unit tests pass- [x] Lint/type checks pass## Agent Team Sheet| Agent | Role | Stage | Time ||-------|------|-------|------|| 🏗️ **backend-system-architect** | API design | Lead | 2m14s || 🛡️ **security-auditor** | Dependency audit | ⚡ Parallel | 0m42s || 🧪 **test-generator** | 47 tests, 94% coverage | ⚡ Parallel | 2m01s |<details><summary><strong>🎬 Agent Credits</strong> — 3 agents collaborated on this PR</summary>**Lead**- 🏗️ **backend-system-architect** — API design (2m14s)**⚡ Parallel** (ran simultaneously)- 🛡️ **security-auditor** — Dependency audit (0m42s)- 🧪 **test-generator** — 47 tests, 94% coverage (2m01s)---<sub>Orchestrated by <a href="https://github.com/yonatangross/orchestkit">OrchestKit</a> — 3 agents, 4m57s total</sub></details>Closes #$ISSUE---Generated with [Claude Code](https://claude.com/claude-code)EOF)"
Phase 4b: Generate PR Playground (REQUIRED — CI blocks without it)
Generate an interactive HTML playground visualizing the PR's changes. CI validates docs/{branch-name}/*.html exists.
Requires theplaygroundplugin (external):/plugin marketplace add anthropics/claude-plugins-official && /plugin install playground
BRANCH=$(git branch --show-current)BRANCH_DIR = BRANCH.replace("/", "--") # feat/foo → feat--foo# Invoke the playground skill with a summary of the PR changesSkill("playground:playground", args=f"""{PR_TITLE} — visualize the key changes in this PR.Show: architecture/data flow, before/after, key components changed.Include presets for the main change areas.Dark theme with purple/violet OrchestKit brand colors.""")# The playground skill writes to a temp path — move it to the correct location# Ensure file lands at: docs/{branch-dir}/<name>.htmlBash(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}")
Add a "Live Preview" section to the PR body:
## Live Preview**[Open Interactive Playground](https://htmlpreview.github.io/?https://github.com/{OWNER}/{REPO}/blob/{BRANCH}/docs/{BRANCH_DIR}/playground.html)**
Why required: CI Stage 1d (playground-check) blocks merge ifdocs/{branch-dir}/*.htmlis missing. Bot PRs (dependabot, release-please) are exempt.
Phase 5: Verify
PR_URL=$(gh pr view --json url -q .url)echo "PR created: $PR_URL"
CI Monitoring (CC 2.1.71)
After PR creation, schedule CI status monitoring:
# Guard: Skip cron in headless/CI (CLAUDE_CODE_DISABLE_CRON)# if env CLAUDE_CODE_DISABLE_CRON is set, run a single check insteadCronCreate(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.")
Handoff File
Write PR details for downstream skills:
Write(".claude/chain/pr-created.json", JSON.stringify({"phase": "create-pr", "pr_number": N, "pr_url": "...","branch": "...", "files_changed": [...], "related_issues": [...]}))
Rules
- NO junk files — Don't create files in repo root
- 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
ghcall (e.g. in a/loop 5m gh pr checks …watcher), stop the loop and wait for reset — do not blind-retry. Seeork:github-operationsfor 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."
Related Skills
ork:commit— Create commits before PRsork:review-pr— Review PRs after creation
Picker fallback (#1795)
If the AskUserQuestion picker stalls (CC 2.1.139 input bug — orchestkit#1795), 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_SKILL_DIR}/references/<file>"):
| File | Content | |
|---|---|---|
references/pr-body-templates.md | PR body templates | |
references/parallel-validation.md | Parallel validation agent configs | |
references/ci-integration.md | CI integration patterns | |
references/multi-commit-pr.md | Multi-commit PR guidance | |
assets/pr-template.md | PR template (legacy) |