/pr

description: "Creates and updates GitHub pull requests for cloudflare-docs changes. Load when asked to open, create, submit, update, or edit a PR, or write a PR title or description. Covers title conventions, branch naming, PR body structure, and the documentation checklist template."

Use this skill when creating a GitHub pull request for changes to this repository, or when editing an existing PR's title or description.

`gh` CLI

This skill uses the `gh` CLI throughout. If a `gh` command fails because it is not installed or not authenticated, fall back to providing the PR title and body clearly so the user can copy-paste them, along with the relevant GitHub URL:

• **New PR**: `https://github.com/cloudflare/cloudflare-docs/compare/production...<branch>` (get branch from `git branch --show-current`)
• **Edit existing PR**: `https://github.com/cloudflare/cloudflare-docs/pull/<number>` — instruct them to select **Edit** on the description.

Editing an existing PR

When asked to update or edit an existing PR description (or title), follow these rules strictly — then stop. Do not proceed to the "Creating a new PR" steps below.

1. **Always read the current PR description first** using `gh pr view <number> --json title,body` before making any changes. 2. **If the description is empty**, treat it as a new PR body and follow the template and guidelines in the "Creating a new PR" section below. 3. **Follow the existing format** — if the author has structured their description in a particular way, preserve that structure. Do not reformat, reorder, or restructure sections they wrote. 4. **Only change what was asked** — make the minimum edit necessary to fulfill the request. Do not "improve" unrelated phrasing, fix grammar elsewhere, rewrite the summary, or modify checklist items that were not part of the request. 5. Apply the edit:

• **Title**: `gh pr edit <number> --title "..."`
• **Body**: Write the updated body to a temp file using the Write tool, then run `gh pr edit <number> --body-file /tmp/pr-body.md` and clean up with `rm /tmp/pr-body.md`. Do not use `--body "..."` — shell quoting mangles backticks and other Markdown formatting.

After pushing to a branch with an open PR

Whenever you push new commits to a branch that already has an open PR, check whether the PR title and description still accurately describe what the branch now does. New commits often add scope the original description does not mention.

1. Check for an open PR on the branch: `gh pr view --json number,title,body`. 2. Compare the title and body against the full branch diff (`git diff production...HEAD --stat`), not just the latest commit. 3. If they are now inaccurate or incomplete, update them following the "Editing an existing PR" rules above — preserve the author's structure and make the minimum edit needed to reflect the new changes. If they still describe the branch correctly, leave them unchanged.

Do this proactively after a push; you do not need to be asked separately to keep the PR in sync.

Creating a new PR

Follow Steps 1–4 below only when creating a new PR (or when an existing PR has an empty description).

Step 1 — Gather context

Run `--stat` first to understand the scope without blowing up context:

git log --oneline production..HEAD
git diff production...HEAD --stat
git status

**If `git status` shows untracked or modified files**, stop and ask the user whether those files should be committed as part of this PR before proceeding. Do not silently ignore them — they may be integral to the work being submitted.

If the stat output shows more than ~20 files changed, do **not** run the full diff. Instead, read specific files that are unclear from the stat output. For smaller changesets (under ~20 files), the full diff is fine:

git diff production...HEAD

Step 2 — Write the PR title

Branch: `production`

This repo uses `production` as the default branch, not `main`. Always use `--base production` when creating PRs. Contributors from other repos often expect `main` — this is intentional.

Create feature branches off an up-to-date `production` commit (`git fetch origin` then branch from `origin/production`) unless the user asked for a different base.

Format

For content changes, the dominant convention is product brackets:

[Product] Short description

For changes spanning multiple products:

[Product1, Product2] Short description

For non-content changes (tooling, CI, config, components, worker code, repo maintenance), use a conventional commit prefix instead:

chore: Short description
fix: Short description
feat: Short description

Inferring the product bracket from file paths

Do not ask the author what product bracket to use — infer it from the changed file paths.

• `src/content/docs/{slug}/` and `src/content/partials/{slug}/` map directly to a product. Read the `title` field from `src/content/docs/{slug}/index.mdx` to get the display name, then strip any "Cloudflare " prefix to get the bracket (e.g. title "Cloudflare Workers" → `[Workers]`).
• `src/content/changelog/{slug}/` maps the same way — use the product bracket, not `[Changelog]`. Use `[Changelog]` only when the PR exclusively adds or updates changelog entries across multiple products.
• If the change spans more than 3 products, use the 2–3 most prominent ones.

Rules

• Use title case for product names inside brackets: `[Workers]`, `[AI Search]`, `[Zero Trust]`
• Keep the description under ~60 characters
• Use imperative mood: add, fix, update, remove, document, correct
• Do not end with a period
• Common abbreviations in brackets: `[DO]` for Durable Objects, `[KV]`, `[ZT]` for Zero Trust, `[R2]`, `[D1]`

Title examples (from real PRs)

[AI Search] Add hybrid search and boosting configuration docs
[Hyperdrive, Workers VPC] Document TCP services, TLS cert verification
[Browser Rendering] Add Wrangler CLI commands documentation
[Billing] Restructu