PR Draft Summary
Purpose
Produce the PR-ready summary required in this repository after eligible code work is complete: a concise summary plus a PR-ready title and draft description that begins with "This pull request ...". The block should be ready to paste into a PR for openai-agents-python.
When to Trigger
- An explicit user request for a PR draft takes precedence over the automatic-trigger exclusions below.
- For automatic invocation, spelling, comments, or formatting alone are editorial even under runtime/test paths when they change no behavior or contract. Skip the automatic draft for those edits.
- Before every final response, check whether the current task changed runtime code (
src/agents/), tests (tests/), examples (examples/), build/test configuration, or docs with behavior impact.
- If it did, run this skill after required verification and before sending the final response. Do not use perceived change size to decide whether to run it.
- Run it for eligible local-only and uncommitted work even when the user did not ask to create a pull request. Producing this text does not authorize creating a branch, committing, pushing, or opening a pull request.
- Skip only for trivial or conversation-only tasks, repo-meta/doc-only tasks without behavior impact, an explicitly invoked
$release-candidate-prep handoff that uses the complete $final-release-review report as its release-specific PR description, or when the user explicitly says not to include the PR draft block. This exception applies to preparing the release candidate itself, not to implementing or changing the release-preparation skill.
Inputs to Collect Automatically (do not ask the user)
- Current branch:
git rev-parse --abbrev-ref HEAD.
- Working tree:
git status -sb.
- Untracked files:
git ls-files --others --exclude-standard (use with git status -sb to ensure they are surfaced; --stat does not include them).
- Changed files:
git diff --name-only (unstaged) and git diff --name-only --cached (staged); sizes via git diff --stat and git diff --stat --cached.
- Latest release tag (prefer remote-aware lookup):
LATEST_RELEASE_TAG=$(.agents/skills/final-release-review/scripts/find_latest_release_tag.sh origin 'v*' 2>/dev/null || git tag -l 'v*' --sort=-v:refname | head -n1).
- Base reference (use the branch's upstream, fallback to
origin/main):
BASE_REF=$(git rev-parse --abbrev-ref --symbolic-full-name @{upstream} 2>/dev/null || echo origin/main).BASE_COMMIT=$(git merge-base --fork-point "$BASE_REF" HEAD || git merge-base "$BASE_REF" HEAD || echo "$BASE_REF").
- Commits ahead of the base fork point:
git log --oneline --no-merges ${BASE_COMMIT}..HEAD.
- Category signals for this repo: runtime (
src/agents/), tests (tests/), examples (examples/), docs (docs/, mkdocs.yml), build/test config (pyproject.toml, uv.lock, Makefile, .github/).
Workflow
- Run the commands above without asking the user; compute
BASE_REF/BASE_COMMIT first so later commands reuse them.
- If there are no staged/unstaged/untracked changes and no commits ahead of
${BASE_COMMIT}, reply briefly that no code changes were detected and skip emitting the PR block.
- Infer change type from the touched paths listed under "Category signals"; classify as feature, fix, refactor, or docs-with-impact, and flag backward-compatibility risk only when the diff changes released public APIs, external config, persisted data, serialized state, or wire protocols. Judge that risk against
LATEST_RELEASE_TAG, not unreleased branch-only churn.
- Summarize changes in 1–3 short sentences using the key paths (top 5) and
git diff --stat output; explicitly call out untracked files from git status -sb/git ls-files --others --exclude-standard because --stat does not include them. If the working tree is clean but there are commits ahead of ${BASE_COMMIT}, summarize using those commit messages.
- Choose the lead verb for the description: feature →
adds, bug fix → fixes, refactor/perf → improves or updates, docs-only → updates.
- Suggest a branch name. If already off main, keep it; otherwise propose
feat/<slug>, fix/<slug>, or docs/<slug> based on the primary area (e.g., docs/pr-draft-summary-guidance).
- If the current branch matches
issue-<number> (digits only), keep that branch suggestion. Optionally pull light issue context (for example via the GitHub API) when available, but do not block or retry if it is not. When an issue number is present, use the native same-repository reference #<number> and include an auto-closing line such as This pull request resolves #<number>.. Do not add the explicit issue URL or wrap the reference in a Markdown link.
- Draft the PR title and description using the template below. Apply the repository-wide GitHub paste-readiness rule: use exactly
#123 for same-repository issues or PRs and owner/repo#123 for cross-repository references; never emit [PR #123](https://github.com/owner/repo/pull/123), [#123](...), Codex navigation links, local file links, Codex-only citation markers or footnotes, or app directives in the copy-ready block. Preserve ordinary descriptive links to API docs, design notes, and other targets without native GitHub issue or pull-request syntax.
- Normalize references before returning the block: replace every same-repository URL or
openai/openai-agents-python#<number> reference with #<number>, replace every cross-repository issue or pull-request URL with owner/repo#<number>, then rescan the full block. Do not return it while a Markdown-linked issue or pull-request label, a same-repository qualified reference, or a bare GitHub issue or pull-request URL remains.
- Output only the block in "Output Format". Keep any surrounding status note minimal and in English.
Output Format
When closing out a task, add this concise Markdown block (English only) after any brief status note unless the task falls under the documented skip cases or the user says they do not want it.
# Pull Request Draft
## Branch name suggestion
git checkout -b <kebab-case suggestion, e.g., feat/pr-draft-summary-skill>
## Title
<single-line imperative title, which can be a commit message; if a common prefix like chore: and feat: etc., having them is preferred>
## Description
<include what you changed plus a draft pull request title and description for your local changes; start the description with prose such as "This pull request resolves/updates/adds ..." using a verb that matches the change (you can use bullets later), explain the change background (for bugs, clearly describe the bug, symptoms, or repro; for features, what is needed and why), any behavior changes or considerations to be aware of, and you do not need to mention tests you ran.>
Keep it tight—no redundant prose around the block, and avoid repeating details between Changes and the description. Tests do not need to be listed unless specifically requested.
1---2name: pr-draft-summary3description: Prepare the required local PR title, description, and branch suggestion after eligible implementation work is complete.4---5
6# PR Draft Summary
7
8## Purpose
9Produce the PR-ready summary required in this repository after eligible code work is complete: a concise summary plus a PR-ready title and draft description that begins with "This pull request <verb> ...". The block should be ready to paste into a PR for openai-agents-python.
10
11## When to Trigger
12- An explicit user request for a PR draft takes precedence over the automatic-trigger exclusions below.
13- For automatic invocation, spelling, comments, or formatting alone are editorial even under runtime/test paths when they change no behavior or contract. Skip the automatic draft for those edits.
14- Before every final response, check whether the current task changed runtime code (`src/agents/`), tests (`tests/`), examples (`examples/`), build/test configuration, or docs with behavior impact.
15- If it did, run this skill after required verification and before sending the final response. Do not use perceived change size to decide whether to run it.
16- Run it for eligible local-only and uncommitted work even when the user did not ask to create a pull request. Producing this text does not authorize creating a branch, committing, pushing, or opening a pull request.
17- Skip only for trivial or conversation-only tasks, repo-meta/doc-only tasks without behavior impact, an explicitly invoked `$release-candidate-prep` handoff that uses the complete `$final-release-review` report as its release-specific PR description, or when the user explicitly says not to include the PR draft block. This exception applies to preparing the release candidate itself, not to implementing or changing the release-preparation skill.
18
19## Inputs to Collect Automatically (do not ask the user)
20- Current branch: `git rev-parse --abbrev-ref HEAD`.
21- Working tree: `git status -sb`.
22- Untracked files: `git ls-files --others --exclude-standard` (use with `git status -sb` to ensure they are surfaced; `--stat` does not include them).
23- Changed files: `git diff --name-only` (unstaged) and `git diff --name-only --cached` (staged); sizes via `git diff --stat` and `git diff --stat --cached`.
24- Latest release tag (prefer remote-aware lookup): `LATEST_RELEASE_TAG=$(.agents/skills/final-release-review/scripts/find_latest_release_tag.sh origin 'v*' 2>/dev/null || git tag -l 'v*' --sort=-v:refname | head -n1)`.
25- Base reference (use the branch's upstream, fallback to `origin/main`):
26 - `BASE_REF=$(git rev-parse --abbrev-ref --symbolic-full-name @{upstream} 2>/dev/null || echo origin/main)`.
27 - `BASE_COMMIT=$(git merge-base --fork-point "$BASE_REF" HEAD || git merge-base "$BASE_REF" HEAD || echo "$BASE_REF")`.
28- Commits ahead of the base fork point: `git log --oneline --no-merges ${BASE_COMMIT}..HEAD`.
29- Category signals for this repo: runtime (`src/agents/`), tests (`tests/`), examples (`examples/`), docs (`docs/`, `mkdocs.yml`), build/test config (`pyproject.toml`, `uv.lock`, `Makefile`, `.github/`).
30
31## Workflow
321) Run the commands above without asking the user; compute `BASE_REF`/`BASE_COMMIT` first so later commands reuse them.
332) If there are no staged/unstaged/untracked changes and no commits ahead of `${BASE_COMMIT}`, reply briefly that no code changes were detected and skip emitting the PR block.
343) Infer change type from the touched paths listed under "Category signals"; classify as feature, fix, refactor, or docs-with-impact, and flag backward-compatibility risk only when the diff changes released public APIs, external config, persisted data, serialized state, or wire protocols. Judge that risk against `LATEST_RELEASE_TAG`, not unreleased branch-only churn.
354) Summarize changes in 1–3 short sentences using the key paths (top 5) and `git diff --stat` output; explicitly call out untracked files from `git status -sb`/`git ls-files --others --exclude-standard` because `--stat` does not include them. If the working tree is clean but there are commits ahead of `${BASE_COMMIT}`, summarize using those commit messages.
365) Choose the lead verb for the description: feature → `adds`, bug fix → `fixes`, refactor/perf → `improves` or `updates`, docs-only → `updates`.
376) Suggest a branch name. If already off main, keep it; otherwise propose `feat/<slug>`, `fix/<slug>`, or `docs/<slug>` based on the primary area (e.g., `docs/pr-draft-summary-guidance`).
387) If the current branch matches `issue-<number>` (digits only), keep that branch suggestion. Optionally pull light issue context (for example via the GitHub API) when available, but do not block or retry if it is not. When an issue number is present, use the native same-repository reference `#<number>` and include an auto-closing line such as `This pull request resolves #<number>.`. Do not add the explicit issue URL or wrap the reference in a Markdown link.
398) Draft the PR title and description using the template below. Apply the repository-wide GitHub paste-readiness rule: use exactly `#123` for same-repository issues or PRs and `owner/repo#123` for cross-repository references; never emit `[PR #123](https://github.com/owner/repo/pull/123)`, `[#123](...)`, Codex navigation links, local file links, Codex-only citation markers or footnotes, or app directives in the copy-ready block. Preserve ordinary descriptive links to API docs, design notes, and other targets without native GitHub issue or pull-request syntax.
409) Normalize references before returning the block: replace every same-repository URL or `openai/openai-agents-python#<number>` reference with `#<number>`, replace every cross-repository issue or pull-request URL with `owner/repo#<number>`, then rescan the full block. Do not return it while a Markdown-linked issue or pull-request label, a same-repository qualified reference, or a bare GitHub issue or pull-request URL remains.
4110) Output only the block in "Output Format". Keep any surrounding status note minimal and in English.
42
43## Output Format
44When closing out a task, add this concise Markdown block (English only) after any brief status note unless the task falls under the documented skip cases or the user says they do not want it.
45
46```
47# Pull Request Draft
48
49## Branch name suggestion
50
51git checkout -b <kebab-case suggestion, e.g., feat/pr-draft-summary-skill>
52
53## Title
54
55<single-line imperative title, which can be a commit message; if a common prefix like chore: and feat: etc., having them is preferred>
56
57## Description
58
59<include what you changed plus a draft pull request title and description for your local changes; start the description with prose such as "This pull request resolves/updates/adds ..." using a verb that matches the change (you can use bullets later), explain the change background (for bugs, clearly describe the bug, symptoms, or repro; for features, what is needed and why), any behavior changes or considerations to be aware of, and you do not need to mention tests you ran.>
60```
61
62Keep it tight—no redundant prose around the block, and avoid repeating details between `Changes` and the description. Tests do not need to be listed unless specifically requested.
gabrielmoreira