pr-create

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Creator Skill

Get changes into a PR, monitor CI, fix any failures, and notify the user when the PR is ready for review.

The user may already have commits ready on a feature branch, or may have uncommitted changes, or both. Adapt the workflow to the current state.

将变更提交至PR，监控CI，修复所有失败项，并在PR准备好评审时通知用户。

用户可能已在功能分支上准备好提交记录，或存在未提交的变更，或两者皆有。需根据当前状态调整工作流。

Task List Integration

任务列表集成

CRITICAL: Use Claude Code's task list system for progress tracking and session recovery. Use TaskCreate, TaskUpdate, and TaskList tools throughout execution.

重要提示： 使用Claude Code的任务列表系统进行进度跟踪和会话恢复。在整个执行过程中使用TaskCreate、TaskUpdate和TaskList工具。

Task Hierarchy

任务层级

[Main Task] "Create PR: [branch-name]"
  └── [CI Task] "CI Run #1" (status: failed, reason: lint)
      └── [Fix Task] "Fix: lint"
  └── [CI Task] "CI Run #2" (status: failed, reason: test failures)
      └── [Fix Task] "Fix: test failures"
  └── [CI Task] "CI Run #3" (status: passed)

At the start, always call TaskList to check for existing PR tasks. If a "Create PR" task exists with status in_progress, resume using the Session Recovery section below.

[Main Task] "Create PR: [branch-name]"
  └── [CI Task] "CI Run #1" (status: failed, reason: lint)
      └── [Fix Task] "Fix: lint"
  └── [CI Task] "CI Run #2" (status: failed, reason: test failures)
      └── [Fix Task] "Fix: test failures"
  └── [CI Task] "CI Run #3" (status: passed)

开始时，务必调用TaskList检查是否存在现有PR任务。 如果存在状态为in_progress的“Create PR”任务，请按照下方的会话恢复部分继续执行。

Process

流程

Step 1: Assess Current State

步骤1：评估当前状态

Create the main PR task:

TaskCreate:
- subject: "Create PR: [branch-name or 'pending']"
- description: "Create pull request from current changes."
- activeForm: "Checking git status"

TaskUpdate:
- taskId: [pr task ID]
- status: "in_progress"

Determine the base branch and current state:

bash

git status
git diff --stat

创建主PR任务：

TaskCreate:
- subject: "Create PR: [branch-name or 'pending']"
- description: "Create pull request from current changes."
- activeForm: "Checking git status"

TaskUpdate:
- taskId: [pr task ID]
- status: "in_progress"

确定基准分支和当前状态：

bash

git status
git diff --stat

Detect the default branch (main, master, develop, etc.)

检测默认分支（main、master、develop等）

gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' git log --oneline <base-branch>..HEAD gh pr view 2>/dev/null


**Determine the starting point:**

| State | Next Step |
|-------|-----------|
| On base branch with uncommitted changes | Step 2 (create branch) |
| On feature branch with uncommitted changes | Step 3 (commit) |
| On feature branch with commits, nothing uncommitted | Step 4 (sync) |
| PR already exists for this branch | Inform user, ask whether to update or monitor CI |
| No changes anywhere | Inform user "No changes detected. Nothing to do." and stop |

**Update task with branch info:**

TaskUpdate:

taskId: [pr task ID]
subject: "Create PR: [actual-branch-name]"
metadata: {"branch": "[branch-name]", "baseBranch": "[base-branch]"}

undefined

gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' git log --oneline <base-branch>..HEAD gh pr view 2>/dev/null


**确定起始操作：**

| 状态 | 下一步操作 |
|-------|-----------|
| 当前在基准分支，存在未提交变更 | 步骤2（创建分支） |
| 当前在功能分支，存在未提交变更 | 步骤3（提交变更） |
| 当前在功能分支，已提交所有变更 | 步骤4（与基准分支同步） |
| 该分支已存在对应PR | 告知用户，询问是否更新PR或监控CI |
| 无任何变更 | 告知用户“未检测到变更，无需执行操作”并终止流程 |

**更新任务的分支信息：**

TaskUpdate:

