PR Creator Skill

You are a developer preparing changes for review. Your job is to commit changes, create a PR, monitor CI, fix any failures, and notify the user when the PR is ready for merge.

Task List Integration

CRITICAL: This skill uses Claude Code's task list system for progress tracking and session recovery. You MUST use TaskCreate, TaskUpdate, and TaskList tools throughout execution.

Why Task Lists Matter Here

CI run tracking: Each CI attempt becomes a task with pass/fail status
Fix iteration visibility: User sees "CI Run #3: fixing lint errors"
Session recovery: If interrupted during CI monitoring, resume watching the same run
Audit trail: Track all fixes made across multiple CI iterations

Task Hierarchy

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

Session Recovery Check

At the start of this skill, always check for existing tasks:

1. Call TaskList to check for existing PR tasks
2. If a "Create PR" task exists with status in_progress:
   - Check its metadata for PR URL and current CI run ID
   - Resume monitoring that CI run
3. If CI tasks exist, check their status to understand current state
4. If no tasks exist, proceed with fresh execution

Process

Step 1: Check Git Status

Create the main PR task:

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

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

Run these commands to understand the current state:

bash

git status
git diff --stat
git log --oneline -5

Verify before proceeding:

There are changes to commit (staged or unstaged)
You're on a feature branch (not main/master) OR need to create one
The branch is not already ahead with unpushed commits that have a PR

If no changes exist:

Inform the user: "No changes detected. Nothing to commit."
Mark task as completed with metadata indicating no changes
Stop here.

Update task with branch info:

TaskUpdate:
- taskId: [pr task ID]
- subject: "Create PR: [actual-branch-name]"
- metadata: {"branch": "[branch-name]", "changesDetected": true}

Step 2: Create Branch (if needed)

If currently on main/master:

bash

git checkout -b <descriptive-branch-name>

Branch naming convention:

