| name | author-pr |
| description | Create ready-for-review pull requests on GitHub. Use when the branch is ready to open a PR; when the user asks to create, push, or open a PR; after local changes are committed; or when documenting user-facing features, bug fixes, performance optimizations, validation, changelog impact, or operational impact in a PR that follows repository conventions without AI attribution. |
Author PR
Overview
The goal is to create the PR on GitHub, not just draft title and body text in chat. The skill is complete when the PR exists on GitHub and you return its URL.
Always create a ready-for-review PR. Never create a GitHub Draft PR, never pass --draft, never set draft: true, and never emit an isDraft=true PR directive. If the branch is not ready for reviewer attention, stop and explain what remains instead of opening a Draft PR.
Write PR titles and descriptions that are reviewable, evidence-backed, and consistent across agents. Default bodies use Description, Usage, Changelog, and Validation sections. Base the summary on all commits in the branch, not only the latest one.
If the branch is not ready — uncommitted work, failing tests the user expects fixed first, or the user asked only to revise an existing PR description — say what is blocking creation and what remains. Do not pretend a PR was opened.
Title Rules
Use a concise imperative title. Prefer the repository's Conventional-Commit-like style:
feat(api): add token trend filters
fix(storage): preserve cursor session ids
docs: document agent contributor workflows
chore: tighten cleanup handling
Do not include AI attribution in the title or body. Do not add generated-by footers, co-author trailers for agents, or notes that the PR was written by an AI tool.
Body Shape
Default to these sections:
## Description
**What.** [One sentence description].
**Why.** [One sentence description].
[Multi-paragraph description]
## Usage
[How users or developers will see this change]
## Changelog
- ...
## Validation
[Narrative description of how this was validated]
Keep sections short when the PR is small. Add focused extra sections only when useful, such as ## Bug Evidence, ## Performance, ## Operational Impact, or ## References.
Description
Open with bold one-line What. and Why. summaries, then expand in prose, bullets, or examples as needed.
State the concrete change in reviewer-facing terms. Mention files or subsystems when that helps review scope. Explain the reason for the change, not only the implementation. Include code, commands, queries, or before/after examples when they make the motivation concrete.
Good:
## Description
**What.** Adds a repo-local contributor workflow plugin with agent skills.
**Why.** Agents were repeating PR body structure differently across sessions; a shared skill gives each agent the same review contract.
- Vendors `$cross-harness-skills:start-work`, `$cross-harness-skills:crystallize`, `$cross-harness-skills:code-review`, and `$cross-harness-skills:author-pr` skills.
- Documents local installation in `docs/development/agent-contributor-workflows.md`.
That makes it easier for reviewers to find behavior, impact, and test evidence.
Usage
For user-facing features, demonstrate the feature in the PR description. Use the most natural form for the change: CLI commands, config snippets, API calls, screenshots, curl examples, or UI steps.
Examples:
## Usage
Run the local plugin marketplace from a checkout:
```bash
codex plugin marketplace add .
```
Then enable `cross-harness-skills` and invoke:
```text
Use $cross-harness-skills:author-pr to create this PR on GitHub.
```
## Usage
Example config:
```toml
[mcp]
retrieval_scope = "project_only"
```
With this setting, search only returns records from the current project.
Skip usage only when the PR is purely internal and no user, operator, or downstream developer action changes. If skipped, say No user-facing usage change.
Changelog
Summarize the externally meaningful change. Use None when there is no release-note-worthy impact.
Good:
## Changelog
- Adds developer-only PR authoring guidance for contributor agents.
- No end-user runtime behavior change.
Validation
Write a short narrative that names exact commands and outcomes. Include skipped validation with a reason.
Example:
## Validation
Validated plugin metadata with `python3 -m json.tool .agents/plugins/marketplace.json` and `quick_validate.py plugins/cross-harness-skills/skills/author-pr`. Ran `make docs-build` successfully. Unit tests were not run; change is docs and plugin metadata only.
For stack-facing changes, include the repository's normal integration or smoke validation details, or state why that validation was not run.
Bug Fixes
Bug fix PRs must include specific evidence that the bug was fixed. Provide at least:
- The failing behavior or reproducer before the change.
- The root cause in concrete terms.
- The code path that changed.
- The command, test, fixture, or manual check that now passes.
Example:
## Bug Evidence
Before this PR, records with missing workspace paths produced empty project
filters:
```text
search_sessions(project_only=true) -> 0 results
```
The fix normalizes the workspace path before writing the row. The new fixture
covers the missing-path case, and the focused storage test now passes.
Performance
Performance optimization PRs must include baseline and PR metrics. Include:
- Hardware or environment when relevant.
- Dataset or workload size.
- Command or measurement method.
- Baseline metric.
- PR metric.
- Delta and caveats.
Example:
## Performance
Workload: 100k normalized events, local database, warm cache.
| Metric | Baseline | This PR | Delta |
| --- | ---: | ---: | ---: |
| `search_sessions` p50 | 182 ms | 121 ms | -33.5% |
| `search_sessions` p95 | 441 ms | 286 ms | -35.1% |
Command:
```bash
bash scripts/bench/search-sessions.sh --events 100000 --warm-cache
```
Do not describe a change as a performance improvement without metrics. If metrics are not available, phrase it as a refactor or preparation work instead.
