Non-negotiable rules:
- Read the full diff against the real base branch before drafting the PR.
- Block on protected-branch usage, empty branch state, or conflict markers.
- If uncommitted changes exist, invoke
commit first instead of creating a misleading PR.
- Push the branch before creating the PR.
- Keep PR creation user-driven. If title, scope, base, or reviewer intent is ambiguous, ask first.
Create PR
Inputs
$request: Optional PR guidance such as draft intent, reviewer hints, base branch, labels, or title direction
Goal
Create a PR that matches the actual branch changes and leaves the user with:
- a correct base branch
- an accurate title
- a useful body
- a pushed branch
- a verified PR URL and state
Step 0: Confirm this is an explicit PR request
This skill is user-only.
Use it only when the user explicitly asks to create or open a PR.
If the request is really:
- code review only, route to a review skill
- commit creation only, route to
commit
- planning only, route to the planner
If reviewer assignment, labels, milestone, or base branch are ambiguous and matter to the request, use AskUserQuestion.
Success criteria: PR creation is explicitly requested and the intended PR shape is clear enough to proceed.
Step 1: Gather real branch context
Inspect the current branch before drafting anything:
- current branch name
- branch tracking state
- uncommitted changes
- base branch candidates
- commits ahead of base
- full diff against base
Rules:
- read the actual diff, not just commit messages
- determine the real base branch before classifying the PR
- use
Read on changed files when the diff summary is not enough to understand the change
Load references/pr-conventions.md for base-branch selection and PR classification heuristics when needed.
Success criteria: You know the branch, base, diff shape, and whether the branch is actually PR-ready.
Step 2: Validate branch readiness
Blockers:
- on
main, master, or develop
- no commits relative to base
- conflict markers in changed files
If uncommitted changes exist:
- invoke the
commit skill
- then re-run branch context gathering before continuing
Warnings:
- type or lint failures are warnings unless the user wants to stop and fix them first
- breaking changes are not blockers, but they must be documented
Success criteria: The branch is in a state where a PR can be created honestly.
Step 3: Classify the PR from the actual diff
Determine:
- type
- scope
- size
- risk
- whether breaking changes exist
Use:
- branch name as a hint, not truth
- changed paths and modules
- commit messages only as supporting context
- the full diff as the source of truth
Document breaking changes if any of these exist:
- removed or renamed public exports
- route or API contract changes
- schema or migration changes
- env var changes
- major dependency changes
Load references/pr-conventions.md for:
- classification heuristics
- title rules
- option flag mapping
- blocking versus warning behavior
Success criteria: The PR is classified from the real code changes, not just branch naming.
Step 4: Run the narrowest relevant quality checks
Run checks that fit the changed surface and project tooling.
Typical checks:
- typecheck
- lint
- conflict-marker scan
Rules:
- conflict markers always block
- other failures should be surfaced honestly to the user
- do not fabricate passing status in the PR body
- if the user asks to proceed with known non-blocking issues, say so explicitly in the final report
Success criteria: The PR reflects the actual readiness state of the branch.
Step 5: Draft the PR title and body
Create:
- a Conventional Commit-style PR title
- a body that explains what changed and how to review it
The body should cover:
- summary
- grouped change areas
- breaking changes when present
- specific test plan
- optional notes for deployment, config, or dependency changes
Use:
references/pr-conventions.md for title and readiness rules
references/pr-body-examples.md only when you need example body shape
If the user explicitly provided title guidance, use it if it still matches the actual diff.
Success criteria: The title and body describe the full branch accurately and are reviewable.
Step 6: Push the branch and create the PR
Before creation:
- ensure the branch is pushed
- ensure upstream is set if needed
Then create the PR with gh pr create.
Support request-driven options such as:
- draft
- reviewer
- assignee
- label
- milestone
Rules:
- do not create the PR before the branch exists on remote
- prefer
gh over manual API calls
- if
gh is unavailable, stop and provide the user with the prepared title, body, and compare URL
Success criteria: The PR exists remotely or the user has the exact fallback material needed to create it manually.
Step 7: Verify and report
After creation, verify:
- PR number
- URL
- title
- state
- draft status
- base branch
Also report:
- whether uncommitted changes remain
- whether the branch is ahead of remote
- whether any warnings were carried into the PR process
Success criteria: The user knows exactly what PR was created and any remaining branch caveats.
Guardrails
- Do not create PRs proactively.
- Do not let the model invoke this skill through SkillTool; this workflow is intentionally user-only.
- Do not add
paths:. This is a generic workflow skill.
- Do not add
context: fork. PR state must stay in the active workspace.
- Do not keep giant readiness checklists, scorecards, or failure catalogs inline in
SKILL.md.
- Do not fabricate test status, branch status, or breaking-change absence.
When To Load References
references/pr-conventions.md
Use for base-branch selection, classification heuristics, option parsing, and blocking rules.
references/pr-body-examples.md
Use only when you need an example PR body shape for a similar request.
Output Contract
Report:
- PR number, URL, title, base, and state
- whether
commit had to be invoked first
- the checks run and any warnings that remained
- any breaking changes documented
- remaining working-tree or branch state
1---
2name: create-pr
3version: 2.0.0
4description: |
5 Open a GitHub pull request that matches what the branch ACTUALLY changed — validated against the
6 real base, not the branch name or an optimistic summary. Reads the full diff against the true base
7 branch, blocks on protected-branch/empty-branch/conflict-marker states, invokes `commit` first if
8 the tree is dirty, classifies type/scope/breaking-changes from the diff, runs the narrowest
9 relevant checks, pushes the branch, then creates the PR with `gh` and verifies its number, URL, and
10 state. Never fabricates passing test status or an absent breaking change, and never creates the PR
11 before the branch is on remote; falls back to a prepared title/body/compare URL if `gh` is missing.
12 Use only when the user explicitly asks to open or create a PR.
13allowed-tools:
14 - AskUserQuestion
15 - Bash
16 - Read
17 - Glob
18 - Grep
19 - Skill
20disable-model-invocation: true
21user-invocable: true
22argument-hint: "[PR guidance]"
23arguments:
24 - request
25when_to_use: |
26 Use only when the user explicitly asks to create or open a pull request — "create PR", "/pr",
27 "open a draft PR", "push and make a PR". Do NOT use to only build a commit (commit) or for branch
28 review only; keep it explicit-user-only and confirm first when title, base, scope, or reviewer
29 intent is ambiguous.
30metadata:
31 source: https://skillmd.com/skills/ulpi-io/create-pr
32---
33
34<EXTREMELY-IMPORTANT>
35This skill mutates remote collaboration state and must stay explicit.
36
37Non-negotiable rules:
381. Read the full diff against the real base branch before drafting the PR.
392. Block on protected-branch usage, empty branch state, or conflict markers.
403. If uncommitted changes exist, invoke `commit` first instead of creating a misleading PR.
414. Push the branch before creating the PR.
425. Keep PR creation user-driven. If title, scope, base, or reviewer intent is ambiguous, ask first.
43</EXTREMELY-IMPORTANT>
44
45# Create PR
46
47## Inputs
48
49- `$request`: Optional PR guidance such as draft intent, reviewer hints, base branch, labels, or title direction
50
51## Goal
52
53Create a PR that matches the actual branch changes and leaves the user with:
54
55- a correct base branch
56- an accurate title
57- a useful body
58- a pushed branch
59- a verified PR URL and state
60
61## Step 0: Confirm this is an explicit PR request
62
63This skill is user-only.
64
65Use it only when the user explicitly asks to create or open a PR.
66
67If the request is really:
68
69- code review only, route to a review skill
70- commit creation only, route to `commit`
71- planning only, route to the planner
72
73If reviewer assignment, labels, milestone, or base branch are ambiguous and matter to the request, use `AskUserQuestion`.
74
75**Success criteria**: PR creation is explicitly requested and the intended PR shape is clear enough to proceed.
76
77## Step 1: Gather real branch context
78
79Inspect the current branch before drafting anything:
80
81- current branch name
82- branch tracking state
83- uncommitted changes
84- base branch candidates
85- commits ahead of base
86- full diff against base
87
88Rules:
89
90- read the actual diff, not just commit messages
91- determine the real base branch before classifying the PR
92- use `Read` on changed files when the diff summary is not enough to understand the change
93
94Load `references/pr-conventions.md` for base-branch selection and PR classification heuristics when needed.
95
96**Success criteria**: You know the branch, base, diff shape, and whether the branch is actually PR-ready.
97
98## Step 2: Validate branch readiness
99
100Blockers:
101
102- on `main`, `master`, or `develop`
103- no commits relative to base
104- conflict markers in changed files
105
106If uncommitted changes exist:
107
108- invoke the `commit` skill
109- then re-run branch context gathering before continuing
110
111Warnings:
112
113- type or lint failures are warnings unless the user wants to stop and fix them first
114- breaking changes are not blockers, but they must be documented
115
116**Success criteria**: The branch is in a state where a PR can be created honestly.
117
118## Step 3: Classify the PR from the actual diff
119
120Determine:
121
122- type
123- scope
124- size
125- risk
126- whether breaking changes exist
127
128Use:
129
130- branch name as a hint, not truth
131- changed paths and modules
132- commit messages only as supporting context
133- the full diff as the source of truth
134
135Document breaking changes if any of these exist:
136
137- removed or renamed public exports
138- route or API contract changes
139- schema or migration changes
140- env var changes
141- major dependency changes
142
143Load `references/pr-conventions.md` for:
144
145- classification heuristics
146- title rules
147- option flag mapping
148- blocking versus warning behavior
149
150**Success criteria**: The PR is classified from the real code changes, not just branch naming.
151
152## Step 4: Run the narrowest relevant quality checks
153
154Run checks that fit the changed surface and project tooling.
155
156Typical checks:
157
158- typecheck
159- lint
160- conflict-marker scan
161
162Rules:
163
164- conflict markers always block
165- other failures should be surfaced honestly to the user
166- do not fabricate passing status in the PR body
167- if the user asks to proceed with known non-blocking issues, say so explicitly in the final report
168
169**Success criteria**: The PR reflects the actual readiness state of the branch.
170
171## Step 5: Draft the PR title and body
172
173Create:
174
175- a Conventional Commit-style PR title
176- a body that explains what changed and how to review it
177
178The body should cover:
179
180- summary
181- grouped change areas
182- breaking changes when present
183- specific test plan
184- optional notes for deployment, config, or dependency changes
185
186Use:
187
188- `references/pr-conventions.md` for title and readiness rules
189- `references/pr-body-examples.md` only when you need example body shape
190
191If the user explicitly provided title guidance, use it if it still matches the actual diff.
192
193**Success criteria**: The title and body describe the full branch accurately and are reviewable.
194
195## Step 6: Push the branch and create the PR
196
197Before creation:
198
199- ensure the branch is pushed
200- ensure upstream is set if needed
201
202Then create the PR with `gh pr create`.
203
204Support request-driven options such as:
205
206- draft
207- reviewer
208- assignee
209- label
210- milestone
211
212Rules:
213
214- do not create the PR before the branch exists on remote
215- prefer `gh` over manual API calls
216- if `gh` is unavailable, stop and provide the user with the prepared title, body, and compare URL
217
218**Success criteria**: The PR exists remotely or the user has the exact fallback material needed to create it manually.
219
220## Step 7: Verify and report
221
222After creation, verify:
223
224- PR number
225- URL
226- title
227- state
228- draft status
229- base branch
230
231Also report:
232
233- whether uncommitted changes remain
234- whether the branch is ahead of remote
235- whether any warnings were carried into the PR process
236
237**Success criteria**: The user knows exactly what PR was created and any remaining branch caveats.
238
239## Guardrails
240
241- Do not create PRs proactively.
242- Do not let the model invoke this skill through SkillTool; this workflow is intentionally user-only.
243- Do not add `paths:`. This is a generic workflow skill.
244- Do not add `context: fork`. PR state must stay in the active workspace.
245- Do not keep giant readiness checklists, scorecards, or failure catalogs inline in `SKILL.md`.
246- Do not fabricate test status, branch status, or breaking-change absence.
247
248## When To Load References
249
250- `references/pr-conventions.md`
251 Use for base-branch selection, classification heuristics, option parsing, and blocking rules.
252- `references/pr-body-examples.md`
253 Use only when you need an example PR body shape for a similar request.
254
255## Output Contract
256
257Report:
258
2591. PR number, URL, title, base, and state
2602. whether `commit` had to be invoked first
2613. the checks run and any warnings that remained
2624. any breaking changes documented
2635. remaining working-tree or branch state