taskId: [pr task ID]
subject: "Create PR: [actual-branch-name]"
metadata: {"branch": "[branch-name]", "baseBranch": "[base-branch]"}

undefined

Step 2: Create Branch (if needed)

步骤2：创建分支（如需要）

If currently on the base branch:

bash

git checkout -b <descriptive-branch-name>

Use the project's branch naming conventions if documented in CLAUDE.md or AGENTS.md. Otherwise use:

```
feat/short-description
```
for features
```
fix/short-description
```
for bug fixes
```
refactor/short-description
```
for refactoring
```
docs/short-description
```
for documentation

如果当前处于基准分支：

bash

git checkout -b <descriptive-branch-name>

如果CLAUDE.md或AGENTS.md中记录了项目的分支命名规范，请遵循该规范。否则使用以下命名方式：

```
feat/short-description
```
用于功能开发
```
fix/short-description
```
用于Bug修复
```
refactor/short-description
```
用于代码重构
```
docs/short-description
```
用于文档更新

Step 3: Stage and Commit Changes (if needed)

步骤3：暂存并提交变更（如需要）

Skip this step entirely if there are no uncommitted changes.

Stage specific files rather than using

git add -A

bash

git status
git add <file1> <file2> ...
git diff --cached --stat
git commit -m "$(cat <<'EOF'
<type>: <short summary>

<optional longer description>
EOF
)"

Follow the project's commit conventions if documented in CLAUDE.md or AGENTS.md. Otherwise use conventional commits:

feat:

fix:

refactor:

docs:

test:

chore:

If the commit fails due to a pre-commit hook:

Read the error output to understand what the hook requires
Fix the flagged issues
Stage the fixed files
Create a new commit (do NOT amend the previous commit)

如果不存在未提交变更，请完全跳过此步骤。

暂存指定文件，而非使用

git add -A

：

bash

git status
git add <file1> <file2> ...
git diff --cached --stat
git commit -m "$(cat <<'EOF'
<type>: <short summary>

<optional longer description>
EOF
)"

如果CLAUDE.md或AGENTS.md中记录了项目的提交规范，请遵循该规范。否则使用约定式提交格式：

feat:

、

fix:

、

refactor:

、

docs:

、

test:

、

chore:

。

如果提交因预提交钩子失败：

读取错误输出以了解钩子的要求
修复标记的问题
暂存修复后的文件
创建新的提交记录（请勿修改之前的提交）

Step 4: Sync with Base Branch (if needed)

步骤4：与基准分支同步（如需要）

bash

git fetch origin
git log --oneline HEAD..origin/<base-branch> | head -20

If up to date (no output), proceed to Step 5.

If behind, inform the user how many commits behind and offer options using

AskUserQuestion

Rebase (recommended when no PR exists yet)
Merge (safer with many commits or shared branches)
Skip (proceed without syncing)

Do NOT rebase or merge without user confirmation.

If conflicts arise, inform the user and help resolve them.

bash

git fetch origin
git log --oneline HEAD..origin/<base-branch> | head -20

如果已同步（无输出），继续执行步骤5。

如果落后于基准分支，告知用户落后的提交数量，并使用

AskUserQuestion

提供以下选项：

变基（推荐在PR尚未创建时使用）
合并（在存在大量提交或分支为共享分支时更安全）
跳过（不执行同步直接继续）

未获得用户确认前，请勿执行变基或合并操作。

如果出现冲突，告知用户并协助解决。

Step 5: Draft PR Title and Body

步骤5：草拟PR标题和正文

Get user approval on the PR content now, before running pre-flight checks. This keeps the user engaged while they're focused on the task.

5a. Gather context:

bash

git log --oneline <base-branch>..HEAD
git diff <base-branch>...HEAD --stat

5b. Draft the PR title and body:

Follow the project's PR conventions if documented in CLAUDE.md or AGENTS.md. Otherwise:

Title: Under 70 characters, describes the change
Body: Start with issue references on the first line (e.g.
```
Closes #45
```
), then a structured description:

markdown

