CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

75

Quality

92%

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

SKILL.md
Quality
Evals
Security

Quality

Content

85%Weight 40%Scale 1-3

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

The body is highly actionable with a well-sequenced, validation-gated workflow and exemplary progressive disclosure into real bundle files. Its one weakness is conciseness: some historical justification and a duplicated sentence add tokens that do not change the agent's understanding.

Suggestions

Remove the 'A previous version of this skill incorrectly required ASCII...' paragraph (and the related restatement in Anti-patterns) -- the rule is already stated; the history does not change the agent's behavior.

Delete the duplicate 'Long verbatim quote blocks, full file listings, and full validation transcripts SHOULD live inside <details>' sentence (it appears in both 'Concision targets' and 'GitHub-Flavored Markdown features').

Tighten the Output charset rule section: the two-rule split is useful, but the prose explaining why the old approach failed can be cut to the rule itself plus the one-sentence rationale.

DimensionReasoningScore

Conciseness

The body is mostly efficient and actionable, but contains padding that could be tightened -- the 'A previous version of this skill incorrectly required ASCII...' historical justification paragraph, and the sentence 'Long verbatim quote blocks, full file listings, and full validation transcripts SHOULD live inside <details>' which is repeated verbatim in two sections. It is not a 3 because not every token earns its place; it is not a 1 because it largely assumes Claude's competence and avoids explaining basic concepts.

2 / 3

Actionability

Provides fully executable, copy-paste-ready guidance -- the mmdc/awk mermaid-validation bash block, concrete git commands in the activation contract table ('git rev-parse --abbrev-ref HEAD', 'git diff --name-status <base>...HEAD'), exact GFM syntax examples, and a precise section-structure table with hard ceilings. It is not a 2 because the code and commands are complete and executable rather than pseudocode.

3 / 3

Workflow Clarity

The 9-step Execution Checklist is clearly sequenced with explicit validation checkpoints and feedback loops -- a lint gate ('STOP, fix, re-run'), mandatory mermaid validation ('refuse to save until all pass'), a self-check pass, and a line-count tightening loop. It is not a 2 because checkpoints are explicit with error-recovery loops, not merely an implicit list.

3 / 3

Progressive Disclosure

SKILL.md is an overview that defers detail to one-level-deep, well-signaled bundle files (assets/section-rubric.md, mermaid-conventions.md, pr-body-template.md, scenario-evidence-rubric.md), each loaded at a specific execution step ('This is the only point at which the template enters context'). All referenced asset paths resolve to real files. It is not a 2 because references are clearly signaled and appropriately split rather than inlined or nested.

3 / 3

Total

11

/

12

Passed

Description

100%Weight 40%Scale 1-3

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

The description is strong: it states a concrete, scoped output artifact, enumerates the sections it produces, and gives explicit natural-language triggers. It cleanly answers both what and when with no vague fluff.

DimensionReasoningScore

Specificity

Lists multiple concrete actions and output components -- 'write the PR description (PR body)', 'TL;DR, Problem (WHY), Approach (WHAT), Implementation (HOW), 1-3 validated mermaid diagrams, explicit trade-offs, validation evidence, and a How-to-test section' -- matching the 'lists multiple specific concrete actions' anchor. It is not a 2 because the catalog of produced sections is comprehensive and specific rather than a partial naming of the domain.

3 / 3

Completeness

Explicitly answers both what ('Produces one self-sufficient GitHub-Flavored Markdown artifact...') and when ('Activate when the user asks to...') with explicit triggers, matching the 'clearly answers both what AND when' anchor. It is not a 2 because the when-clause is explicit, not merely implied.

3 / 3

Trigger Term Quality

Provides natural trigger phrases a user would actually say -- 'write a PR description', 'draft a PR body', 'open a PR', 'fill in the PR template', 'or any equivalent' -- giving good coverage of common variations. It is not a 2 because multiple natural phrasings are enumerated rather than a single generic keyword.

3 / 3

Distinctiveness Conflict Risk

Scoped to 'any pull request opened against microsoft/apm' with a distinct, narrow output artifact and trigger set, making conflict with other skills unlikely. It is not a 2 because the niche (PR-body authoring for a specific repo) is clearly bounded rather than overlapping with general writing skills.

3 / 3

Total

12

/

12

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.

Validation16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository
microsoft/apm
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.