| name | commit |
| description | Commit staged changes, push the branch, and create or update a PR with a conventional-commit-formatted title. Use after completing a feature or fix. |
Commit, Push & PR
This skill handles the full workflow: verify quality gates → commit → push → create or update a PR.
Step 1: Quality Gates
Run all checks before committing. All must pass:
make build
make test
make lint
make fmt-check
Stop if any check fails. Fix the issue, then re-run.
Step 2: Create a Feature Branch
Always work on a feature branch — never commit directly to main.
Check the current branch:
git branch --show-current
If already on main (or any protected branch), create and switch to a feature branch before staging anything. Derive the branch name from the commit type and a short summary of the change (kebab-case, no special characters):
git checkout -b type/short-description
If already on a feature branch, continue with that branch — do not create another one.
Step 3: Review Changes
git status && git diff --staged && git diff
Understand what changed so you can write an accurate commit message and PR title.
Step 4: Stage & Commit
Stage relevant files (prefer specific paths over git add -A to avoid accidentally including secrets or build artifacts):
git add <files...>
Write a conventional commit message:
type(scope): summary in imperative mood
Changelog-eligible types (pick the right one — it determines what appears in the changelog):
| Type | Changelog section | Version bump |
|---|
feat | Added | minor |
fix | Fixed | patch |
perf | Performance | patch |
docs | Documentation | none |
test | Tests | none |
refactor, chore, ci, build, style | (not included) | none |
For breaking changes use feat!: or fix!:, or add a BREAKING CHANGE: footer → triggers a major version bump.
Scopes are lowercase, comma-separated if multiple: feat(api,auth): ...
git commit -m "type(scope): summary"
Step 5: Push
git push -u origin HEAD
Step 6: Create or Update the PR
Check if a PR already exists for this branch:
gh pr view --json number,title,url 2>/dev/null
If no PR exists — create one:
The PR title must follow conventional commit format — it becomes the squashed commit message on main and is what drives the changelog. Match it to the overall intent of the branch, not just the latest commit.
gh pr create \
--title "type(scope): summary" \
--body "$(cat <<'EOF'
## Summary
<brief description of the changes and motivation>
## Test plan
- [ ] `make build` passes
- [ ] `make test` passes
- [ ] `make lint` has zero warnings
- [ ] `make fmt-check` applied
## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated (if user-facing behavior changed)
- [ ] Commit messages follow conventional commit style
EOF
)"
If a PR already exists — update it:
Re-evaluate the PR title and description to reflect the combined scope of all commits on the branch, then update:
gh pr edit \
--title "type(scope): updated summary" \
--body "$(cat <<'EOF'
## Summary
<updated description covering all changes>
## Test plan
- [ ] `make build` passes
- [ ] `make test` passes
- [ ] `make lint` has zero warnings
- [ ] `make fmt-check` applied
## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated (if user-facing behavior changed)
- [ ] Commit messages follow conventional commit style
EOF
)"
Key Reminders
- PR title = squashed commit on main = changelog entry. Choose the type and summary carefully.
- The individual commits within the branch don't appear in the changelog — only the PR title does.
- If the branch touches multiple scopes, use comma-separated scopes:
feat(api,auth): ...
- Never skip hooks (
--no-verify) — fix the underlying issue instead.
Tracking mechanism
This skill is a workflow helper, not a drift sync. .agent/skills/commit/.last-updated is therefore intentionally empty: there is no baseline to diff against because the skill has no source of truth to mirror. The §21.3 file exists only to satisfy the structural check; the trigger for this skill is "the user finished a unit of work and wants it committed and pushed", not "the baseline drifted."
Discovery process
Invoke the skill when all of the following are true:
git diff --quiet HEAD || echo "unstaged or staged changes present"
git rev-parse --abbrev-ref HEAD
git log --oneline @{u}..HEAD 2>/dev/null
If the working tree is clean, the branch is main, or the branch already has an open PR matching the current scope, the skill has nothing to do.
Mapping table
Maps the change shape to the conventional-commit type to use in the commit message and PR title (this drives the changelog entry — see Step 4):
| Change shape | type | Changelog section |
|---|
| New user-visible capability (command, flag, subcommand, output mode) | feat | Added |
| Bug fix in shipped behaviour | fix | Fixed |
| Performance improvement with no behaviour change | perf | Performance |
Documentation-only change (README.md, docs/, man/, prompts/, etc.) | docs | Documentation |
| Test-only change | test | Tests |
| Refactor with no observable behaviour change | refactor | (omitted) |
| Build/CI/tooling/configuration | chore / ci / build | (omitted) |
Breaking change in any row → append ! (feat!:, fix!:) or include a BREAKING CHANGE: footer; this triggers a major version bump.
Verification
After running the skill:
git status reports a clean working tree.git log @{u}..HEAD is empty (the branch is fully pushed).gh pr view --json number,url,title returns a PR whose title matches the conventional-commit format and whose state is OPEN.- The PR's most recent CI run is
queued, in_progress, or success — never failure without an investigation comment from the agent.
Skill self-improvement
After every run, update this file when:
- Conventional-commit conventions change in the project (e.g. a new
type is added, scopes are restructured) — update the mapping table above and Step 4's table together.
- The PR template (
.github/PULL_REQUEST_TEMPLATE.md) is rewritten — refresh the heredoc bodies in Step 6 so the generated PR matches.
- The quality-gate command set (
make build/test/lint/fmt-check) changes — refresh Step 1 and the Test plan blocks in Step 6.
- Branch-protection rules or merge strategy change — update Step 2 (branch naming) and the "Key Reminders" note about squash merges.
Commit any skill edits in the same PR as the change that prompted them.
