pr

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)

Use the [Product] bracket format as your default for content changes. Use conventional commit prefixes for non-content changes.

Step 3 — Write the PR body

Read the PR template from the repository before writing the body:

Use that file as the exact base for the PR body. Do not rely on any hardcoded version of the template — always read it fresh from disk in case it has changed.

How to fill out each section

Summary

Write a short explanation covering:

• What type of documentation is being changed (new page, update, fix, restructure, changelog entry)
• Why the change is needed or what prompted it
• Links to any relevant public context: GitHub issues, related PRs, or public docs pages.

This is a public, open-source repository. Do not include private Cloudflare information, secrets, credentials, environment variable values, or URLs and titles of internal resources (tickets, wiki pages, internal docs) in PR titles, descriptions, or comments. If there is any doubt about whether something is safe to publish, stop and ask the user.

Keep it factual. Do not repeat what the checklist items say. For small, focused PRs 1-2 sentences is enough. For larger PRs touching many files or multiple areas, a longer description is appropriate — use tables, lists, or code blocks over paragraphs of prose where it makes the summary easier to scan.

Good examples:

Small, focused PR:

Adds a caution note for the active attribute mapping behavior in SCIM provisioning.

Fixes https://github.com/cloudflare/cloudflare-docs/issues/1234

Medium PR:

Updates the Access policies index to reflect the new policy grouping UI. Fixes stale screenshots and outdated step ordering.

Larger PR spanning multiple areas:

Restructures the billing docs into intent-based sections to make it easier for users to find pricing and usage information.

Before	After
billing/usage.mdx	billing/usage-and-limits.mdx
billing/limits.mdx	(merged into above)
billing/overview.mdx	billing/index.mdx

• Updated all internal links pointing to moved pages
• Added redirects for all renamed files

Screenshots (optional)

Skip this section entirely unless the PR changes something visual — new pages, rearranged navigation, updated UI steps, or modified images. Do not leave the empty comment placeholder if screenshots are not needed.

If the PR does change something visual, include the section with a <!-- TODO: add screenshots before requesting review --> comment so the human knows to fill it in before the PR is ready for review.

Documentation checklist

Go through each item and decide whether it applies:

1. Changelog entry — Required if the PR documents a new feature, enhancement, or noteworthy change to a Cloudflare product. Remove this item if the PR is a fix, typo correction, internal restructure, or style update.

2. Style guide adherence — Check the diff for files under src/content/ or authored component files (.mdx, .astro, .css). Keep this item only if at least one such file was added or modified. Remove this item if the PR exclusively changes source code (.ts, .tsx, .js), tooling, CI, configuration files, agent skills, or any other non-content assets — even if those files live under src/ or happen to be Markdown.

3. Issue opened for larger changes — Keep this item if the PR adds a new page, restructures a section, or addresses known inaccuracies. Remove it for small focused changes.

4. Redirects for renamed/moved files — Keep this item if any .mdx files were renamed, moved, or deleted. Remove it if no files changed location.

Remove individual checklist items that genuinely do not apply. Do not leave unchecked items that are irrelevant — they create noise for reviewers. Only remove the entire Documentation checklist section if none of the items apply (e.g. a pure CI or tooling change). If even one item applies, keep the section and remove only the irrelevant items.

What not to do

These patterns create review friction and will result in the PR being sent back:

• Context-free rewrites — If the PR significantly changes or restructures content, the summary must explain what changed and why. A diff with no explanation forces reviewers to reverse-engineer intent.
• Diff narration — Do not summarise the PR by listing what changed line by line ("changed X to Y on line 42", "updated heading from A to B"). Explain why the change was made, not what it mechanically did.
• Cross-product changes without explanation — If the PR touches files across multiple product areas, explain the connection. Unrelated-looking changes with no stated reason are a red flag for reviewers.
• Pruning the checklist wrong — Remove individual items that do not apply. Do not delete the entire checklist section unless none of the items are relevant. Reviewers use the remaining items to quickly verify coverage.

Step 4 — Create the PR

Build the PR body by starting from the template read in Step 3 — replace the summary placeholder comment with your actual summary, remove checklist items that do not apply, and handle the screenshots section per the guidance above.

Important: Do not pass the body via --body "$BODY" or --body '...' — shell quoting mangles backticks and other Markdown formatting. Instead, write the body to a temporary file and use --body-file:

All PRs MUST be created as drafts. Most contributors should not land straight into the review queue — the author should review the deploy preview first and mark the PR ready when it looks correct.

Output

Share the PR URL and let the user know it has been created as a draft — they should verify the changes and deploy preview look correct, then mark it as ready for review when they are satisfied. Do not push follow-up commits, do not request reviewers, do not make further edits to the PR unprompted. The human takes it from here.