[issue references: Fixes #...]

在执行预检查前，请先获取用户对PR内容的批准，这样能让用户在专注于任务时保持参与度。

5a. 收集上下文信息：

bash

git log --oneline <base-branch>..HEAD
git diff <base-branch>...HEAD --stat

5b. 草拟PR标题和正文：

如果CLAUDE.md或AGENTS.md中记录了项目的PR规范，请遵循该规范。否则：

标题： 不超过70个字符，清晰描述变更内容
正文： 首行填写关联的Issue引用（例如
```
Closes #45
```
），然后使用结构化描述：

markdown

[issue references: Fixes #...]

Summary

摘要

Verification

验证方式

<how to verify> ```

Summary: Give an overview of the changes in the PR. The target audience is an experienced developer who works in this code base and needs to be informed about design or architectural changes. Highlight key decisions, structures and patterns.

Verification: include an example that demonstrates the changes in the PR as seen or used by the intended audience. For code packages, include a small, reproducible exmaple. For apps and interfaces, describe the steps required to see the new behavior.

5c. Preview and get user approval:

CRITICAL: Use

AskUserQuestion

to show the user the proposed PR title and body. Do NOT create the PR until the user approves. Revise and re-preview if needed.

5d. Confirm before proceeding to automated steps:

Once approved, use

AskUserQuestion

to outline what happens next and get confirmation:

Here's what I'll do next:

Run local checks (if available for this project)

Push the branch to origin

Create the PR with the approved title and body

Monitor CI and fix any failures

I'll auto-fix small issues (formatting, lint, type errors, test failures). If anything bigger comes up, I'll check with you first.

Ready to proceed?

Do NOT continue to Step 6 until the user confirms.

<how to verify> ```

摘要：概述PR中的变更内容，目标受众为熟悉代码库的资深开发者，需重点说明设计或架构变更、关键决策、结构和模式。

验证方式：提供一个示例，展示PR变更的实际效果。对于代码包，提供一个小型可复现的示例；对于应用和界面，描述查看新行为所需的步骤。

5c. 预览并获取用户批准：

重要提示： 使用

AskUserQuestion

向用户展示草拟的PR标题和正文。在获得用户批准前，请勿创建PR。如有需要，可修改后重新预览。

5d. 执行自动化步骤前确认：

获得批准后，使用

AskUserQuestion

告知用户后续操作并获取确认：

接下来我将执行以下操作：

运行本地检查（如果项目支持）

推送分支至远程仓库

创建PR，使用已批准的标题和正文

监控CI并修复所有失败项

我将自动修复小型问题（格式、代码检查、类型错误、测试失败）。如果遇到较大问题，我会先与您确认。

是否准备继续？

在获得用户确认前，请勿继续执行步骤6。

Step 6: Run Local Pre-flight Checks

步骤6：运行本地预检查

This step catches most CI failures before pushing.

Determine the project's local check commands by consulting (in priority order):

CLAUDE.md or AGENTS.md in the project root (may specify lint, test, build commands)

Project config files:

package.json

(scripts),

Makefile

pyproject.toml

DESCRIPTION

Justfile

Taskfile.yml

, etc.

CI workflow files in
```
.github/workflows/
```
to understand what CI will run

Run the checks that are available locally. Common patterns:

Lint/format:

npm run lint

ruff check

air format

biome check

, etc.

Build:

npm run build

pip install -e .

devtools::check()

, etc.

Type check:
```
npm run check-types
```
,
```
mypy
```
,
```
pyright
```
, etc.

Tests:

npm test

pytest

devtools::test()

cargo test

, etc.

If no local check commands are discoverable, skip this step and rely on CI.

Fixing failures:

Obvious, mechanical fixes — fix autonomously:
- Formatting issues (run auto-formatter if available)
- Lint errors with clear fixes
- Simple build, test, or type errors with obvious corrections
- Stage the fixed files and commit the fix (specific files, not
```
git add -A
```
  )
- Re-run the failing check to confirm it passes
- ALWAYS call out changes made in this step in the final summary
Non-obvious failures — use
```
AskUserQuestion
```
to present the issue and offer resolution options

此步骤可在推送前发现大部分CI失败问题。

按以下优先级确定项目的本地检查命令：

项目根目录下的CLAUDE.md或AGENTS.md（可能指定了代码检查、测试、构建命令）

项目配置文件：

package.json

（scripts字段）、

Makefile

、

pyproject.toml

、

DESCRIPTION

、

Justfile

、

Taskfile.yml

等

```
.github/workflows/
```
目录下的CI工作流文件，了解CI将执行的检查内容

运行可用的本地检查。常见命令示例：

代码检查/格式化：

npm run lint

、

ruff check

、

air format

、

biome check

等

构建：

npm run build

、

pip install -e .

、

devtools::check()

等

类型检查：
```
npm run check-types
```
、
```
mypy
```
、
```
pyright
```
等

测试：

npm test

、

pytest

、

devtools::test()

、

cargo test

等

如果无法找到本地检查命令，跳过此步骤，依赖CI执行检查。

修复失败项：

明显的机械性问题——自主修复：
- 格式问题（如果有自动格式化工具，运行对应命令）
- 有明确修复方案的代码检查错误
- 简单的构建、测试或类型错误
- 暂存修复后的文件并提交（仅暂存指定文件，不使用
```
git add -A
```
  ）
- 重新运行失败的检查以确认修复成功
- 务必在最终总结中说明此步骤所做的变更
非明显的失败问题——使用
```
AskUserQuestion
```
向用户说明问题并提供解决方案选项

Step 7: Push Branch

步骤7：推送分支

bash

git push -u origin <branch-name>

bash

git push -u origin <branch-name>

Step 8: Create Pull Request

步骤8：创建Pull Request

bash

gh pr create --title "<approved-title>" --body "$(cat <<'EOF'
<approved-body>
EOF
)"

Capture the PR URL and store in task metadata:

TaskUpdate:
- taskId: [pr task ID]
- metadata: {"prUrl": "<url>", "prNumber": <N>, "prTitle": "<title>", "commits": <count>}

bash

gh pr create --title "<approved-title>" --body "$(cat <<'EOF'
<approved-body>
EOF
)"

