home / skills / windmill-labs / windmill / pr

pr skill

safe

This skill helps you open a draft pull request on GitHub by analyzing changes, ensuring up-to-date commits, and drafting clear PR details.

npx playbooks add skill windmill-labs/windmill --skill pr

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.0 KB

---
name: pr
user_invocable: true
description: Open a draft pull request on GitHub. MUST use when you want to create/open a PR.
---

# Pull Request Skill

Create a draft pull request with a clear title and explicit description of changes.

## Instructions

1. **Analyze branch changes**: Understand all commits since diverging from main
2. **Push to remote**: Ensure all commits are pushed
3. **Create draft PR**: Always open as draft for review before merging

## PR Title Format

Follow conventional commit format for the PR title:
```
<type>: <description>
```

### Types
- `feat`: New feature or capability
- `fix`: Bug fix
- `refactor`: Code restructuring
- `docs`: Documentation changes
- `chore`: Maintenance tasks
- `perf`: Performance improvements

### Title Rules
- Keep under 70 characters
- Use lowercase, imperative mood
- No period at the end

## PR Body Format

The body MUST be explicit about what changed. Structure:

```markdown
## Summary
<Clear description of what this PR does and why>

## Changes
- <Specific change 1>
- <Specific change 2>
- <Specific change 3>

## Test plan
- [ ] <How to verify change 1>
- [ ] <How to verify change 2>

---
Generated with [Claude Code](https://claude.com/claude-code)
```

## Execution Steps

1. Run `git status` to check for uncommitted changes
2. Run `git log main..HEAD --oneline` to see all commits in this branch
3. Run `git diff main...HEAD` to see the full diff against main
4. Check if remote branch exists and is up to date:
   ```bash
   git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo "no upstream"
   ```
5. Push to remote if needed: `git push -u origin HEAD`
6. Create draft PR using gh CLI:
   ```bash
   gh pr create --draft --title "<type>: <description>" --body "$(cat <<'EOF'
   ## Summary
   <description>

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

   ## Test plan
   - [ ] <test 1>
   - [ ] <test 2>

   ---
   Generated with [Claude Code](https://claude.com/claude-code)
   EOF
   )"
   ```
7. Return the PR URL to the user

Overview

This skill opens a draft pull request on GitHub for the current branch, ensuring your changes are reviewed before merging. It enforces a conventional commit-style title and a structured body that documents summary, concrete changes, and a test plan. Use this skill whenever you intend to create or open a PR for review.

How this skill works

The skill inspects the branch commits and diffs against main, checks that the branch is pushed to the remote, and then creates a draft PR using the GitHub CLI. It prompts or accepts a conventional commit-style title and a clear, itemized PR body that includes Summary, Changes, and Test plan sections. Finally, it returns the created PR URL.

When to use it

When you want to open a pull request for review before merging (always as a draft)
After finishing a feature, bugfix, refactor, docs, chore, or perf change
When you need a clear, standardized PR description for reviewers
Before merging to ensure tests and reviews are tracked

Best practices

Use a conventional commit format for the title: <type>: <description> (feat, fix, refactor, docs, chore, perf)
Keep the title under 70 characters, lowercase, imperative, and no trailing period
Ensure all local commits are pushed to the remote branch before creating the PR
Include a short Summary, specific bulletized Changes, and a verifiable Test plan in the body
Open as draft so reviewers can comment before merging; convert to ready when approved

Example use cases

Opening a draft PR for a new API endpoint: feat: add payments webhook
Submitting a bugfix branch for review: fix: handle nil pointer in worker
Creating a documentation update PR: docs: update onboarding guide
Proposing a refactor for code cleanup: refactor: decouple auth module

FAQ

What CLI does this use to create the PR?

It uses the GitHub CLI (gh) to create a draft pull request and returns the PR URL.

What checks are performed before creating the PR?

It inspects commits since main, shows the diff against main, verifies the branch has an upstream, and ensures commits are pushed before creating the draft PR.