agent-pr-creator

gh pr create

Workflow

Step 1: Gather Context

# Detect base branch (main or develop)
git rev-parse --verify develop 2>/dev/null && echo "develop" || echo "main"

# Get changed files
git diff <base>...HEAD --name-only

# Get commit history since branching
git log --oneline <base>..HEAD

# Get diff stats
git diff <base>...HEAD --stat

# Check if PR already exists
gh pr list --head $(git branch --show-current)

Step 2: Read the Template

.github/PULL_REQUEST_TEMPLATE.md

.github/

Step 3: Fill the Template

📝 Description

• Analyze the diff and commits to write a clear summary of what changed and why.
• Focus on business value, not implementation details.
• Group changes logically if multiple areas were modified.
• Reference Linear/issue IDs from branch name or commits if present (e.g.,

  PUL3-34

  ).

🔧 Type of Change

• Match commit prefixes to types:

  feat

  → New feature,

  fix

  → Bug fix,

  refactor

  → Refactoring,

  test

  → Test changes,

  docs

  → Documentation,

  chore

  /

  build

  → Build/Config.
• Use

  [x]

  to check matching boxes,

  [ ]

  for the rest.
• Multiple types can be checked.
• Use the exact checkbox labels from the template — do not rewrite them.

💥 Breaking Changes

• Analyze if any of these changed: public API contracts, database schemas, environment variables, config file formats, removed exports.
• If yes: check Yes and explain what breaks + migration steps.
• If no: check No.

📸 Screenshots / Videos

• If changes touch

  client/components/

  or UI files, add:

  <!-- Please attach screenshots for UI changes -->

  .
• Otherwise:

  N/A — No UI changes.

📋 Additional Notes

• Mention deployment steps if needed.
• Mention dependencies on other PRs or services.
• Add reviewer instructions if the changes require specific testing.
• If nothing special:

  N/A

  .

Step 4: Create the PR

gh pr create

gh pr create --base <base-branch> --title "<type>: <short description>" --body "<filled template>"

• Use conventional commit prefix:

  feat:

  ,

  fix:

  ,

  refactor:

  ,

  docs:

  ,

  chore:

  .
• Keep under 70 characters.
• Use imperative mood ("add", "update", "fix" — not "added", "updates", "fixes").

• Use a HEREDOC for the body to preserve markdown formatting.
• Include all sections from the template, filled in.
• Preserve the

  ---

  separators from the template.

Step 5: Confirm

1. The PR URL.
2. A brief summary of what was included.

Important

• NEVER create a PR if there are uncommitted changes — warn the user first.
• NEVER push if the branch is behind the remote — warn the user.
• If the branch has no remote tracking, push with

  -u

  before creating the PR.
• Always use the project's actual template structure, not a generic one.

Examples

Positive Trigger

agent-pr-creator

gh pr create

agent-pr-creator

agent-pr-creator

Non-Trigger

agent-pr-creator

gh pr view

agent-pr-creator

git diff

git log

Troubleshooting

Skill Does Not Trigger

• Error: The skill is not selected when the user asks to create a PR.
• Cause: Request wording does not match the description trigger conditions.
• Solution: Rephrase with explicit PR creation keywords like "create a pull request", "make a PR", or "open a PR" and retry.

PR Template Not Found

• Error: Cannot find

  .github/PULL_REQUEST_TEMPLATE.md

  .
• Cause: Project does not have a PR template, or it's in a non-standard location.
• Solution: Search for template files with

  fd PULL_REQUEST

  or ask the user for the template location. If no template exists, create a basic PR with just title and description.

PR Already Exists

• Error:

  gh pr create

  fails because a PR already exists for this branch.
• Cause: The branch already has an open PR.
• Solution: Inform the user of the existing PR URL and ask if they want to update the description using

  gh pr edit

  instead.

Uncommitted Changes Warning

• Error: Cannot create PR due to uncommitted changes.
• Cause: Working directory has unstaged or uncommitted changes.
• Solution: Warn the user and suggest committing changes first with

  /commit

  , or stashing them before creating the PR.

Missing Remote Tracking Branch

• Error:

  gh pr create

  fails because branch has no upstream.
• Cause: Local branch has never been pushed to remote.
• Solution: Push the branch first with

  git push -u origin <branch-name>

  , then create the PR.