creating-pull-request

cblecker 的头像作者 cblecker

44. 所有PR操作的标准工作流("创建PR"、"打开PR"、"拉取请求"、"提交并PR"):用端到端编排替换基于bash的gh/git工作流 - 处理未提交的更改(自动调用创建提交/创建分支),分析提交历史,生成符合约定的内容,检测fork/origin。git-workflows的规范PR实现。

📖 中文导读:44. 所有PR操作的标准工作流("创建PR"、"打开PR"、"拉取请求"、"提交并PR"):用端到端编排替换基于bash的gh/git工作流 - 处理未提交的更改(自动调用创建提交/创建分支),分析提交历史,生成符合约定的内容,检测fork/origin。git-workflows的规范PR实现。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: Create a GitHub pull request description: Enhances Claude Code PR workflow with fork detection, uncommitted changes handling, and MCP-based creation. Integrates with standard PR behavior—adds repository-aware checks, template discovery, and target branch detection before delegating to default PR content generation. Use for 'create PR', 'open PR', 'pull request', 'submit for review', 'open pull request'.

Skill: Creating a Pull Request

When to Use This Skill

Use this skill for pull request creation requests: "create a PR", "open a PR", "submit for review", or similar.

Use other skills for: viewing existing PRs (GitHub MCP directly), updating PRs (GitHub MCP update), or only committing changes (creating-commit).

Workflow Description

Enhances the standard Claude Code PR workflow with pre-flight checks and repository-aware enhancements. This skill adds fork detection, uncommitted changes handling, and MCP-based PR creation, then delegates content generation to Claude Code's default PR behavior.

This skill provides:

  • Fork detection (origin vs upstream)
  • Uncommitted changes handling (auto-invokes creating-commit)
  • Repository-specific PR template detection
  • MCP-based PR creation (preferred over gh CLI)
  • Atomic context gathering scripts

Claude Code default workflow handles:

  • PR content generation (title, description)
  • Summary/Test plan format
  • Claude Code footer (Generated with Claude Code)
  • Git analysis (diff, log, commit history)

Extract from user request: draft status ("draft"/"WIP" → true, default false), PR title/description (if provided, else delegate to default for generation), target branch (if specified, else mainline)


Phase 1: Gather Context (Optimized)

Objective: Collect all PR context and validate prerequisites in a single atomic operation.

Steps:

  1. Determine base branch from user request (optional):

    • Analyze user request for target branch specification
    • Look for phrases like: "create PR to ", "base on ", "merge into ", "target "
    • Common branch names: develop, staging, main, master, release, etc.
    • Store base_branch if found, otherwise let script detect mainline
  2. Run ${CLAUDE_PLUGIN_ROOT}/scripts/gather-pr-context.sh (optionally pass base_branch parameter if determined in step 1)

  3. Parse the JSON response and handle results:

IF success: false:

See reference/error-types.md (Phase 1: Context Gathering Errors) for detailed error type handling.

Read reference/error-types.md and match error_type from response to documented handling. Follow the prescribed action for the specific error type.

IF success: true:

Extract and store context:

{
  "current_branch": "feature-branch",
  "base_branch": "main",
  "is_fork": true,
  "repository": {
    "upstream_owner": "owner",
    "upstream_repo": "repo",
    "origin_owner": "user",
    "origin_repo": "repo"
  },
  "branch_validation": {
    "is_feature_branch": true,
    "has_uncommitted_changes": false
  },
  "uncommitted_files": [],
  "commit_history": [...],
  "diff_summary": {...},
  "uses_conventional_commits": true
}

Validation Gate: Uncommitted Changes

IF branch_validation.has_uncommitted_changes: true: List files from uncommitted_files array INFORM: "Uncommitted changes detected - creating commit first" INVOKE: creating-commit skill (handles mainline detection internally) WAIT for creating-commit to complete

IF creating-commit succeeded: RE-RUN Phase 1 (gather context again after commit) Continue to Phase 2

IF creating-commit failed: STOP immediately EXPLAIN: "Cannot create PR without committing changes" EXIT workflow

IF no uncommitted changes: Continue to Phase 2

