PR Description Skill

PR Description Skill -- Anchored, Concise, Validated PR Bodies

When to use

Trigger this skill on any of the following intents:

• "write a PR description"
• "draft a PR body"
• "open a PR" / "open this PR" / "let's open the PR"
• "fill in the PR template"
• "summarize this branch as a PR"
• "create the PR write-up"

Reusable for any PR against microsoft/apm. The output is one markdown file that the orchestrator pastes into gh pr create --body-file or surfaces to the maintainer.

Output charset rule (read this first)

The repo-wide encoding rule at .github/instructions/encoding.instructions.md constrains source files and CLI output to printable ASCII because Windows cp1252 terminals raise UnicodeEncodeError on anything else. PR comments are NOT source code and NOT CLI output -- they are rendered by GitHub's Primer engine, which expects UTF-8 GitHub-Flavored Markdown.

Two distinct rules therefore apply:

1. Source files in this bundle (SKILL.md, assets/*) MUST stay ASCII. They live in the repo and are subject to .github/instructions/encoding.instructions.md.
2. The PR body output the skill produces MUST be UTF-8 GitHub-Flavored Markdown. Use em dashes, smart punctuation, alerts, collapsibles, task lists, and Unicode where it improves readability. Mermaid diagram labels MAY use Unicode -- there is no constraint here. The output is consumed by GitHub's renderer, not by a Windows terminal.

A previous version of this skill incorrectly required ASCII in the PR body. That made the output unreadable: no alerts, no collapsibles for long evidence, no em dashes, no smart quotes. Reviewers had to scroll through hundreds of flat lines instead of scanning a body shaped by GFM features.

Concision targets (hard ceilings)

The skill aims for 150-220 lines for a typical PR body. 300+ lines is a smell, not a virtue. If your draft exceeds 250 lines, run a tightening pass: every sentence that does not change the reviewer's understanding must be cut.

Per-section ceilings (enforced by assets/section-rubric.md):

Long verbatim quote blocks, full file listings, and full validation transcripts SHOULD live inside <details> so the body stays scannable.

Core principles (with quoted anchors)

Each rule the skill enforces is backed by a verbatim quote from one of the two reference docs. If a rule below cannot be backed by a quote, it is downgraded to a "should" with the reason given.

1. Self-sufficient body. A reviewer must be able to read the PR body and form an opinion without opening any other doc, issue, or chat. Every WHY-claim cites the source doc inline; every named file is qualified with what changed in it; every diagram has a one-sentence legend.

   Anchor: Agent Skills, "agents pattern-match well against concrete structures".

2. Anchored: every WHY-claim cites its source. Every claim of the form "this violates X" or "this satisfies Y" is followed by a verbatim quoted phrase wrapped in a hyperlink to the source page. Reproduce quotes character-for-character; do not paraphrase inside link text.

   Anchor: PROSE, "Grounding outputs in deterministic tool execution transforms probabilistic generation into verifiable action.".

3. Cite-or-omit. If a WHY-claim cannot be backed by a verbatim quote, drop it or soften to a tradeoff statement. Never invent justification.

   Anchor: Agent Skills, "Add what the agent lacks, omit what it knows".

4. Visual aid where structure is non-trivial. Any change that touches more than one file or alters control flow SHOULD include at least one mermaid diagram. Add a second only when the relationships are non-trivial. Never add a third unless it earns its place. Each diagram MUST be preceded by a one-sentence legend.

   Anchor: Agent Skills, "agents pattern-match well against concrete structures".

5. Trade-offs explicit. Address every non-obvious decision (option chosen vs option rejected). For mechanical PRs this section may be 1-2 bullets. For cross-cutting changes, surface the rejected alternatives.

   Anchor: PROSE, "Favor small, chainable primitives over monolithic frameworks.".

6. Single artifact, no fluff. One markdown file. No marketing tone, no self-congratulation. TL;DR is at most four sentences.

   Anchor: Agent Skills, "When you find yourself covering every edge case, consider whether most are better handled by the agent's own judgment.".

GitHub-Flavored Markdown features the skill MUST use

The PR body is rendered by GitHub's Primer engine. Use the features that engine provides; do not flatten the output to plain text.

• Alerts for high-signal callouts: > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION]. Reference: https://github.com/orgs/community/discussions/16925.

• Collapsible sections for long diffs, full validation output, or appendix material:

  <details><summary>Full audit output</summary>
  
  ...content...
  </details>

  Use <details open> only when the content answers the most likely first reviewer question.

• Task lists for "How to test" sections: - [ ] Apply label, observe X.

• Tables with alignment: | col | :---: | ---: | for matrices.

• Permalink references to specific lines in the diff: https://github.com/microsoft/apm/blob/<sha>/path#L12-L34.

Long verbatim quote blocks, full file listings, and full validation transcripts SHOULD live inside <details> so the body stays scannable.

Required body structure

The Trade-offs (7) and How to test (10) sections are non-skippable for any PR that changes more than docs.

Activation contract -- inputs the orchestrator MUST gather first

Before invoking this skill, the orchestrator MUST have collected all of the following. The skill MUST NOT invent facts not present in these inputs.

If any required input is missing, the orchestrator MUST stop and collect it. This is a Progressive Disclosure boundary: "Context arrives just-in-time, not just-in-case.". Do not load assets/pr-body-template.md until the table above is complete.