pull-request

Pull request

Principle

Publish one GitHub pull request action from validated local files and a process-local author value. Keep the parent environment unchanged.

When this applies

Use this skill for one pull request action:

• Create a pull request, ready for review by default or a draft with --draft.
• Edit a pull request title or body.
• Add a pull request comment.
• Submit a pull request review.
• Recover one selected legacy author record before the action.

Send issue create, edit, and comment work to the issue-tracker skill, one action at a time. Send review and fix-loop work to e-code-review. Make commits and pushes with Git directly.

Require one repository and one action target. Stop before author lookup or network work when the repository, pull request, action, author, or required local file is missing or ambiguous.

Use these exact refusal responses when the request belongs to another skill:

• Issue action: Use issue-tracker for this GitHub issue action.
• Commit or push: Use Git directly for this commit or push.
• Missing target: Provide one repository and one pull request action target.

Constraints

• Run local validation and privacy checks before account lookup or network work.
• Use a body file. Do not send inline body text through the shell.
• Keep GITHUB_DEFAULT_ACCOUNT, the parent environment, and global GitHub CLI state unchanged.
• Run one create, edit, comment, review, or recovery action per command.
• Use global account switching only for one explicitly selected legacy record.
• Read back the remote state before reporting success.

Dependencies

The commands use Python 3.11 or later and the Python standard library. GitHub actions also require an authenticated gh executable. The linter and artifact uploader ship in this package. Set GITHUB_DEFAULT_ACCOUNT to one exact GitHub CLI login when the action needs a selected author. Leave it unset to use the current process environment.

Sub-skills

Skill	When	Produces	If missing
pstack:poteto-agent with pull-request instructions	Create or a full body rewrite, when you want the body drafted for you	A reviewed title and body file	Write the title and body yourself
privacy-hygiene	Before any durable GitHub post	A clean body and repository privacy sweep	Stop before publication and report the missing gate
issue-tracker	Issue create, edit, or comment requests	Issue state and issue URLs	Route the request there.
e-code-review	Review or review/fix loop requests	Structured findings or a clean review result	Route the request there.

Task seeding

When the session exposes a task tool, register the items in reference/publication-tasks.md as session tasks. Otherwise work through the Process steps in order.

Process

1. Scope the action

Resolve the repository, action, and selected GitHub author. For create, resolve the source branch, base, and head. For other actions, resolve one existing pull request target. Create publishes a ready pull request, and --draft publishes a draft. Record the target before any write.

2. Author the title and body

For create, run pull_request.py template --body-file <path> --title <title> first. It appends each heading the linter and proof gate require that the file lacks. Then fill the body, or invoke pstack:poteto-agent with the diff-specific writing instructions to draft it. A comment or review may use a supplied body file when it does not rewrite the pull request description.

Check each behavior claim against the final diff and verification evidence. Preserve whether a rule is added, removed, or narrowed, and distinguish tests added from tests run. Refresh these claims after a rebase or correction.

Write the body in the section order reference/body-sections.md gives: What this does, What changed, Existing work, Proof in practice, Eval for a feat title, Risk, How to revert. Include only claims supported by the final diff.

Keep substantive review and test evidence. Put extensive logs, raw diffs, token counts, and agent transcripts in an existing linked artifact or a closed <details> section after the primary explanation. Let justified evidence grow without a total-length cap. A collapsed transcript still needs a useful opening.

Load a repository's PR-description skill and run the checker command it supplies. Apply these steps to automated publishers too. A green code check proves no description claim by itself.

3. Run the local linter

Resolve the active managed root (CLAUDE_CONFIG_DIR when set, ~/.claude otherwise), then run <managed-root>/scripts/durable_post_lint.py with the matching action and title or body file. Use pr-create, pr-edit, pr-comment, or pr-review. The linter owns the action-specific body, title, and volatile-path rules.

Exit code 0 continues to the next gate. Any non-zero exit stops the action. Fix the named local input and rerun the linter. Do not look up the author or make a network call while validation fails.

4. Run privacy and artifact checks

Invoke privacy-hygiene before the GitHub post. Upload binary evidence with scripts/gh_artifact_upload.py and replace local artifact references with permanent URLs. Rerun the linter after changing the body.

5. Resolve the process-local author

Run ~/.agents/skills/pull-request/scripts/pull_request.py (under the agents home, not the repository; a worktree holds no .agents/ copy) with one structured action and the selected author. The command runs the linter again, resolves the author value, and passes it only to the child gh process. It never changes the parent environment or calls gh auth switch.

If the selected author has no usable value, stop and report the account lookup failure. Never print the value.

6. Recover a selected legacy record

Follow reference/legacy-author-recovery.md only when the user selects one legacy state file. Mark this step N/A otherwise.

7. Run the action

Run pull_request.py for exactly one of create, edit, comment, or review. Supply the validated body file path. Treat a non-zero exit as a failed publication and preserve the local inputs for retry.

8. Read back the remote state

Use the same selected process-local author for a read-only remote readback. Confirm the pull request URL and number, title, body, head SHA, and draft state. For comments and reviews, confirm the new remote entry. Report artifact URLs without exposing author values.

Confirm the published claims still describe the verified head and preserve the scope of its evidence, including whether checks used saved artifacts or a new run. Read the remote opening with evidence sections collapsed. Confirm that it explains the change on its own and that the evidence links lead to the cited results.

Exit handling

Stop before network work when authoring, local validation, privacy, or author selection fails. A failed action preserves its body and any recovery record. Report the generic error and the next required input. A successful action ends only after remote readback proves the requested state.

Examples

Read reference/examples.md for a create, a rejected comment, and a recovery.

Gotchas

• Relative body-file paths depend on the caller directory. Use an absolute path when another process or worktree starts the command.
• Normal pull request actions never call gh auth switch. If that command appears outside explicit recovery, stop.
• gh auth switch, login, and logout change the account for every session on the machine, and a PreToolUse hook denies them. Scope another account to one command: GH_TOKEN=$(gh auth token -u <account>) gh <command>.
• GitHub CLI output can contain account data. The command captures account lookup and recovery output and prints only generic errors.

File index

Path	Purpose
SKILL.md	Hub for pull request publication, validation, author selection, recovery, and readback
reference/publication-tasks.md	Ordered tasks for every publication gate
reference/legacy-author-recovery.md	Recovery of one selected legacy author record
reference/examples.md	Worked create, rejected comment, and recovery examples
reference/body-sections.md	Pull request body sections, their order, and what each holds
scripts/pull_request.py	Command for author selection and create, edit, comment, and review actions
scripts/github_pr_command_constants/	Constants for pull request actions, recovery, exit codes, and generic messages
scripts/test_pull_request.py	Tests for pull_request.py
scripts/recover_legacy_author.py	Command for one selected legacy author record
scripts/test_github_pr_command_constants.py	Tests for the command and recovery constants
scripts/test_recover_legacy_author.py	Tests for recover_legacy_author.py
<managed-root>/scripts/durable_post_lint.py	Shared action-aware title, body, and path validator
scripts/gh_artifact_upload.py	Helper for permanent GitHub binary evidence URLs
scripts/tests/test_gh_artifact_upload.py	Tests for binary evidence upload