PR Description Writer

MIT License

Copyright (c) 2026 OpenAgentSkills Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

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.