PR Description Writer

PR Description Writer

What this skill does

This skill directs the agent to read a diff or a plain summary of changes and produce a complete, well-structured pull request description. It covers what changed, why it changed, how reviewers can test it, and what edge cases or risks to be aware of — so reviewers can do their job without having to chase you for context.

Use this when you're about to open a PR and want a description that will actually get reviewed instead of skipped, or when you need to document a large change for future reference.

How to use

Claude Code / Cline

Copy this file to .agents/skills/pr-description-writer/SKILL.md in your project root.

Then ask:

• "Write a PR description for these changes using the PR Description Writer skill."
• "Use the PR Description Writer skill. Here's the diff."

You can provide:

• A git diff main...HEAD or git diff output
• A bullet list of what changed (if the diff is too large to paste)
• The GitHub issue number this PR closes (optional)
• Any context about why the change was needed

Cursor / Codex

Paste the instructions from the section below into your session, then provide your diff or change summary.

The Prompt / Instructions for the Agent

When asked to write a pull request description, follow these steps:

1. Understand the change

Read the diff or change list and identify:

• What files / modules were touched?
• Is this a new feature, a bug fix, a refactor, a performance improvement, or a configuration change?
• What was the motivation? (If not stated, ask — or make a reasonable inference and flag it for the author to verify)
• Are there any breaking changes or behavioral differences a user or caller would notice?

2. Write the PR description

Produce a description with these exact sections:

## Summary 1-3 bullet points. Each bullet is one complete thought. Focus on the what and the why, not the implementation details. Example:

• Adds rate limiting to the /auth/login endpoint to prevent brute-force attacks
• Limits failed login attempts to 5 per minute per IP, after which requests return 429

## Changes A more detailed breakdown for reviewers. Group related changes together. Use sub-bullets if needed:

• server/auth.ts — added checkRateLimit() middleware before the password comparison step
• server/middleware/rateLimiter.ts — new file: generic rate limiter using an in-memory sliding window
• tests/auth.test.ts — added 4 new test cases covering the rate limit behavior

## Test Plan A checklist of how to verify the change works. Written as concrete steps a reviewer can follow:

• Run npm test — all tests should pass
• POST /auth/login with valid credentials returns 200
• POST /auth/login 6 times in 1 minute from the same IP returns 429 on the 6th request
• After 1 minute, requests succeed again

## Screenshots or recordings (optional) If the change has a UI component, include this section with a note to attach screenshots. Otherwise omit it.

## Risks and notes Any caveats, known limitations, or things the reviewer should pay special attention to:

• The in-memory rate limiter resets on server restart — a Redis-backed implementation is tracked in #234
• This change does not affect the /auth/refresh endpoint

## Related

• Closes #[issue number] (if applicable)
• Related to #[other PR or issue] (if applicable)

3. Tone rules

• Write for the reviewer, not for yourself
• Be specific — "updated the login handler" is useless; "added a 5 req/min rate limit on failed logins" is useful
• Assume the reviewer knows the codebase but has not looked at this change yet
• Flag anything uncertain: "I believe this is backwards-compatible but please check the formatDate caller in ReportPage.tsx"

4. Output format

Produce the PR description in a fenced markdown block so it can be copy-pasted directly into GitHub.

Example

Input to Agent:

"Use the PR Description Writer skill. Here's a summary of my changes:

• Added a CopyableCodeBlock component that shows a code block with a copy button
• Used it in the JSON Formatter tool to replace the plain <pre> tag
• Updated the Header component to add a link to the new AI Resources page This closes issue #88."

Output from Agent:

## Summary

- Adds a reusable `CopyableCodeBlock` component with a one-click copy button for code output
- Replaces the plain `<pre>` tag in the JSON Formatter with `CopyableCodeBlock`, improving usability
- Adds an AI Resources link to the site header

## Changes

- `client/src/components/CopyableCodeBlock.tsx` — new component: renders a code block with syntax highlighting and a copy-to-clipboard button using the Clipboard API
- `client/src/tools/JsonFormatter.tsx` — replaced `<pre>` output with `<CopyableCodeBlock>`
- `client/src/components/Header.tsx` — added "AI Resources" nav link pointing to `/ai-resources`

## Test Plan

- [ ] Run `npm test` — all tests pass
- [ ] Open the JSON Formatter tool, format some JSON, and verify the copy button copies the output to clipboard
- [ ] Click the copy button twice — verify it shows a "Copied!" confirmation on the first click and resets after 2 seconds
- [ ] Check the header on desktop and mobile — "AI Resources" link should be visible and route correctly

## Risks and Notes

- `CopyableCodeBlock` uses the async Clipboard API — this requires HTTPS or localhost. It will silently fail on plain HTTP (no existing pages served over plain HTTP, so this is fine).

## Related

- Closes #88

Notes

• The more context you provide, the better the description. A full diff is ideal; a bullet list of changes works too.
• If the PR is very large (100+ files), describe the intent and major areas affected rather than pasting the entire diff.
• The Test Plan section is the most commonly skipped in practice and the most valuable to reviewers — do not omit it.
• This skill writes the description only. It does not open the PR or interact with GitHub directly.