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.

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.

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.

Process

Step 1: Assess Current State

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
# Detect the default branch (main, master, develop, etc.)
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]"}

Step 2: Create Branch (if needed)

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

Step 3: Stage and Commit Changes (if needed)

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)

Step 4: Sync with Base Branch (if needed)

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.

Step 5: Draft PR Title and Body

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 #...]

## Summary
<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.

Step 6: Run Local Pre-flight Checks

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

Step 7: Push Branch

bash

git push -u origin <branch-name>

Step 8: Create 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>}

Step 9: Monitor 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

# List workflow runs for this 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
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"}

Step 10: Handle CI Results

If CI Passes:

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

If CI Fails:

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.

Step 11: Final Report

Mark main PR task as completed.

Call

TaskList

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

markdown

## PR Ready for Review

**PR:** [#<number> <title>](<url>)
**Branch:** `<branch-name>` -> `<base-branch>`
**Commits:** <count>
**CI Status:** All checks passed

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

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

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.

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

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.

pr-create

NPX Install

Tags

SKILL.md Content

PR Creator Skill

Task List Integration

Task Hierarchy

Process

Step 1: Assess Current State

Step 2: Create Branch (if needed)

Step 3: Stage and Commit Changes (if needed)

Step 4: Sync with Base Branch (if needed)

Step 5: Draft PR Title and Body

Step 6: Run Local Pre-flight Checks

Step 7: Push Branch

Step 8: Create Pull Request

Step 9: Monitor CI

Step 10: Handle CI Results

If CI Passes:

If CI Fails:

Step 11: Final Report

Session Recovery

Important Rules

Error Handling