chore: Make the create-pr skill write shorter PR descriptions for new reviewers (#40811)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

.agents/skills/create-pr/SKILL.md

@@ -78,11 +78,24 @@ Creates GitHub PRs with titles that pass n8n's `check-pr-title` CI validation.
    body structure, then populate each section with actual content before
    creating the PR:
    - **Summary**: describe what the PR does
+   - **Why**: explain why the change is needed (see Why below)
    - **How to test**: describe how to test the changes. Include an example workflow if appropriate
    - **Related tickets**: add the Linear ticket URL (`https://linear.app/n8n/issue/[TICKET-ID]`) and any GitHub issue links
    - **Checklist**: keep as-is from the template
 	 - Add a "🤖 PR Summary generated by AI" at the end of the body
 
+   Before you create the PR, proofread the body with these checks. Rewrite
+   each sentence that fails a check:
+   1. The Summary and the Why together are under the word budget. If not,
+      first remove the details that the reviewer reads in the diff, then
+      shorten the Why.
+   2. Each sentence names who does what: a component, a process, or a person
+      as the subject, with a plain technical verb.
+   3. Each domain term has a plain definition where it first appears.
+   4. Each sentence is true for the diff.
+
+   When a later commit changes a fact in the body, update the body.
+
    ```bash
    gh pr create --draft --title "<type>(<scope>): <summary>" --body "$(cat <<'EOF'
    <populated body based on pull_request_template.md>
@@ -94,12 +107,43 @@ Creates GitHub PRs with titles that pass n8n's `check-pr-title` CI validation.
 
 Based on `.github/pull_request_template.md`:
 
-Write the PR body in ASD-STE100 Simplified Technical English: use short
-sentences, the active voice, and one instruction for each sentence.
+Write for a reviewer who does not know this area of the code. The reviewer
+must understand the change before they open the diff. Use ASD-STE100
+Simplified Technical English: short sentences, active voice.
+1. Keep the Summary and the Why together under about 200 words. A small PR
+   needs much less.
+2. Define each domain term in plain words where it first appears. Do not use
+   a ticket ID or an internal name as an explanation.
+3. Leave out details that the reviewer reads in the diff: error cases, status
+   codes, renamed fields, the order of calls, file lists, test names. Mention
+   one only when it changes behaviour that a reviewer could miss. Also leave
+   out what reviewers already know (framework behaviour).
+4. Use plain technical verbs, not metaphors ("passes the value", not
+   "hands the value" or "lets the value through").
 
-### Summary Section
-- Describe what the PR does
-- Include screenshots/videos for UI changes
+### Summary: what the PR does
+1. Start with one to three sentences of background for a reader who is new to
+   the area. Then state what the PR does.
+2. Write **prose** about behaviour, not a list of code edits. Name a class or
+   a function when it represents an essential/core concept and it helps
+   the reader to navigate the change.
+3. If the PR changes no product code, say so in the first sentence
+   (for example: "This PR only adds tests.").
+4. Do not justify the change here. The justification goes in the Why.
+5. Include screenshots or videos for UI changes.
+
+### Why: the reasoning
+Always fill the `## Why` section. The Summary and the core of the
+Why are what the reviewer needs most. Keep the core short:
+1. Do not repeat the Summary.
+2. State the problem or the constraint that makes the pre-existing code unfit.
+3. If there are accepted gaps, or changes for existing code paths, state them
+   in a separate short paragraph.
+
+Add rejected alternatives only when a reviewer would otherwise ask about them,
+if any. Use one or two sentences for each alternative: state the concrete
+reason it fails. Write an alternative that was never built in the conditional.
+Together, the alternatives must be shorter than the core Why section.
 
 ### How to test Section
 - Explain how to test the changes

.github/pull_request_template.md

@@ -1,8 +1,15 @@
 ## Summary
 
 <!--
-Describe what the PR does.
-Photos and videos are recommended.
+Start with 1 to 3 sentences of background for a new reader. Then describe what the PR does, in prose, not as a list of edits.
+Add photos or videos for UI changes.
+-->
+
+## Why
+
+<!--
+State the problem or the constraint that makes the current code unfit. Do not repeat the Summary.
+Add a rejected alternative only when a reviewer would ask about it, in one or two sentences.
 -->
 
 ## How to test