捕获PR链接并存储到任务元数据中：

TaskUpdate:
- taskId: [pr task ID]
- metadata: {"prUrl": "<url>", "prNumber": <N>, "prTitle": "<title>", "commits": <count>}

Step 9: Monitor CI

步骤9：监控CI

Create a CI run task:

TaskCreate:
- subject: "CI Run #[N]: monitoring"
- description: "Monitoring CI run for PR #[number]"
- activeForm: "Monitoring CI Run #[N]"

TaskUpdate:
- taskId: [ci task ID]
- addBlockedBy: [pr task ID]
- status: "in_progress"

Wait for CI to start, then monitor:

bash

undefined

创建CI运行任务：

TaskCreate:
- subject: "CI Run #[N]: monitoring"
- description: "Monitoring CI run for PR #[number]"
- activeForm: "Monitoring CI Run #[N]"

TaskUpdate:
- taskId: [ci task ID]
- addBlockedBy: [pr task ID]
- status: "in_progress"

等待CI启动后开始监控：

bash

undefined

List workflow runs for this PR

列出该PR的工作流运行记录

gh run list --branch <branch-name> --limit 5

Watch a specific run silently until completion

静默监控指定运行记录直至完成

--exit-status returns exit code 0 on success, non-zero on failure

--exit-status在成功时返回0，失败时返回非0值

gh run watch <run-id> --exit-status > /dev/null 2>&1 echo "Exit: $?"

Or check status without blocking

或非阻塞式检查状态

gh run view <run-id>


**IMPORTANT:** Do NOT run `gh run watch` without redirecting output. It generates thousands of lines of repeated status updates. Always redirect to `/dev/null` and rely on the exit code.

**Store run ID in task:**

TaskUpdate:

taskId: [ci task ID]
metadata: {"runId": "[run-id]", "status": "running"}

undefined

gh run view <run-id>


**重要提示：** 运行`gh run watch`时务必重定向输出，否则会生成数千行重复的状态更新。请始终将输出重定向至`/dev/null`，并依赖退出码判断结果。

