pr-writing-review
Extract and analyze writing improvements from GitHub PR review comments. Use when asked to show review feedback, style changes, or editorial improvements from a GitHub pull request URL. Handles both explicit suggestions and plain text feedback. Produces structured output comparin
Install
npx skills add https://github.com/evalstate/fast-agent/tree/main/examples/hf-toad-cards/skills/pr-writing-review
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install evalstate-fast-agent@llmmart
git clone https://github.com/evalstate/fast-agent.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole evalstate/fast-agent collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
PR Writing Review
Extract editorial feedback from GitHub PRs to learn from review improvements.
Prerequisites
- GitHub CLI:
ghinstalled - Authenticated
ghsession:gh auth statusshould show you’re logged in- For private repos, your token needs appropriate scopes (typically
repo).
- For private repos, your token needs appropriate scopes (typically
- Python: 3.12+
- uv (recommended): https://github.com/astral-sh/uv
Division of Labor
| Tool | Responsibility |
|---|---|
| Python script | API calls, parsing, file tracking across renames, structured extraction |
| LLM analysis | Pattern recognition, paragraph comparison, style lesson synthesis |
Quick Start
> **All paths are relative to the directory containing this SKILL.md file.**
> Before running any script, first `cd` to that directory or use the full path.
# Get suggestions and feedback
uv run scripts/extract_pr_reviews.py <pr_url>
# Get full first→final comparison for deep analysis
uv run scripts/extract_pr_reviews.py <pr_url> --diff
# Same as above, but cap each FIRST/FINAL dump to 2k chars for LLM prompting
uv run scripts/extract_pr_reviews.py <pr_url> --diff --max-file-chars 2000
Workflow
Step 1: Extract with --diff
uv run scripts/extract_pr_reviews.py https://github.com/org/repo/pull/123 --diff
This outputs:
- Explicit Suggestions — exact before/after text from
suggestionblocks (supports multiple suggestion blocks per comment) - Reviewer Feedback — plain text comments (the "why" behind changes)
- File Evolution — first draft and final version of each text file
Tip: add
--max-file-chars 2000to keep each FIRST/FINAL dump lightweight, or pair--diffwith--no-filesif you only need the suggestion/feedback summaries.
Step 2: Analyze the Output
With the script output, perform this analysis:
A. Catalog the Explicit Suggestions
Create a table of mechanical fixes:
| Pattern | Original | Fixed |
|---|---|---|
| Grammar | "Its easier" | "It's easier" |
| Filler removal | "using this way" | "this way" |
| Capitalization | "Image Generation" | "image generation" |
B. Map Feedback to Changes
For each reviewer feedback comment:
- Find the relevant section in FIRST DRAFT
- Find the same section in FINAL VERSION
- Document what changed and why
Example:
Feedback: "would be nice to end more enthusiastically"
First draft: "...it's simple to add new tools to Claude and use them straight away."
Final: "...Let us know what you find and create in the comments below!"
Lesson: End blog posts with a call-to-action
C. Paragraph-by-Paragraph Comparison
Compare FIRST DRAFT to FINAL VERSION section by section:
- What was added?
- What was removed?
- What was reworded?
- What structural changes were made?
D. Synthesize Style Patterns
Group findings into categories:
| Category | Patterns Found |
|---|---|
| Clarity | Passive→active, shorter sentences, remove filler |
| Precision | Vague→specific, "Create"→"Generate" |
| Tone | Added enthusiasm, call-to-action endings |
| Structure | Added transitions, better section flow |
| Grammar | its/it's, subject-verb agreement |
| Content | Added links, examples, context |
Script Options
📁 All paths are relative to the directory containing this SKILL.md file.
| Flag | Output | Use Case |
|---|---|---|
| (none) | Suggestions + feedback | Quick review of what reviewers said |
--diff |
Adds FIRST/FINAL file dumps to the default output | Deep analysis of how the author responded |
--max-file-chars N |
Truncates each FIRST/FINAL block to N chars (appends ...[truncated X chars]) |
Keep prompts within LLM token limits |
--no-files |
Suppresses FIRST/FINAL dumps even when --diff is set |
When you only need explicit suggestions + reviewer feedback |
--json |
Raw JSON (includes file_evolutions when --diff without --no-files) |
Programmatic processing |
Input formats: pass either a full PR URL,
owner/repo PR_NUMBER, orowner repo PR_NUMBER.
Output Structure
Default Output
- Writing Suggestions: Grouped by reviewer, shows original→suggested text (fenced blocks) along with any reviewer note and a permalink back to GitHub
- Reviewer Feedback: Plain comments without code suggestions, each tagged with its GitHub link
With --diff
- Explicit Suggestions: Compact before/after pairs, reviewer notes, and GitHub permalinks in one place
- Reviewer Feedback: Numbered list of requests (same as default view)
- File Evolution: FIRST DRAFT and FINAL VERSION for each
.md/.txt/.rst/.mdxfile; add--max-file-charsto truncate each block with a visible...[truncated X chars]indicator
Handling File Renames
The script traces files through renames by:
- Checking each commit for rename operations
- Building a path history (e.g.,
claudeimages.md→claude-images.md→claude-and-mcp.md) - Fetching content using the correct path for each commit
Example Analysis Output
After running the script and performing LLM analysis, produce a summary like:
## Style Lessons from PR #123
### Mechanical Fixes
- Fix grammar: "Its" → "It's" (contraction)
- Lowercase generic terms: "Image Generation" → "image generation"
- Remove filler: "the output quality of" → "the quality of"
### Reviewer-Driven Changes
- **"end more enthusiastically"** → Added call-to-action in conclusion
- **"emphasize these are SoTA"** → Changed "latest" to "state-of-the-art"
- **"add blurb about MCP Server"** → Added explanatory paragraph
### Structural Improvements
- Added transition sentence between sections
- Simplified setup instructions (3 sentences → 1)
- Added new bullet point for model flexibility
Limitations
- Only extracts inline PR review comments (not issue comments or the PR description)
- Extremely long files can still be heavy; when that happens, lower
--max-file-charsor pass--no-filesto keep outputs prompt-friendly
{{currentDate}} {{env}}
Files (fast-agent)
-
scripts
-
extract_pr_reviews.py 24 KB
Loading…
-
-
SKILL.md 7.3 KB
--- name: pr-writing-review description: Extract and analyze writing improvements from GitHub PR review comments. Use when asked to show review feedback, style changes, or editorial improvements from a GitHub pull request URL. Handles both explicit suggestions and plain text feedback. Produces structured output comparing original phrasing with reviewer suggestions to help refine future writing. --- # PR Writing Review Extract editorial feedback from GitHub PRs to learn from review improvements. ## Prerequisites - **GitHub CLI**: `gh` installed - **Authenticated `gh` session**: `gh auth status` should show you’re logged in - For private repos, your token needs appropriate scopes (typically `repo`). - **Python**: 3.12+ - **uv** (recommended): https://github.com/astral-sh/uv ## Division of Labor | Tool | Responsibility | | ----------------- | ----------------------------------------------------------------------- | | **Python script** | API calls, parsing, file tracking across renames, structured extraction | | **LLM analysis** | Pattern recognition, paragraph comparison, style lesson synthesis | ## Quick Start ```bash > **All paths are relative to the directory containing this SKILL.md file.** > Before running any script, first `cd` to that directory or use the full path. # Get suggestions and feedback uv run scripts/extract_pr_reviews.py <pr_url> # Get full first→final comparison for deep analysis uv run scripts/extract_pr_reviews.py <pr_url> --diff # Same as above, but cap each FIRST/FINAL dump to 2k chars for LLM prompting uv run scripts/extract_pr_reviews.py <pr_url> --diff --max-file-chars 2000 ``` ## Workflow ### Step 1: Extract with `--diff` ```bash uv run scripts/extract_pr_reviews.py https://github.com/org/repo/pull/123 --diff ``` This outputs: 1. **Explicit Suggestions** — exact before/after text from `suggestion` blocks (supports multiple suggestion blocks per comment) 2. **Reviewer Feedback** — plain text comments (the "why" behind changes) 3. **File Evolution** — first draft and final version of each text file > Tip: add `--max-file-chars 2000` to keep each FIRST/FINAL dump lightweight, or pair `--diff` with `--no-files` if you only need the suggestion/feedback summaries. ### Step 2: Analyze the Output With the script output, perform this analysis: #### A. Catalog the Explicit Suggestions Create a table of mechanical fixes: | Pattern | Original | Fixed | | -------------- | ------------------ | ------------------ | | Grammar | "Its easier" | "It's easier" | | Filler removal | "using this way" | "this way" | | Capitalization | "Image Generation" | "image generation" | #### B. Map Feedback to Changes For each reviewer feedback comment: 1. Find the relevant section in FIRST DRAFT 2. Find the same section in FINAL VERSION 3. Document what changed and why Example: > **Feedback:** "would be nice to end more enthusiastically" > > **First draft:** "...it's simple to add new tools to Claude and use them straight away." > > **Final:** "...Let us know what you find and create in the comments below!" > > **Lesson:** End blog posts with a call-to-action #### C. Paragraph-by-Paragraph Comparison Compare FIRST DRAFT to FINAL VERSION section by section: - What was added? - What was removed? - What was reworded? - What structural changes were made? #### D. Synthesize Style Patterns Group findings into categories: | Category | Patterns Found | | ------------- | ------------------------------------------------ | | **Clarity** | Passive→active, shorter sentences, remove filler | | **Precision** | Vague→specific, "Create"→"Generate" | | **Tone** | Added enthusiasm, call-to-action endings | | **Structure** | Added transitions, better section flow | | **Grammar** | its/it's, subject-verb agreement | | **Content** | Added links, examples, context | ## Script Options > 📁 **All paths are relative to the directory containing this SKILL.md file.** | Flag | Output | Use Case | | -------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------- | | _(none)_ | Suggestions + feedback | Quick review of what reviewers said | | `--diff` | Adds FIRST/FINAL file dumps to the default output | Deep analysis of how the author responded | | `--max-file-chars N` | Truncates each FIRST/FINAL block to _N_ chars (appends `...[truncated X chars]`) | Keep prompts within LLM token limits | | `--no-files` | Suppresses FIRST/FINAL dumps even when `--diff` is set | When you only need explicit suggestions + reviewer feedback | | `--json` | Raw JSON (includes `file_evolutions` when `--diff` without `--no-files`) | Programmatic processing | > Input formats: pass either a full PR URL, `owner/repo PR_NUMBER`, or `owner repo PR_NUMBER`. ## Output Structure ### Default Output - **Writing Suggestions**: Grouped by reviewer, shows original→suggested text (fenced blocks) along with any reviewer note and a permalink back to GitHub - **Reviewer Feedback**: Plain comments without code suggestions, each tagged with its GitHub link ### With `--diff` - **Explicit Suggestions**: Compact before/after pairs, reviewer notes, and GitHub permalinks in one place - **Reviewer Feedback**: Numbered list of requests (same as default view) - **File Evolution**: FIRST DRAFT and FINAL VERSION for each `.md`/`.txt`/`.rst`/`.mdx` file; add `--max-file-chars` to truncate each block with a visible `...[truncated X chars]` indicator ## Handling File Renames The script traces files through renames by: 1. Checking each commit for rename operations 2. Building a path history (e.g., `claudeimages.md` → `claude-images.md` → `claude-and-mcp.md`) 3. Fetching content using the correct path for each commit ## Example Analysis Output After running the script and performing LLM analysis, produce a summary like: ```markdown ## Style Lessons from PR #123 ### Mechanical Fixes - Fix grammar: "Its" → "It's" (contraction) - Lowercase generic terms: "Image Generation" → "image generation" - Remove filler: "the output quality of" → "the quality of" ### Reviewer-Driven Changes - **"end more enthusiastically"** → Added call-to-action in conclusion - **"emphasize these are SoTA"** → Changed "latest" to "state-of-the-art" - **"add blurb about MCP Server"** → Added explanatory paragraph ### Structural Improvements - Added transition sentence between sections - Simplified setup instructions (3 sentences → 1) - Added new bullet point for model flexibility ``` ## Limitations - Only extracts **inline PR review comments** (not issue comments or the PR description) - Extremely long files can still be heavy; when that happens, lower `--max-file-chars` or pass `--no-files` to keep outputs prompt-friendly {{currentDate}} {{env}}
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.