Phase 1 complete. Continue to Phase 2.


Phase 2: Verify PR Base Branch

Objective: Confirm target branch for pull request.

Steps:

  1. Use base_branch from Phase 1 context (already detected mainline)

  2. IF user specified different target branch in Step 1 of Phase 1:

    • Override with user-specified branch
    • INFORM: "Using as PR base (overriding default )"
  3. Store pr_base for later phases

Phase 2 complete. Continue to Phase 3.


Phase 3: Delegate to Default PR Workflow

Objective: Generate PR title and description using Claude Code's default PR workflow with the context from Phase 1.

System Workflow Delegation:

Proceed with the standard Claude Code PR workflow as defined in the system prompt. The system workflow includes:

  1. Run git commands in parallel:

    • git status to see untracked files
    • git diff to see changes (both staged and unstaged)
    • git log to see recent commits for context
    • git diff [base-branch]...HEAD to understand ALL commits in the PR
  2. Analyze ALL commits in the PR:

    • Review the full commit history from the branch point to HEAD
    • Consider the hints from Phase 1 (conventional commits format, commit history, diff summary)
    • If repository uses Conventional Commits (uses_conventional_commits: true), consider using format for title
  3. Generate PR title and description:

    • Use the standard Claude Code PR format:

      ## Summary
      <1-3 bullet points summarizing changes>
      
      ## Test plan
      <Bulleted checklist of testing steps>
      
      ---
      Generated with [Claude Code](https://claude.ai/code)
      
    • If repository has PR template (check .github/pull_request_template.md and similar paths), use template structure instead

    • Title: Concise summary of changes (<72 chars)

    • If user provided explicit title/description in request, use those instead

  4. Present for approval:

    • Show generated title and description to user
    • Allow user to edit if needed

This skill's enhancements:

This skill overrides the default PR creation steps:

  • Default uses: gh pr create (CLI tool)
  • This skill uses: MCP tool mcp__plugin_github_github__create_pull_request (Phase 5)
  • This skill handles: Correct remote for forks (origin for forks, Phase 4)

This skill provided: Fork detection, uncommitted changes handling, atomic context gathering

Continue to Phase 4 (Push to Remote).


Phase 4: Push to Remote

Objective: Push current branch to remote.

Plan Mode: Auto-enforced read-only if active

Steps:

  1. Use current_branch from Phase 1 context (no need to query git)

  2. Push branch with upstream tracking:

    git push -u origin <current_branch>
    

Validation Gate: Push Failure

IF push fails:

See reference/error-types.md (Phase 4: Push Failures) for detailed error handling.

Read reference/error-types.md and match error message to documented failure scenarios. Follow the prescribed action for the specific error type.

Continue to Phase 5.


Phase 5: Create Pull Request

Objective: Create PR on GitHub using MCP.

Plan Mode: Auto-enforced read-only if active

Steps:

  1. Prepare parameters from Phase 1 context:

    • owner, repo: From repository object
    • head: current_branch
    • base: pr_base (from Phase 2)
    • title/body: Generated in Phase 3, approved in Phase 4
  2. Determine draft: Check user request for "draft", "WIP", "work in progress"

  3. Create: mcp__github__create_pull_request with all parameters

Error Handling: IF failure:

See reference/error-types.md (Phase 5: PR Creation Failures) for detailed error handling.

Read reference/error-types.md and match error to documented failure scenarios. Follow the prescribed action for the specific error type.

Continue to Phase 7.


Phase 7: Return PR URL

Objective: Provide PR URL and confirm success with standardized output.

Steps:

  1. Extract from Phase 6: PR number, URL, state, title

  2. Format output using standardized template:

    ✓ Pull Request Created Successfully
    
    **PR Number:** #<number> \
    **Title:** <title> \
    **URL:** <pr_url> \
    **Status:** <Open|Draft> \
    **Base Branch:** <base_branch> \
    **Head Branch:** <head_branch>
    
    [If draft: **Notes:** Mark as 'Ready for review' when ready]
    [If open: **Notes:** The pull request is ready for review]
    

Workflow complete.