Create Pull Request
Collaborating skills
- Git Commit: skill:
git-commitfor creating well-structured commit messages before opening a PR
Creates GitHub PRs with conventional commit titles and a body that mirrors .github/pull_request_template.md.
PR Title Format
<type>(<scope>): <summary>
Types (required)
| Type | Description |
|---|---|
feat | New feature |
fix | Bug fix |
perf | Performance improvement |
test | Adding/correcting tests |
docs | Documentation only |
refactor | Code change (no bug fix or feature) |
build | Build system or dependencies |
ci | CI configuration |
chore | Routine tasks, maintenance |
Scopes (optional but recommended)
backend— Backend/API (apps/backendorapps/api)web— Frontend (apps/web)types— Shared TypeScript types (packages/types)api— Public API contract (serializers, endpoints)infra— Deployment, Docker, Kamal, CIdocs— Documentation and strategy files
Summary Rules
- Use imperative present tense: "Add" not "Added"
- Capitalize first letter
- No period at the end
- Add
!before:for breaking changes (e.g.feat(api)!: ...)
Steps
-
Check current state:
git status git diff --stat git log origin/main..HEAD --oneline -
Analyze changes to determine:
- Type: What kind of change is this?
- Scope: Which area is affected?
- Summary: What does the change do?
-
Push branch if needed:
git push -u origin HEAD -
Create PR using gh CLI with title and body. If
.github/pull_request_template.mdexists, use it as the PR body instead of the default template:gh pr create --title "<type>(<scope>): <summary>" --body "<body from template>" -
Assign labels by parsing the PR title:
- Extract
<type>from the title - Extract
<scope>if present in parentheses - Check for
!prefix indicating breaking change - Create labels if they don't exist
- Apply labels using
gh pr edit --add-labels
See
references/labels.mdfor the complete implementation script.gh pr create --title "<type>(<scope>): <summary>" --body "$(cat <<'EOF' ## What <Describe the change concisely. What does this PR do and why?> ## Why <What problem does this solve? Link to issue if applicable.> <!-- Closes #123 / Fixes #123 / Resolves #123 --> ## Type of change - [ ] Bug fix - [ ] New feature - [ ] Refactor - [ ] Documentation - [ ] Infrastructure / tooling ## Testing <How was this tested? What cases were covered?> ## Checklist - [ ] Tests pass (`<test command>`) - [ ] No new dependencies introduced without justification - [ ] Breaking changes are documented below (if any) ## Breaking changes <!-- List any breaking API contracts, renamed fields, removed endpoints, or behaviour changes. Leave blank if none. --> EOF )" - Extract
Examples
New feature
feat(auth): Add OAuth2 login support
Bug fix
fix(api): Correct pagination offset calculation
Breaking API change
feat(api)!: Rename response field user_name to username
Infra / tooling
chore(infra): Update Docker base image to node:22-alpine
No scope (affects multiple areas)
chore: Upgrade dependencies and synchronise lockfile
Validation
The PR title must match this pattern:
^(feat|fix|perf|test|docs|refactor|build|ci|chore|revert)(\([a-zA-Z0-9 ]+\))?!?: [A-Z].+[^.]$
Key rules:
- Type must be one of the allowed types
- Scope is optional but must be in parentheses if present
!for breaking changes goes before the colon- Summary must start with a capital letter
- Summary must not end with a period
Labels
After creating the PR, assign labels based on the type and scope extracted from the PR title.
Standard labels to apply:
- Type label (from
<type>(<scope>):):feat,fix,perf,test,docs,refactor,build,ci,chore - Scope label (if scope present): derived from the scope in the PR title
- Special labels:
breaking(if!in title),dependencies(for dependency updates),security(for security fixes)
Create labels if they don't exist. See references/labels.md for complete color mapping and implementation script.
Iron Rule
The agentic coding assistant shall never merge to the main branch — create pull requests only. Never use gh pr merge, git merge, or any command that directly merges to main. Pull requests are for human review and merging.