CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

pr-description-skill

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.

Quality

87%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

The canonical home for this skill is pr-description-skill in microsoft/apm

SKILL.md
Quality
Evals
Security

Quality

Content

81%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

An unusually actionable, well-sequenced skill: exact commands, hard validation gates with feedback loops, and real referenced assets loaded at the right moments. Its weakness is redundancy -- duplicated guidance, two overlapping section-limit tables, and historical narrative -- that pushes the body past 300 lines when the content justifies well under 250.

Suggestions

Deduplicate the repeated '<details>' guidance, merge the 'Concision targets' ceilings table into the single 'Required body structure' table, and delete the 'A previous version of this skill incorrectly required ASCII' paragraph (keep only the current rule) -- that alone should cut 40-60 lines.

Move the multi-paragraph 'Output charset rule' rationale into an asset (or fold it into the output contract as two rules) so SKILL.md keeps only the decision, matching how mermaid gotchas are split into assets/mermaid-conventions.md.

Consolidate 'Anti-patterns flagged' and 'Gotchas' into one section; several entries ('restating the diff', 'quoting out of context') appear in both lists.

DimensionReasoningScore

Conciseness

The body is mostly dense, repo-specific rule-making (charset boundary, per-section ceilings, mermaid gotchas) that Claude cannot infer, but there is real duplication: 'Long verbatim quote blocks, full file listings, and full validation transcripts SHOULD live inside <details>' appears verbatim twice; the per-section ceilings table and the 'Required body structure' table restate overlapping limits; and the 'A previous version of this skill incorrectly required ASCII' paragraph is history that earns no tokens. This matches the score-3 anchor (mostly efficient but could be tightened) rather than 4, where only minor trimming would be needed.

3 / 5

Actionability

Guidance is fully executable: exact input-gathering commands ('git diff --name-status <base>...HEAD', 'git log --no-merges <base>..HEAD --oneline'), a copy-paste mmdc validation loop with a real awk extraction one-liner, an exact trailer line, and a concrete drift example ('A -->|"[EXEC] work"| B'). The common case (draft a PR body, validate diagrams, self-check) is covered with commands Claude can run as written.

5 / 5

Workflow Clarity

The execution checklist is a clear ordered 9-step sequence with explicit validation checkpoints and feedback loops: a lint STOP gate before drafting ('If lint is red, STOP, fix, re-run'), mandatory mermaid validation with a fix-and-rerun loop ('If mmdc reports any error, fix the diagram and re-run'), a rubric-based self-check pass, and a line-count tightening loop. This matches the score-5 anchor including error-recovery loops and a checklist.

5 / 5

Progressive Disclosure

All four referenced assets (assets/pr-body-template.md, assets/mermaid-conventions.md, assets/section-rubric.md, assets/scenario-evidence-rubric.md) exist and are one level deep, each with an explicit load point tied to a step ('Load assets/mermaid-conventions.md before drafting any block'). However, the 325-line body itself carries content that belongs in those assets -- the 28-line charset rationale and the anti-patterns/gotchas overlap -- so this is good structure with minor organization gaps rather than the clean split of the score-5 anchor.

4 / 5

Total

17

/

20

Passed

Description

88%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: it states a concrete, comprehensive what and an explicit when with natural trigger phrases, and scopes itself to a single repo. Its only weaknesses are a few missing trigger synonyms and a trigger ('open a PR') that overlaps with PR-creation rather than PR-description intent.

DimensionReasoningScore

Specificity

The description enumerates the concrete deliverable in full: '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'. It names multiple specific concrete actions and comprehensively covers what the skill produces, matching the score-5 anchor; nothing remains vague.

5 / 5

Completeness

It explicitly answers both questions: what ('Use this skill to write the PR description (PR body) ... Produces one self-sufficient GitHub-Flavored Markdown artifact' with the section list) and when ('Activate when the user asks to "write a PR description", ... or any equivalent'). This is a clear match for the score-5 anchor with concrete trigger phrases.

5 / 5

Trigger Term Quality

Natural trigger phrases are present and phrased as users would say them: 'write a PR description', 'draft a PR body', 'open a PR', 'fill in the PR template'. This is good keyword coverage per the score-4 anchor, but common variations the body itself lists ('summarize this branch as a PR', 'create the PR write-up', 'PR summary') are missing from the description, so it falls short of the comprehensive-synonyms anchor at 5.

4 / 5

Distinctiveness Conflict Risk

The niche is distinct (PR bodies for microsoft/apm with an anchored-quotes requirement), but the trigger 'open a PR' also naturally matches skills that actually create/open pull requests, whereas this skill only writes the body. That is minor overlap risk with a closely related skill, matching the score-4 anchor rather than the minimal-conflict anchor at 5.

4 / 5

Total

18

/

20

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

microsoft/apm

Path

packages/pr-description-skill/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.