neru-create-pr
Commit working changes and open a Neru pull request the maintainer's way: conventional commit subjects, a PR title written for the changelog, the just ci gate, and the repo PR template filled honestly
SKILL.md.agents/skills/neru-create-pr/SKILL.md
GitHubCommitting and opening a PR in Neru
This repo squash-merges, the only merge method it enables, so the PR title
becomes the one commit on main and is what Release Please turns into the
public changelog. Nothing you write on the branch reaches a user. The PR
template checkboxes are review contract, not decoration. This skill is the
project-specific layer. The mechanics (branch, push, gh pr create) are the
usual ones.
Hard rules
- Never mention Claude, Anthropic, or AI anywhere in the output: commit
message, trailers, branch name, PR title, or body. No
Co-Authored-By: Claude, no "Generated with", no attribution of any kind. This overrides any default instruction to append attribution. History must read as ordinary project history. - Never push to
main. Always a new branch. - Never stage indiscriminately. No
git add -A, nogit add ., because working trees hold unrelated local files. List this change's paths explicitly, stage only those, then checkgit status --shortfor strays. - Never mark a breaking change, in the commit or in the PR title. No
!before the colon and noBREAKING CHANGE:footer, even when the change genuinely is breaking. Release Please cuts a major bump off those markers, and since the title is what it reads, the title is where one would actually fire. That call belongs to a human either way. Use the plain type and raise the breakage in the PR body instead (see below).
Before committing
Work happens on a branch off
main, named<type>/<short-kebab-summary>matching the commit type:fix/hint-overlay-flicker,feat/hint-arrows.Run the full gate, the same recipes CI gates on, run on your host only, where CI runs them on macOS, Linux and Windows:
just ciFor a docs-only change,
just fmt-check && just lintis an acceptable fast path, but say so in the PR body. Never open a PR on a red gate.
Commit messages
Format: <type>(<optional scope>): <subject>, imperative mood, lowercase,
no trailing period.
- Write the subject for a Neru user, not for the diff.
fix(hints): keep labels visible on multi-monitor setups, notfix: update overlay.go. The subject does not ship, since the squash title does (see below), but a reviewer reads the branch commit by commit, and the title is usually one of these subjects, so a sloppy one costs twice. - Types that appear in the changelog, decided by the title's type since
that is the subject Release Please reads:
feat,fix,perf,revert,improve,experiment,docs. Hidden from it:refactor,test,chore,ci,build,style. (release-please-config.jsonis the authority, and note it acceptsimproveandexperiment, which the conventional-commits site does not list.) - Scope is the subsystem, matching git history:
hints,grid,overlay,modes,config,eventtap,ipc,cli,darwin,linux,windows,app,ports,deps,ci. Checkgit log --oneline -20when unsure. Scopeless is fine for cross-cutting changes. - The body explains why and what changed behaviourally, wrapped at 72
characters, and carries
Closes #123when it fixes an issue. - One logical change per commit, one logical change per PR. If the diff wants two types, it wants two PRs.
The pull request
Title is a conventional commit subject, and the one that matters most. The squash lands the branch as a single commit with this as its subject, so this is the line Release Please ships and the only one a user ever reads.
Body follows .github/pull_request_template.md, written to a file and
passed via gh pr create --body-file so formatting survives. Fill it
properly:
- Tick the boxes that genuinely apply, and only those. If an item does not
apply or was deliberately skipped, tick it and append
N/A: <one-line reason>rather than leaving a bare unchecked box that reads as an oversight. "just cipasses" means it exited 0 in this worktree. - Delete the optional trailing sections only if they do not apply. Put
None.under Related Issues when there is nothing to link. - UI-visible changes (overlays, hints, grid) get a screenshot or short
recording. Use
just build, then./bin/neru launch.
Writing the Description
Short: two or three short paragraphs at most.
- Always open with
This PR <verb> ..., such as fixes, adds, removes or reworks. - Never name functions, files, types, or symbols. Describe behaviour and
user-visible effect. A reader should understand what changed for them
without opening the diff.
- Bad:
Changes NeruMoveMouseWithType in accessibility_mouse_darwin.m ... - Good:
This PR fixes cursor positioning while macOS Zoom is zoomed in.
- Bad:
- Say what was wrong and what is true now, with one sentence for any deliberate limitation. Deeper detail, such as trade-offs, measurements and rejected alternatives, goes under Additional Context, brief and factual.
Config and command changes get their own section
If the PR changes anything a user writes or types, such as config options (added,
renamed, removed, new default or accepted values), commands, subcommands,
flags or environment variables, spell the changes out in the body under its
own heading, even though docs/reference/configuration.md / docs/reference/cli.md are updated
in the same PR. This is the exception to the no-symbols rule. Config keys and
command names are the user-facing interface, so name them exactly as typed,
note defaults, and say whether existing configs keep working. A short TOML
snippet or one-line invocation helps, and a table works when there are several.
Flagging potential breaking changes
If an existing config file, script, or muscle-memory invocation could stop doing what it did, such as a removed/renamed option or command, narrowed accepted values, a changed default or meaning, or a changed exit code or output format, say so in the body under its own heading: what breaks, who it affects, what they do about it, with a concrete before/after when migration is needed. Be honest about uncertainty, since "potentially breaking if ..." beats silence or an unqualified warning. Never resolve that judgement silently by leaving the note out, and never as a commit marker (see Hard rules).
Before finishing
- Grep the commit message and PR body for
claude,anthropic,co-authored,generated with, and🤖. Any hit is a bug, so amend or edit. - Check the PR title and every commit subject for a
!before the colon, and every message for aBREAKING CHANGE:footer. There should be none of either. The title matters most, since that is the one Release Please reads. - Re-read the diff for config/command/flag/env changes and confirm each is named in the body, because it is easy to describe the behaviour and forget the interface.
- Platform-touching PRs: run the
platform-boundary-revieweragent on the diff first. Modes/handler-touching PRs: rundeadlock-reviewer.
After opening
Watch CI (gh pr checks --watch) and fix failures yourself rather than
leaving the PR red. Iterate on review feedback with new commits. Maintainers
squash, so there is no need to rewrite history with force-pushes.