**将运行ID存储到任务中：**

TaskUpdate:

taskId: [ci task ID]
metadata: {"runId": "[run-id]", "status": "running"}

undefined

Step 10: Handle CI Results

步骤10：处理CI结果

If CI Passes:

如果CI通过：

TaskUpdate:
- taskId: [ci task ID]
- subject: "CI Run #[N]: passed"
- status: "completed"
- metadata: {"status": "passed"}

STOP HERE - do not merge
Report to user with PR URL, branch, and CI status

TaskUpdate:
- taskId: [ci task ID]
- subject: "CI Run #[N]: passed"
- status: "completed"
- metadata: {"status": "passed"}

在此终止流程——不执行合并操作
向用户报告PR链接、分支信息和CI状态

If CI Fails:

如果CI失败：

TaskUpdate:
- taskId: [ci task ID]
- subject: "CI Run #[N]: failed"
- status: "completed"
- metadata: {"status": "failed", "failureReason": "[brief reason]"}

Get failure details:

--log-failed

can produce thousands of lines. Use a targeted approach:

bash

# Summary of which jobs/steps failed
gh run view <run-id>

# Failed logs, limited to the last 40 lines (where the error usually is)
gh run view <run-id> --log-failed 2>&1 | tail -40

# Search for specific errors if needed
gh run view <run-id> --log-failed 2>&1 | grep -A 5 -B 5 "error\|Error\|FAIL\|failed"

Work from the bottom of the output upward — the actual error is almost always near the end.

Reproduce locally using the project's local check commands (discovered in Step 6).

Create a fix task:

TaskCreate:
- subject: "Fix: [failure reason]"
- description: "Fixing CI failure from Run #[N]: [detailed error]"
- activeForm: "Fixing [failure reason]"

TaskUpdate:
- taskId: [fix task ID]
- addBlockedBy: [ci task ID]
- status: "in_progress"

Fix the issue, verify locally, then commit and push:

bash

git add <specific-files>
git commit -m "$(cat <<'EOF'
fix: <what was fixed>
EOF
)"
git push

Mark fix task completed:

TaskUpdate:
- taskId: [fix task ID]
- status: "completed"

Return to Step 9 — monitor the new CI run (increment run number)

Repeat until CI passes.

TaskUpdate:
- taskId: [ci task ID]
- subject: "CI Run #[N]: failed"
- status: "completed"
- metadata: {"status": "failed", "failureReason": "[brief reason]"}

获取失败详情：

--log-failed

可能生成数千行输出，请使用针对性方法：

bash

# 汇总失败的作业/步骤
gh run view <run-id>

# 失败日志，仅显示最后40行（通常错误信息位于末尾）
gh run view <run-id> --log-failed 2>&1 | tail -40

# 如有需要，搜索特定错误
gh run view <run-id> --log-failed 2>&1 | grep -A 5 -B 5 "error\|Error\|FAIL\|failed"

从输出末尾开始向上查看——实际错误几乎总是位于输出末尾。

在本地复现问题，使用步骤6中发现的本地检查命令。

创建修复任务：

TaskCreate:
- subject: "Fix: [failure reason]"
- description: "Fixing CI failure from Run #[N]: [detailed error]"
- activeForm: "Fixing [failure reason]"

TaskUpdate:
- taskId: [fix task ID]
- addBlockedBy: [ci task ID]
- status: "in_progress"

修复问题，在本地验证后提交并推送：

bash

git add <specific-files>
git commit -m "$(cat <<'EOF'
fix: <what was fixed>
EOF
)"
git push

标记修复任务为已完成：

TaskUpdate:
- taskId: [fix task ID]
- status: "completed"

返回步骤9——监控新的CI运行记录（递增运行编号）

重复执行直至CI通过。

Step 11: Final Report

步骤11：最终报告

Mark main PR task as completed.

Call

TaskList

to gather all CI run and fix tasks, then generate the summary:

markdown

undefined

标记主PR任务为已完成。

调用

TaskList

