| name | create-pr |
| description | Create or update a Pull Request with AI-generated description, mermaid diagram, file walkthrough, and automatic SDD spec detection. Uses templates/pr-body.md for structure. |
| when_to_use | When the user says "open a PR", "create pull request", "push this as a PR",
"open PR against main", "update my PR description", "--update <number>",
or wants to ship a completed feature branch with a rich description.
|
| disable-model-invocation | true |
| argument-hint | [base-branch] | --update <pr-number> |
| allowed-tools | Bash(git:*), Bash(gh:*), Read |
Create PR Skill
Generate and create/update a comprehensive PR using the shared body template.
Mode detection
Parse $ARGUMENTS:
- Starts with
--update or -u followed by a number → Update Mode on that PR.
- Anything else → Create Mode (argument is the base branch; default
main).
Create Mode
1. Gather diff information (parallel)
git log origin/${BASE:-main}..HEAD --oneline
git diff origin/${BASE:-main}...HEAD --stat
git diff origin/${BASE:-main}...HEAD
2. Detect spec context
Changed paths → spec type:
| Path pattern | Spec type |
|---|
infrastructure/base/crossplane/configuration/kcl/**/*.k, *-composition.yaml | composition |
opentofu/**/*.tf, terramate.tm.hcl | infrastructure |
*networkpolicy*, *rbac*, openbao/**, *cilium*policy* | security |
| Multiple top-level dirs + HelmRelease/Kustomization | platform |
Find the spec directory for these changes (if one exists). The repo uses the 3-artifact structure (spec.md, plan.md, clarifications.md) so any of those files in the diff signals a spec:
git diff origin/${BASE:-main}...HEAD --name-only \
| grep -oE 'docs/specs/[0-9]+-[a-z0-9-]+' | sort -u | head -1
For each detected spec directory, also note which artifacts changed (spec.md / plan.md / clarifications.md). Include them as bullet points under the Specification block:
## 📋 Specification
Implements [#<issue>](../issues/<issue>) — see [`<spec-dir>/`](../blob/main/<spec-dir>/).
Artifacts touched in this PR:
- `spec.md` (contract — should usually be unchanged after approval)
- `plan.md` (design + tasks + review checklist)
- `clarifications.md` (CL-N entries appended)
If spec.md itself changed in a non-frozen way (i.e., this PR isn't the spec-creation PR), surface a warning — modifying the contract mid-implementation usually indicates scope creep that should be a follow-up spec.
If changes look spec-worthy but no spec directory exists, include the Spec Recommendation warning block from the template.
3. Render the PR body
Fill the template in templates/pr-body.md. Apply the mermaid styling from references/mermaid-styles.md. Keep title < 70 chars. Drop sections that do not apply (no empty stubs).
4. Create the PR
git push -u origin "$(git branch --show-current)"
gh pr create --base "${BASE:-main}" --title "<title>" --body "$BODY"
5. Output
Return only the PR URL.
Update Mode
gh pr view "$PR_NUMBER" --json number,title,files,additions,deletions,baseRefName,body
gh pr diff "$PR_NUMBER"
Generate a fresh body using the same template. Update:
gh pr edit "$PR_NUMBER" --body "$BODY"
Return Updated PR #<N>: <url>.
Content rules
- Title: conventional prefix (
feat(crossplane): ...), under 70 chars.
- Summary: WHY, not WHAT. The file table shows WHAT.
- Auto-detect spec directory by scanning
docs/specs/NNN-* in the diff. Preserve existing references on update.
- Never skip hooks, never force-push without explicit user direction.
Related skills
/spec — create the spec this PR references/commit — commit with pre-commit validation before creating PR/improve-pr <number> — security + quality review after PR exists
Supporting files
