pr-workflow-skill

A skill for high-signal PR and commit workflows in agentic AI coding. Works with your coding agent of choice.

What it does

• Enforces human-written intent at the top of every PR (never AI-generated)
• Captures full prompt history with timestamps for auditability
• Records environment metadata (harness, model, thinking level, terminal, system)
• Guides surgical commits (one logical change per commit, no bulk adds)
• Defaults PRs to draft until tests + review pass

Installation

Give this to your coding agent:

Install the PR workflow skill from https://github.com/joshp123/pr-workflow-skill — clone it to wherever I keep skills, and wire it up so it activates when I create commits or PRs.

Usage

The skill activates when creating commits or PRs. It will:

1. Prompt you for intent — your own words explaining WHY this change exists
2. Build the PR body using the template in references/pr-human-template.md
3. Collect environment metadata using scripts/build_pr_body.sh
4. Include full prompt history in table format

Example PR

---

Human written summary:

The intent of this change is, as written by a human:

I want to make a global skill to encode my PR workflow. the skill should help me (a lazy idiot) make good PRs using my coding agents, explaining what i've done, so that maintainers get high quality contributiions, without noise, espeically including rpompt histories.

The rest of this PR was written by gpt-5.2-codex-high, running in the codex harness. Full environment + prompt history appear at the end.

Changes

• New skill: skills/pr-commit-workflow/ — global PR/commit workflow with hard human-intent gate and explicit prompt-history requirements
• Human-written PR template: verbatim intent at top (blockquote), model attribution, full prompt history at bottom
• Reviewer-prompting + default-draft policy: PRs stay draft until tests + review pass
• Environment metadata collector script: detects harness/model/thinking/terminal/system programmatically
• Surgical commit guidance: one logical change per commit, no bulk git add

Tests

• nix flake check — ok (warnings: uncommitted tree, unknown flake output homeManagerModules)

Risks

• Low; docs/skill only
• Template may feel heavy for tiny changes (follow-up: add lightweight variant)

Follow-ups

• Lightweight template variant for trivial PRs
• Reviewer handles/team mapping for automation

Prompt History

Environment

Harness: codex Model: gpt-5.2-codex Thinking level: high Terminal: iTerm.app 3.6.6 System: macOS 26.1

Prompts

(truncated for this example — real PRs include full verbatim prompts)

ISO-8601	Prompt
2026-01-10T20:05:12Z	i need you to use cass/cm and search for all instructions related to creating PRs in the last 2 months or so...
2026-01-10T20:34:59Z	can you draft a skill that helps us do this commit and PR workflow?
2026-01-10T20:46:07Z	needs to indicate HUMAN WRITTEN intent. this absolutely MUST NOT be generated by the model EVER!!!!!
2026-01-10T20:50:06Z	ok. use the skill and make a PR to my ai stack repo with this

---

Files

• SKILL.md — skill entry point
• references/workflow-commit.md — commit workflow steps
• references/workflow-pr.md — PR workflow steps
• references/pr-human-template.md — the PR template
• references/commit-format.md — commit message format
• scripts/build_pr_body.sh — environment metadata collector

License

AGPL-3.0