```
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

bash

# Stage all changes
git add -A

# Review what's staged
git diff --cached --stat

# Create commit with descriptive message
git commit -m "$(cat <<'EOF'
<type>: <short summary>

<optional longer description>
EOF
)"

Commit message guidelines:

Use conventional commits:
```
feat:
```
,
```
fix:
```
,
```
refactor:
```
,
```
docs:
```
,
```
test:
```
,
```
chore:
```
First line: 50 chars max, imperative mood
Body: wrap at 72 chars, explain what and why

Step 4: Push Branch

bash

git push -u origin <branch-name>

Step 5: Create Pull Request

bash

gh pr create --title "<title>" --body "$(cat <<'EOF'
## Summary
<1-3 bullet points describing what this PR does>

## Changes
<list of key changes>

## Test Plan
<how to verify this works>
EOF
)"

Capture the PR URL from the output and store in task metadata:

TaskUpdate:
- taskId: [pr task ID]
- metadata: {
    "prUrl": "https://github.com/owner/repo/pull/123",
    "prNumber": 123,
    "prTitle": "[title]",
    "commits": [count]
  }

Step 6: Monitor CI

Create a CI run task for tracking:

TaskCreate:
- subject: "CI Run #[N]: monitoring"
- description: |
    Monitoring CI run for PR #[number]
    Run ID: [run-id]
    Started: [timestamp]
- activeForm: "Monitoring CI Run #[N]"

TaskUpdate:
- taskId: [ci task ID]
- addBlockedBy: [pr task ID]  # Links CI run to main PR task
- 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 (blocking)
gh run watch <run-id>

# Or check status without blocking
gh run view <run-id>

Poll every 30-60 seconds until CI completes.

Store run ID in task for session recovery:

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

Step 7: Handle CI Results

If CI Passes:

Update CI task as passed:

TaskUpdate:
- taskId: [ci task ID]
- subject: "CI Run #[N]: passed ✅"
- status: "completed"
- metadata: {"runId": "[run-id]", "status": "passed", "completedAt": "[timestamp]"}

Update main PR task:

TaskUpdate:
- taskId: [pr task ID]
- metadata: {"ciStatus": "passed", "ciRunCount": [N]}

STOP HERE - do not merge

Report to user:

✅ PR is ready for review!

**PR:** <url>
**Branch:** <branch-name>
**CI Status:** All checks passed

The PR is ready to be reviewed and merged.

If CI Fails:

Update CI task as failed:

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

Get failure details:
bash
```
gh run view <run-id> --log-failed
```
Analyze the failure:
- Identify which job/step failed
- Read the error message
- Determine the fix

Create a fix task:

TaskCreate:
- subject: "Fix: [failure reason]"
- description: |
    Fixing CI failure from Run #[N]
    Failure: [detailed error]
    Files to modify: [list if known]
- activeForm: "Fixing [failure reason]"

TaskUpdate:
- taskId: [fix task ID]
- addBlockedBy: [ci task ID]  # Links fix to the failed CI run
- status: "in_progress"

Fix the issue:
- Make necessary code changes
- Stage and commit the fix:
  bash
```
git add -A
git commit -m "fix: <what was fixed>"
git push
```

Mark fix task as completed:

TaskUpdate:
- taskId: [fix task ID]
- status: "completed"
- metadata: {"filesModified": ["file1.ts", "file2.ts"], "commitHash": "[hash]"}

Return to Step 6 - monitor the new CI run (increment run number)

Repeat until CI passes.

Step 8: Final Report

Mark main PR task as completed:

TaskUpdate:
- taskId: [pr task ID]
- status: "completed"
- metadata: {
    "prUrl": "[url]",
    "prNumber": [number],
    "branch": "[branch-name]",
    "ciStatus": "passed",
    "ciRunCount": [N],
    "merged": false
  }

Generate report from task data:

Call

TaskList

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

markdown

## PR Ready for Review

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

### Changes Included
- <change 1>
- <change 2>

### CI Runs
[Generated from CI run tasks:]
- Run #1: ❌ Failed (lint errors) → Fixed in commit [hash]
- Run #2: ❌ Failed (test failures) → Fixed in commit [hash]
- Run #3: ✅ Passed

### Fixes Applied
[Generated from fix tasks:]
- Fix: lint errors - modified [files]
- Fix: test failures - modified [files]

### Next Steps
1. Request review from team
2. Address any review feedback
3. Merge when approved

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

Session Recovery

If resuming from an interrupted session:

Recovery decision tree:

TaskList shows:
├── PR task in_progress, no CI tasks
│   └── PR was created, start monitoring CI (Step 6)
├── 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 7)
├── 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)

Resuming CI monitoring:

1. Get runId from latest CI task metadata
2. Check if run is still active: gh run view <runId>
3. If still running, continue monitoring
4. If completed, process result (Step 7)
5. If new run started, create new CI task and monitor that

Always inform user when resuming:

Resuming PR creation session:
- PR: [url from task metadata]
- Branch: [branch from task metadata]
- CI Runs: [count] attempts
- Current state: [in_progress task description]
- Resuming: [next action]

Important Rules

NEVER merge the PR - only create it and ensure CI passes
NEVER force push unless explicitly asked
NEVER push to main/master directly
Continue fixing until CI passes - don't give up after one failure
Preserve commit history - don't squash unless asked

Error Handling

Authentication issues:

bash

gh auth status

If not authenticated, inform user to run

gh auth login

Branch conflicts:

bash

git fetch origin main
git rebase origin/main
# or
git merge origin/main

Resolve conflicts if any, then continue.

PR already exists:

bash

gh pr view --web

Inform user a PR already exists for this branch.

CI Debugging Tips

Common failures and fixes:

Failure	Likely Cause	Fix
Lint errors	Code style violations	Run `npm run lint -- --fix` or equivalent
Type errors	TypeScript issues	Fix type annotations
Test failures	Broken tests	Fix tests or update snapshots
Build failures	Compilation errors	Fix syntax/import errors
Timeout	Slow tests	Optimize or increase timeout

Read the logs carefully - the error message usually tells you exactly what's wrong.

pr-creator

NPX Install

Tags

SKILL.md Content

PR Creator Skill

Task List Integration

Why Task Lists Matter Here

Task Hierarchy

Session Recovery Check

Process

Step 1: Check Git Status

Step 2: Create Branch (if needed)

Step 3: Stage and Commit Changes

Step 4: Push Branch

Step 5: Create Pull Request

Step 6: Monitor CI

Step 7: Handle CI Results

If CI Passes:

If CI Fails:

Step 8: Final Report

Session Recovery

Important Rules

Error Handling

CI Debugging Tips