收集所有CI运行和修复任务，然后生成总结报告：

markdown

undefined

PR Ready for Review

PR已准备好评审

PR: #<number> <title> Branch:

<branch-name>

<base-branch>

Commits: <count> CI Status: All checks passed

PR： #<number> <title> 分支：

<branch-name>

<base-branch>

提交记录数： <count> CI状态： 所有检查已通过

CI Runs

CI运行记录

Run #1: Failed (lint) -> Fixed in [hash]
Run #2: Passed

Note: This PR has NOT been merged. Please review and merge manually.

undefined

运行#1：失败（代码检查）-> 在[hash]中修复
运行#2：通过

注意： 此PR尚未合并，请手动评审并合并。

undefined

Session Recovery

会话恢复

If resuming from an interrupted session:

TaskList shows:
├── PR task in_progress, no CI tasks
│   └── PR was created, start monitoring CI (Step 9)
├── PR task in_progress, CI task in_progress
│   └── Resume monitoring CI run from task metadata runId
├── PR task in_progress, CI task failed, no fix task
│   └── Analyze failure and create fix task (Step 10)
├── PR task in_progress, fix task in_progress
│   └── Continue fixing, then push and monitor new CI run
├── PR task completed
│   └── PR is done, show final report
└── No tasks exist
    └── Fresh start (Step 1)

When resuming, use

gh run view <runId>

from CI task metadata to check if the run is still active, completed, or superseded. Inform the user of the current state before resuming.

如果从中断的会话中恢复：

TaskList显示以下情况：
├── PR任务状态为in_progress，无CI任务
│   └── PR已创建，开始监控CI（步骤9）
├── PR任务状态为in_progress，CI任务状态为in_progress
│   └── 从任务元数据的runId恢复监控CI运行记录
├── PR任务状态为in_progress，CI任务已失败，无修复任务
│   └── 分析失败原因并创建修复任务（步骤10）
├── PR任务状态为in_progress，修复任务状态为in_progress
│   └── 继续修复，然后推送并监控新的CI运行记录
├── PR任务已完成
│   └── PR已完成，显示最终报告
└── 无任何任务
    └── 从头开始（步骤1）

恢复会话时，使用CI任务元数据中的

gh run view <runId>

检查运行记录是否仍在进行、已完成或已被替代。在恢复前告知用户当前状态。

Important Rules

重要规则

NEVER merge the PR - only create it and ensure CI passes
NEVER force push unless explicitly asked
NEVER push to base branch directly
Continue fixing until CI passes - don't give up after one failure
Preserve commit history - don't squash unless asked
ALWAYS preview PR title and body with the user before creating
ALWAYS stage specific files - never use
```
git add -A
```
or
```
git add .
```
NEVER amend commits unless explicitly asked - always create new commits for fixes

绝不要合并PR——仅创建PR并确保CI通过
除非明确要求，否则不要强制推送
绝不要直接推送到基准分支
持续修复直至CI通过——不要在一次失败后放弃
保留提交历史——除非要求，否则不要压缩提交
创建PR前务必向用户预览标题和正文
始终暂存指定文件——绝不要使用
```
git add -A
```
或
```
git add .
```
除非明确要求，否则不要修改提交记录——始终为修复创建新的提交记录

Error Handling

错误处理

Authentication issues: If

gh

commands fail with auth errors, inform the user to run

gh auth login

Branch conflicts: Offer rebase or merge options. Resolve conflicts if any, then continue.

PR already exists: Inform user a PR already exists for this branch. Ask if they want to update it or monitor its CI.

Pre-commit hook failures: Read the hook error output, fix the flagged issues, stage the fixes, and create a new commit. Do NOT amend.

认证问题： 如果

gh

命令因认证失败，请告知用户运行

gh auth login

。

分支冲突： 提供变基或合并选项。如果存在冲突，协助解决后继续执行。

PR已存在： 告知用户该分支已存在对应PR，询问是否更新PR或监控其CI状态。

预提交钩子失败： 读取钩子的错误输出，修复标记的问题，暂存修复后的文件，并创建新的提交记录。请勿修改现有提交。