// Use this skill when creating or writing a pull request description. Invoke automatically when: the user says "create a PR", "open a pull request", "submit for review", "write the PR body", or "push this for review". If the PR includes UI changes, invoke the capture-screenshots skill before writing the description.
| name | create-pr |
| description | Use this skill when creating or writing a pull request description. Invoke automatically when: the user says "create a PR", "open a pull request", "submit for review", "write the PR body", or "push this for review". If the PR includes UI changes, invoke the capture-screenshots skill before writing the description. |
| argument-hint | [linear-issue-id] |
| disable-model-invocation | false |
| user-invocable | true |
| allowed-tools | Bash, Read, Glob, Grep, mcp__linear-server__get_issue |
Structured approach for writing effective, user-centric pull request descriptions.
Rule: The PR description is for understanding user value and testing the change — not for explaining how the code works.
Invoke this skill when:
gh pr createIf the PR includes UI changes: invoke the capture-screenshots skill before writing the description.
Use mcp__linear-server__get_issue with the issue identifier:
# Returns the full issue URL needed for the PR header
mcp__linear-server__get_issue(id: "EDG-40")
If this PR touches any UI: run the capture-screenshots skill first (--for pr).
Screenshots must appear in the AFTER section before submitting.
Audience: Product managers, designers, and developers — not just technical reviewers.
| Do | Avoid |
|---|---|
| Start with what users gain | Replicating the Linear ticket |
| Use plain language | Technical jargon in the opening |
| Screenshot first, explain second | Code snippets in the description |
| State explicit user benefits | Vague improvements ("better UX") |
Opening formula:
This PR [transforms/enhances/improves] how users [do something].
Previously, [limitation]. Now, [new capability].
Good: "This PR transforms how users understand their data pipelines by showing both runtime and configuration status through intuitive visual feedback."
Bad: "This PR implements a dual-status model with Runtime and Operational enums and refactors 10 node components."
# Pull Request: [User-facing feature name]
**Linear Issue:** https://linear.app/hivemq/issue/[ISSUE-ID]/[slug]
---
## Description
[Opening paragraph — user value proposition]
The enhancement introduces:
- **[Key improvement]**: [User-facing description]
- **[Key improvement]**: [User-facing description]
### User Experience Improvements
**What users gain:**
- **[Benefit]**: [How it helps]
- **[Benefit]**: [How it helps]
### Technical Summary
- [High-level point, no code]
- [High-level point, no code]
---
## BEFORE
### Previous behavior
[One paragraph + 3–5 limitation bullets]
---
## AFTER
### New behavior
#### 1. [Scenario name]
_Test: `cypress/e2e/[path]/[file].spec.cy.ts`_
_Screenshot: 1400×1016 viewport_
**Key Visual Elements:**
- **[Element]**: [What it shows]
**User Benefits:** [One paragraph]
---
## Test Coverage
- **[X]+ tests total, all passing ✅**
- **Unit tests**: [What they cover]
- **E2E tests**: [What they cover]
---
## Breaking Changes
None. / [List with compatibility notes]
---
## Accessibility
- ✅ [Key a11y feature]
- ✅ Tested with axe-core via `cy.checkAccessibility()`
---
## Documentation
- `[file]` — [What was added/updated]
---
## Reviewer Notes
**Focus areas:**
1. [What to review]
2. [What to review]
**Manual testing:**
1. [Step]
2. [Step]
3. Observe: [Expected result] ✅
**Quick test commands:**
```bash
pnpm cypress:run:e2e --spec "cypress/e2e/[path]/[file].spec.cy.ts"
```
---
## Submission checklist
- [ ] Title is user-focused, not technical
- [ ] Linear issue link is correct
- [ ] Description opens with user value proposition
- [ ] No code snippets in the description section
- [ ] AFTER section has screenshots with Cypress test captions
- [ ] Test coverage is summarized (count only, not exhaustive list)
- [ ] Breaking changes stated (or "None")
- [ ] Accessibility section present (UI changes)
- [ ] Reviewer notes provide clear testing steps
- [ ] No replication of Linear ticket content
---
## Never do this
- Open description with implementation details ("This PR refactors…")
- Include code snippets in the description (save for Files Changed / code review)
- Write vague benefits ("improved UX", "better performance")
- Skip screenshots for UI changes
- Replicate the entire Linear ticket
Automated code review against established patterns before PR creation. Analyzes git diff for critical issues, pattern violations, test coverage, and generates a comprehensive report.
Use this skill when any artifact needs visual evidence of UI state. Invoke automatically when: creating a PR with UI changes (invoke before writing the PR body), updating docs/ with new screenshots, or preparing blog post visuals. Trigger phrases: "I need screenshots", "capture the UI", "show before/after", "add visuals to the PR".
Use this skill when writing user-facing documentation for a blog post, release notes, or feature announcement. Invoke automatically when: the user asks to "write a blog post", "write release notes", "document this feature for users", or "write a feature announcement". Produces structured ~500-word feature write-ups in plain language for non-technical readers (DevOps engineers, system administrators — not frontend developers).
Use this skill when a Cypress test is failing and the cause is not immediately obvious. Invoke automatically when: a test throws "element not found", "expected to find element", "element is disabled", or any assertion failure. Also invoke before reaching for {force: true}, cy.wait(), or rewriting a test from scratch — investigate first.
Fetch and analyze SonarQube quality metrics for pull requests, reporting on code quality, bugs, vulnerabilities, coverage, and code smells
Review technical documentation against the HiveMQ writing guidelines, producing a structured quality report with actionable findings per file