Claude Skill

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

LLM Mart · 0 points · 21 views 96 listing impressions 0 install-command copies
Download evalstate-fast-agent-examples_hf-toad-cards_skills_pr-writing-review-c551658.zip · 9 KB

Install

skills CLI npx skills add https://github.com/evalstate/fast-agent/tree/main/examples/hf-toad-cards/skills/pr-writing-review
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install evalstate-fast-agent@llmmart
Git 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: 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


> **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:

  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:

## 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}}

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.

No comments yet.

Reviews (0)

No reviews yet.