Use this skill to write the PR description (PR body) for any pull request opened against microsoft/apm. Produces one self-sufficient GitHub-Flavored Markdown artifact: TL;DR, Problem (WHY), Approach (WHAT), Implementation (HOW), 1-3 validated mermaid diagrams, explicit trade-offs, validation evidence, and a How-to-test section -- with every WHY-claim backed by a verbatim quote from PROSE or Agent Skills. Activate when the user asks to "write a PR description", "draft a PR body", "open a PR", "fill in the PR template", or any equivalent.
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:
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.
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):
Section
Ceiling
TL;DR
2-4 sentences
Problem (WHY)
max 6 bullets, max 3 quoted anchors total
Approach (WHAT)
a table OR 3-7 bullets; may be skipped if PR is purely additive (say "additive: see Implementation")
Implementation (HOW)
one short paragraph per file, OR a table; no prose walls
Diagrams
1-3 mermaid blocks; every diagram preceded by a one-sentence legend
Trade-offs
3-5 bullets; mechanical PRs may be 1-2
Benefits
3-5 numbered items, each measurable
Validation
copy-paste real command output; do not narrate
How to test
max 5 numbered steps
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.
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.
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.
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.
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.
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
#
Section
Purpose
1
Title line
Imperative summary; first line <verb>(<scope>): <summary>, max 100 chars
2
TL;DR
2-4 sentence executive summary
3
Problem (WHY)
Observed failure modes; max 6 bullets, max 3 quoted anchors
4
Approach (WHAT)
Table or 3-7 bullets; may say "additive: see Implementation"
5
Implementation (HOW)
One short paragraph per file or a table
6
Diagrams
1-3 validated mermaid blocks, each with a legend; diagram type chosen per intent (assets/mermaid-conventions.md)
7
Trade-offs
3-5 bullets (1-2 if mechanical)
8
Benefits
3-5 numbered, measurable items
9
Validation
Real command output, ideally inside <details> if long; MUST include the Scenario Evidence subsection (assets/scenario-evidence-rubric.md) for any behavior-change PR -- maps each user-promise scenario this PR touches to the test that proves it works, tagged with the APM principle the scenario serves
10
How to test
Max 5 numbered or task-list steps
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.
Input
Source
Required
Branch name (head)
git rev-parse --abbrev-ref HEAD
yes
Base ref
usually main; ask if unclear
yes
List of files changed
git diff --name-status <base>...HEAD
yes
Actual diff
git diff <base>...HEAD
yes
Commit messages on the branch
git log --no-merges <base>..HEAD --oneline
yes
CHANGELOG entry, if any
inspect CHANGELOG.md Unreleased section
yes
Linked issue / motivation
user-provided or referenced in commits
yes
Validation evidence
output of apm audit --ci, uv run pytest, or equivalent
yes
Scenario-test mapping
author-supplied or derived from diff: per user-promise scenario the PR touches, the test path proving it, plus the APM principle the scenario serves (taxonomy in assets/scenario-evidence-rubric.md)
conditional (required for any behavior-change PR; may be skipped for docs-only / asset-bump / pure-refactor per the rubric's skip clause, with the skip case stated in trade-offs)
Mirror parity check, if applicable
apm install --target copilot output
conditional
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.
Execution checklist
Run these steps in order. Tick each before moving on.
Confirm every row of the activation contract is filled in.
Defense-in-depth gate: before drafting the body, confirm the
repo's lint contract is green (canonical commands and lifecycle
binding live in .apm/instructions/linting.instructions.md). If lint is red,
STOP, fix, re-run; a PR body claiming green CI while lint fails
is a credibility tax we refuse to take on.
Read the diff in full. Identify per-file change summary,
new files, deleted files, behavior changes at module
boundaries.
Fill in the template top-to-bottom using only facts from
the activation contract. Every WHY-claim gets a verbatim
quoted anchor. If you cannot anchor a claim, drop it.
Generate 1-3 mermaid diagrams. Before drafting any block,
load assets/mermaid-conventions.md to pick the right
diagram type per intent (sequenceDiagram for execution flow,
flowchart LR for pipeline / architecture, stateDiagram-v2 for
state machines) and apply the boxing convention for NEW
behavior. Add a one-sentence legend above each diagram.
Validate every mermaid block deterministically (see
below). Do NOT save the draft until every block validates.
Run the line-count check. If the body exceeds 250 lines,
tighten until it fits 150-220.
Write the final body to a single file path provided by the
orchestrator (default: .git/PR_BODY.md or
session-state-relative). Return the path; do not paste the
body inline unless explicitly asked.
Mandatory mermaid validation step
Run every mermaid block in the draft through mmdc and refuse to
save until all pass.
# Extract mermaid blocks and validate each one.
# Requires: npx --yes -p @mermaid-js/mermaid-cli mmdc (one-shot, no global install needed)
awk '/^```mermaid/{n++; f=outdir"/diag"n".mmd"; getline; while($0 != "```") {print > f; getline}}' outdir=/tmp/mermaid-check pr-body-draft.md
for f in /tmp/mermaid-check/diag*.mmd; do
npx --yes -p @mermaid-js/mermaid-cli mmdc -i "$f" -o "${f%.mmd}.svg" --quiet || { echo "INVALID: $f"; exit 1; }
done
If mmdc reports any error, fix the diagram and re-run. The skill
MUST NOT save the draft until every mermaid block validates.
Diagram type and pitfalls reference
The full diagram-type-by-intent table, canonical templates, and the
GitHub-renderer gotcha list (mmdc does NOT always catch GitHub
rejections) live in assets/mermaid-conventions.md. Load it whenever
a PR body needs a mermaid block.
Critical drift-known gotcha (the one most likely to bite, captured
inline because it is not obvious from mmdc output):
Square brackets in flowchart edge labels MUST be quoted.A -->|[EXEC] work| B parses on mmdc but is rejected by
GitHub's renderer (Expecting 'TAGEND', ..., got 'SQS'). Quote
the label: A -->|"[EXEC] work"| B. The same rule applies to
parentheses, colons, slashes, and pipes in edge labels.
For everything else (semicolons in classDiagram links, note right of closing rules, round brackets in node labels, inline
:::cssClass failing in classDiagram on GitHub), see
assets/mermaid-conventions.md.
Output contract
Exactly ONE markdown file is produced.
The file is UTF-8 GitHub-Flavored Markdown. Em dashes, smart
quotes, Unicode in mermaid labels, alerts, and collapsibles are
all permitted and encouraged where they improve readability.
Every mermaid block has been validated by mmdc and renders
without error.
The cite-or-omit rule applies absolutely.
The TL;DR is at most four sentences.
The body ends with the trailer:
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Anti-patterns flagged -- refuse these
Posting unvalidated mermaid. A parser error renders as raw
code on GitHub and signals carelessness. Validate every block
before saving.
Pasting commit messages as the body. Commit messages are inputs,
not output.
Marketing tone or self-congratulation ("this is a great
improvement", "significantly enhances", "best-in-class"). Strip
on sight.
Diagrams without a legend, OR diagrams that fail mmdc.
A TL;DR longer than four sentences.
Skipping any required section because "the PR is small". A small
PR can have a one-line Implementation per file, but the section
header must still be present.
Restating the diff line-by-line in Implementation. That is what
the Files Changed tab is for.
Quoting a doc out of context. The self-check pass must verify
that the quoted phrase actually supports the claim.
Forcing ASCII-only on the PR body. That rule applies to
source files and CLI output, not to Primer-rendered markdown.
See "Output charset rule" above.
Gotchas
Do not restate the diff. Implementation is for intent, risk,
and decisions -- not a textual re-rendering of the patch.
Do not quote out of context. Re-read the surrounding paragraph
of the source doc before pasting a quote.
Verify the source URL still serves the quoted text. If the
doc has been edited and the phrase no longer appears verbatim,
drop the citation or find a new anchor.
A doc-only PR still needs TL;DR, Problem, Validation, and
How-to-test. "The PR is trivial" is not an exemption.
Long evidence belongs in <details>. Reviewers should be
able to read the whole body in a single screen-and-a-half scroll
and expand evidence on demand.
1---2name: pr-description-skill3description: >-4 Use this skill to write the PR description (PR body) for any pull5 request opened against microsoft/apm. Produces one self-sufficient6 GitHub-Flavored Markdown artifact: TL;DR, Problem (WHY), Approach7 (WHAT), Implementation (HOW), 1-3 validated mermaid diagrams,8 explicit trade-offs, validation evidence, and a How-to-test9 section -- with every WHY-claim backed by a verbatim quote from10 PROSE or Agent Skills. Activate when the user asks to "write a PR11 description", "draft a PR body", "open a PR", "fill in the PR12 template", or any equivalent.13metadata:14 source: https://skillmd.com/skills/microsoft/pr-description-skill15---1617# PR Description Skill -- Anchored, Concise, Validated PR Bodies1819## When to use2021Trigger this skill on any of the following intents:2223- "write a PR description"24- "draft a PR body"25- "open a PR" / "open this PR" / "let's open the PR"26- "fill in the PR template"27- "summarize this branch as a PR"28- "create the PR write-up"2930Reusable for any PR against `microsoft/apm`. The output is one31markdown file that the orchestrator pastes into32`gh pr create --body-file` or surfaces to the maintainer.3334## Output charset rule (read this first)3536The repo-wide encoding rule at37`.github/instructions/encoding.instructions.md` constrains38**source files and CLI output** to printable ASCII because Windows39cp1252 terminals raise `UnicodeEncodeError` on anything else. PR40comments are NOT source code and NOT CLI output -- they are rendered41by GitHub's Primer engine, which expects UTF-8 GitHub-Flavored42Markdown.4344Two distinct rules therefore apply:45461. **Source files in this bundle** (`SKILL.md`, `assets/*`) MUST47 stay ASCII. They live in the repo and are subject to48 `.github/instructions/encoding.instructions.md`.492. **The PR body output the skill produces** MUST be UTF-850 GitHub-Flavored Markdown. Use em dashes, smart punctuation,51 alerts, collapsibles, task lists, and Unicode where it improves52 readability. Mermaid diagram labels MAY use Unicode -- there is53 no constraint here. The output is consumed by GitHub's renderer,54 not by a Windows terminal.5556A previous version of this skill incorrectly required ASCII in the57PR body. That made the output unreadable: no alerts, no collapsibles58for long evidence, no em dashes, no smart quotes. Reviewers had to59scroll through hundreds of flat lines instead of scanning a body60shaped by GFM features.6162## Concision targets (hard ceilings)6364The skill aims for **150-220 lines** for a typical PR body. **300+65lines is a smell, not a virtue**. If your draft exceeds 250 lines,66run a tightening pass: every sentence that does not change the67reviewer's understanding must be cut.6869Per-section ceilings (enforced by `assets/section-rubric.md`):7071| Section | Ceiling |72|---|---|73| TL;DR | 2-4 sentences |74| Problem (WHY) | max 6 bullets, max 3 quoted anchors total |75| Approach (WHAT) | a table OR 3-7 bullets; may be skipped if PR is purely additive (say "additive: see Implementation") |76| Implementation (HOW) | one short paragraph per file, OR a table; no prose walls |77| Diagrams | 1-3 mermaid blocks; every diagram preceded by a one-sentence legend |78| Trade-offs | 3-5 bullets; mechanical PRs may be 1-2 |79| Benefits | 3-5 numbered items, each measurable |80| Validation | copy-paste real command output; do not narrate |81| How to test | max 5 numbered steps |8283Long verbatim quote blocks, full file listings, and full validation84transcripts SHOULD live inside `<details>` so the body stays85scannable.8687## Core principles (with quoted anchors)8889Each rule the skill enforces is backed by a verbatim quote from one90of the two reference docs. If a rule below cannot be backed by a91quote, it is downgraded to a "should" with the reason given.92931. **Self-sufficient body.** A reviewer must be able to read the PR94 body and form an opinion without opening any other doc, issue,95 or chat. Every WHY-claim cites the source doc inline; every96 named file is qualified with what changed in it; every diagram97 has a one-sentence legend.9899 Anchor: Agent Skills,100 ["agents pattern-match well against concrete structures"](https://agentskills.io/skill-creation/best-practices).1011022. **Anchored: every WHY-claim cites its source.** Every claim of103 the form "this violates X" or "this satisfies Y" is followed by104 a verbatim quoted phrase wrapped in a hyperlink to the source105 page. Reproduce quotes character-for-character; do not paraphrase106 inside link text.107108 Anchor: PROSE,109 ["Grounding outputs in deterministic tool execution transforms probabilistic generation into verifiable action."](https://danielmeppiel.github.io/awesome-ai-native/docs/prose/).1101113. **Cite-or-omit.** If a WHY-claim cannot be backed by a verbatim112 quote, drop it or soften to a tradeoff statement. Never invent113 justification.114115 Anchor: Agent Skills,116 ["Add what the agent lacks, omit what it knows"](https://agentskills.io/skill-creation/best-practices).1171184. **Visual aid where structure is non-trivial.** Any change that119 touches more than one file or alters control flow SHOULD include120 at least one mermaid diagram. Add a second only when the121 relationships are non-trivial. Never add a third unless it earns122 its place. Each diagram MUST be preceded by a one-sentence legend.123124 Anchor: Agent Skills,125 ["agents pattern-match well against concrete structures"](https://agentskills.io/skill-creation/best-practices).1261275. **Trade-offs explicit.** Address every non-obvious decision128 (option chosen vs option rejected). For mechanical PRs this129 section may be 1-2 bullets. For cross-cutting changes, surface130 the rejected alternatives.131132 Anchor: PROSE,133 ["Favor small, chainable primitives over monolithic frameworks."](https://danielmeppiel.github.io/awesome-ai-native/docs/prose/).1341356. **Single artifact, no fluff.** One markdown file. No marketing136 tone, no self-congratulation. TL;DR is at most four sentences.137138 Anchor: Agent Skills,139 ["When you find yourself covering every edge case, consider whether most are better handled by the agent's own judgment."](https://agentskills.io/skill-creation/best-practices).140141## GitHub-Flavored Markdown features the skill MUST use142143The PR body is rendered by GitHub's Primer engine. Use the features144that engine provides; do not flatten the output to plain text.145146- **Alerts** for high-signal callouts:147 `> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`,148 `> [!CAUTION]`. Reference:149 https://github.com/orgs/community/discussions/16925.150- **Collapsible sections** for long diffs, full validation output,151 or appendix material:152153 ```154 <details><summary>Full audit output</summary>155156 ...content...157 </details>158 ```159160 Use `<details open>` only when the content answers the most161 likely first reviewer question.162- **Task lists** for "How to test" sections:163 `- [ ] Apply label, observe X`.164- **Tables with alignment**: `| col | :---: | ---: |` for matrices.165- **Permalink references** to specific lines in the diff:166 `https://github.com/microsoft/apm/blob/<sha>/path#L12-L34`.167168Long verbatim quote blocks, full file listings, and full validation169transcripts SHOULD live inside `<details>` so the body stays170scannable.171172## Required body structure173174| # | Section | Purpose |175|---|---------|---------|176| 1 | Title line | Imperative summary; first line `<verb>(<scope>): <summary>`, max 100 chars |177| 2 | TL;DR | 2-4 sentence executive summary |178| 3 | Problem (WHY) | Observed failure modes; max 6 bullets, max 3 quoted anchors |179| 4 | Approach (WHAT) | Table or 3-7 bullets; may say "additive: see Implementation" |180| 5 | Implementation (HOW) | One short paragraph per file or a table |181| 6 | Diagrams | 1-3 validated mermaid blocks, each with a legend; diagram type chosen per intent (`assets/mermaid-conventions.md`) |182| 7 | Trade-offs | 3-5 bullets (1-2 if mechanical) |183| 8 | Benefits | 3-5 numbered, measurable items |184| 9 | Validation | Real command output, ideally inside `<details>` if long; **MUST include the Scenario Evidence subsection** (`assets/scenario-evidence-rubric.md`) for any behavior-change PR -- maps each user-promise scenario this PR touches to the test that proves it works, tagged with the APM principle the scenario serves |185| 10 | How to test | Max 5 numbered or task-list steps |186187The Trade-offs (7) and How to test (10) sections are non-skippable188for any PR that changes more than docs.189190## Activation contract -- inputs the orchestrator MUST gather first191192Before invoking this skill, the orchestrator MUST have collected193all of the following. The skill MUST NOT invent facts not present194in these inputs.195196| Input | Source | Required |197|-------|--------|----------|198| Branch name (head) | `git rev-parse --abbrev-ref HEAD` | yes |199| Base ref | usually `main`; ask if unclear | yes |200| List of files changed | `git diff --name-status <base>...HEAD` | yes |201| Actual diff | `git diff <base>...HEAD` | yes |202| Commit messages on the branch | `git log --no-merges <base>..HEAD --oneline` | yes |203| CHANGELOG entry, if any | inspect `CHANGELOG.md` Unreleased section | yes |204| Linked issue / motivation | user-provided or referenced in commits | yes |205| Validation evidence | output of `apm audit --ci`, `uv run pytest`, or equivalent | yes |206| Scenario-test mapping | author-supplied or derived from diff: per user-promise scenario the PR touches, the test path proving it, plus the APM principle the scenario serves (taxonomy in `assets/scenario-evidence-rubric.md`) | conditional (required for any behavior-change PR; may be skipped for docs-only / asset-bump / pure-refactor per the rubric's skip clause, with the skip case stated in trade-offs) |207| Mirror parity check, if applicable | `apm install --target copilot` output | conditional |208209If any required input is missing, the orchestrator MUST stop and210collect it. This is a Progressive Disclosure boundary:211["Context arrives just-in-time, not just-in-case."](https://danielmeppiel.github.io/awesome-ai-native/docs/prose/).212Do not load `assets/pr-body-template.md` until the table above is213complete.214215## Execution checklist216217Run these steps in order. Tick each before moving on.2182191. [ ] Confirm every row of the activation contract is filled in.220 Defense-in-depth gate: before drafting the body, confirm the221 repo's lint contract is green (canonical commands and lifecycle222 binding live in `.apm/instructions/linting.instructions.md`). If lint is red,223 STOP, fix, re-run; a PR body claiming green CI while lint fails224 is a credibility tax we refuse to take on.2252. [ ] Read the diff in full. Identify per-file change summary,226 new files, deleted files, behavior changes at module227 boundaries.2283. [ ] Load `assets/pr-body-template.md`. This is the only point229 at which the template enters context. Progressive Disclosure230 in action:231 ["store them in `assets/` and reference them from `SKILL.md` so they only load when needed."](https://agentskills.io/skill-creation/best-practices).2324. [ ] Fill in the template top-to-bottom using only facts from233 the activation contract. Every WHY-claim gets a verbatim234 quoted anchor. If you cannot anchor a claim, drop it.2355. [ ] Generate 1-3 mermaid diagrams. **Before drafting any block,236 load `assets/mermaid-conventions.md`** to pick the right237 diagram type per intent (sequenceDiagram for execution flow,238 flowchart LR for pipeline / architecture, stateDiagram-v2 for239 state machines) and apply the boxing convention for NEW240 behavior. Add a one-sentence legend above each diagram.2416. [ ] **Validate every mermaid block deterministically (see242 below). Do NOT save the draft until every block validates.**2437. [ ] Load `assets/section-rubric.md` and run the self-check pass.244 Validation loop pattern from Agent Skills:245 ["do the work, run a validator (a script, a reference checklist, or a self-check), fix any issues, and repeat until validation passes."](https://agentskills.io/skill-creation/best-practices).2468. [ ] Run the line-count check. If the body exceeds 250 lines,247 tighten until it fits 150-220.2489. [ ] Write the final body to a single file path provided by the249 orchestrator (default: `.git/PR_BODY.md` or250 session-state-relative). Return the path; do not paste the251 body inline unless explicitly asked.252253## Mandatory mermaid validation step254255Run every mermaid block in the draft through `mmdc` and refuse to256save until all pass.257258```bash259# Extract mermaid blocks and validate each one.260# Requires: npx --yes -p @mermaid-js/mermaid-cli mmdc (one-shot, no global install needed)261awk '/^```mermaid/{n++; f=outdir"/diag"n".mmd"; getline; while($0 != "```") {print > f; getline}}' outdir=/tmp/mermaid-check pr-body-draft.md262for f in /tmp/mermaid-check/diag*.mmd; do263 npx --yes -p @mermaid-js/mermaid-cli mmdc -i "$f" -o "${f%.mmd}.svg" --quiet || { echo "INVALID: $f"; exit 1; }264done265```266267If `mmdc` reports any error, fix the diagram and re-run. The skill268MUST NOT save the draft until every mermaid block validates.269270### Diagram type and pitfalls reference271272The full diagram-type-by-intent table, canonical templates, and the273GitHub-renderer gotcha list (`mmdc` does NOT always catch GitHub274rejections) live in `assets/mermaid-conventions.md`. Load it whenever275a PR body needs a mermaid block.276277Critical drift-known gotcha (the one most likely to bite, captured278inline because it is not obvious from `mmdc` output):279280- **Square brackets in flowchart edge labels MUST be quoted.**281 `A -->|[EXEC] work| B` parses on `mmdc` but is rejected by282 GitHub's renderer (`Expecting 'TAGEND', ..., got 'SQS'`). Quote283 the label: `A -->|"[EXEC] work"| B`. The same rule applies to284 parentheses, colons, slashes, and pipes in edge labels.285286For everything else (semicolons in classDiagram links, `note right287of` closing rules, round brackets in node labels, inline288`:::cssClass` failing in classDiagram on GitHub), see289`assets/mermaid-conventions.md`.290291## Output contract292293- Exactly ONE markdown file is produced.294- The file is **UTF-8 GitHub-Flavored Markdown**. Em dashes, smart295 quotes, Unicode in mermaid labels, alerts, and collapsibles are296 all permitted and encouraged where they improve readability.297- Every mermaid block has been validated by `mmdc` and renders298 without error.299- The cite-or-omit rule applies absolutely.300- The TL;DR is at most four sentences.301- The body ends with the trailer:302 `Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>`303304## Anti-patterns flagged -- refuse these305306- **Posting unvalidated mermaid.** A parser error renders as raw307 code on GitHub and signals carelessness. Validate every block308 before saving.309- Pasting commit messages as the body. Commit messages are inputs,310 not output.311- Marketing tone or self-congratulation ("this is a great312 improvement", "significantly enhances", "best-in-class"). Strip313 on sight.314- Diagrams without a legend, OR diagrams that fail `mmdc`.315- A TL;DR longer than four sentences.316- Skipping any required section because "the PR is small". A small317 PR can have a one-line Implementation per file, but the section318 header must still be present.319- Restating the diff line-by-line in Implementation. That is what320 the Files Changed tab is for.321- Quoting a doc out of context. The self-check pass must verify322 that the quoted phrase actually supports the claim.323- **Forcing ASCII-only on the PR body.** That rule applies to324 source files and CLI output, not to Primer-rendered markdown.325 See "Output charset rule" above.326327## Gotchas328329- **Do not restate the diff.** Implementation is for intent, risk,330 and decisions -- not a textual re-rendering of the patch.331- **Do not quote out of context.** Re-read the surrounding paragraph332 of the source doc before pasting a quote.333- **Verify the source URL still serves the quoted text.** If the334 doc has been edited and the phrase no longer appears verbatim,335 drop the citation or find a new anchor.336- **A doc-only PR still needs TL;DR, Problem, Validation, and337 How-to-test.** "The PR is trivial" is not an exemption.338- **Long evidence belongs in `<details>`.** Reviewers should be339 able to read the whole body in a single screen-and-a-half scroll340 and expand evidence on demand.341342Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Run npx get-skill add microsoft/pr-description-skill in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Use this skill to write the PR description (PR body) for any pull request opened against microsoft/apm. Produces one self-sufficient GitHub-Flavored Markdown artifact: TL;DR, Problem (WHY), Approach (WHAT), Implementation (HOW), 1-3 validated mermaid diagrams, explicit trade-offs, validation evidence, and a How-to-test section -- with every WHY-claim backed by a verbatim quote from PROSE or Agent Skills. Activate when the user asks to "write a PR description", "draft a PR body", "open a PR", "fill in the PR template", or any equivalent. It is listed under AI & ML on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: CAUTION, Skill Scanner: PASS. Capability flags: executes scripts, makes network calls. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
Microsoft (@microsoft) published this skill. Their other Agent Skills are listed on their SkillMD profile.