codex-pr
Skill118 starsChanged 37 days agoMITView on GitHub
Open or update a pull request for the current branch with an independently drafted and reviewed PR_AGENTDESC.md. Use whenever the user asks Codex to open or draft a pull request in a tbhb repository, or when a completed task should end in a pull request. Routes later CI work to codex-watch-pr and codex-fix-pr.
In this repository32 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- analyze-sessionSkill
- codex-analyze-sessionSkill
- codex-commitSkill
- codex-fix-proseSkill
- codex-fix-prSkill
- codex-merge-prSkill
- codex-rebaseSkill
- codex-resolve-rebase-conflictsSkill
- codex-review-commit-messageSkill
- codex-review-pr-descriptionSkill
- codex-review-prose-fixSkill
- codex-review-squash-messageSkill
- codex-watch-prSkill
- codex-write-pr-descriptionSkill
- codex-write-prose-fixSkill
- commitSkill
- fix-proseSkill
- fix-prSkill
- merge-prSkill
- prSkill
- rebaseSkill
- releaseSkill
- resolve-rebase-conflictsSkill
- review-commit-messageSkill
- review-pr-descriptionSkill
- review-prose-fixSkill
- review-squash-messageSkill
- watch-prSkill
- write-pr-descriptionSkill
- write-prose-fixSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 9
Use update_plan for these phases: preflight, draft, prose gates, independent review, confirmation, publication, and requested …
- Very specific: line 19
Stop on a missing prerequisite or an interrupted Git operation.
- Very specific: line 29
Don't draft the file in the calling context.
- Very specific: line 31
Run the prose workflow over PR_AGENTDESC.md with mise run lint-pr-description when codex-fix-prose is available.
- Very specific: line 43
Run mise run lint-pr-description after review.
- Distinctive: line 58
After confirmation, run only:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Open a pull request
Use update_plan for these phases: preflight, draft, prose gates, independent review, confirmation, publication, and requested follow-through. Keep only one phase in_progress.
Preflight
Run:
bash .agents/skills/codex-pr/scripts/preflight.shStop on a missing prerequisite or an interrupted Git operation. If the branch is behind its base, use codex-rebase first. Tell the user about uncommitted changes before continuing. The preflight scaffolds PR_AGENTDESC.md and reports an existing pull request.
Draft with a delegated writer
Spawn one subagent with this bounded task:
Use the codex-write-pr-description skill in <repo root>. Write or revise PR_AGENTDESC.md, run its validator, and return only its DRAFT result.Don't draft the file in the calling context. If the writer reports DRAFT: BLOCKED, report the blocker and stop.
Run the prose workflow over PR_AGENTDESC.md with mise run lint-pr-description when codex-fix-prose is available. Otherwise run that task directly and resolve only mechanical findings.
Review with a fresh delegated agent
Spawn a different subagent:
Use the codex-review-pr-description skill in <repo root>. Review PR_AGENTDESC.md against the branch and return its verdict.On CHANGES REQUIRED, send the findings verbatim to a fresh writer, then review again with a fresh reviewer. Bound finding-driven revisions at three. After PASS, the reviewer records the reviewed digest through record-review.sh. Don't run that script from the calling agent.
Run mise run lint-pr-description after review. Any edit invalidates the digest, so repeat the independent review after a change.
Get confirmation in default mode
Show the branch, base, commit count, and complete draft. Unless preflight reports pr: GRANTED, ask before publication by putting this question and its choices in the final response when using Default mode:
- open, fix, and merge
- open, watch, and fix
- open and watch
- open only
Also ask whether fixes should be separate commits or amendments. A pre-approval chooses separate commits and routes through merge only when merge: GRANTED. Stop there: don't publish in the same turn as the confirmation question.
Publish
After confirmation, run only:
bash .agents/skills/codex-pr/scripts/create-pr.shThe script checks the draft and requires the recorded digest to match its current bytes. It also resolves properties, pushes, and creates or updates the pull request. Don't bypass it with a direct mutating gh pr call. Report the URL.
Route follow-through to codex-watch-pr and codex-fix-pr according to the confirmed choice. Bound repeated fixes of the same check at three. Use codex-merge-pr only when the user explicitly requested merging or pre-approved it.
Preconditions
- authenticated
gh mise run lint-pr-description- ignored
PR_AGENTDESC.md .github/pull_request_template.md- the sibling Codex skills named in the preceding sections
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

