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 comparing original phrasing with reviewer suggestions to help refine future writing.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
Start Here
[!TIP] Please see https://fast-agent.ai for latest documentation.
fast-agent is a flexible way to interact with LLMs, excellent for use as a Coding Agent, Development Toolkit, Evaluation or Workflow platform.
To start an interactive session with shell support, install uv and run
uvx fast-agent-mcp@latest -x
To start coding with Hugging Face inference providers or use your OpenAI Codex plan:
# Code with Hugging Face Inference Providers
uvx fast-agent-mcp@latest --pack hf-dev
# Code with Codex (agents optimized for OpenAI)
uvx fast-agent-mcp@latest --pack codex
Enter a shell with !, or run shell commands e.g. ! cd web && npm run build.
Manage skills with the /skills command, and connect to MCP Servers with /connect. The default fast-agent registry contains skills to let you set up LSP, Agent and Tool Hooks, Compaction strategies, Automation and more.
# /connect supports stdio or streamable http (with OAuth)
# Start a STDIO server
/connect @modelcontextprotocol/server-everything
# Connect to a Streamable HTTP Server
/connect https://huggingface.co/mcp
It's recommended to install fast-agent to set up the shell aliases and other tooling.
# Install fast-agent
uv tool install -U fast-agent-mcp
# Run fast-agent with opus, shell support and built-in subagents
fast-agent --model opus -xx
Use local models with the generic provider, or automatically create the correct configuration for llama.cpp:
fast-agent model llamacpp
Any fast-agent setup or program can be used with any ACP client - the simplest way is to use fast-agent-acp:
# Run fast-agent inside Toad
toad acp "fast-agent-acp -x --model sonnet"
fast-agent enables you to create and interact with sophisticated multimodal Agents and Workflows in minutes. It is the first framework with complete, end-to-end tested MCP Feature support including Sampling and Elicitations.
fast-agent is CLI-first, with an optional prompt_toolkit-powered interactive terminal prompt (TUI-style input, completions, and in-terminal menus); responses can stream live to the terminal via rich without relying on full-screen curses UIs or external GUI overlays.
The simple declarative syntax lets you concentrate on composing your Prompts and MCP Servers to build effective agents.
Model support is comprehensive with native support for Anthropic, OpenAI and Google providers as well as Azure, Ollama, Deepseek and dozens of others via TensorZero. Structured Outputs, PDF and Vision support is simple to use and well tested. Passthrough and Playback LLMs enable rapid development and test of Python glue-code for your applications.
Recent features include:
- Agent Skills (SKILL.md)
- MCP Apps
- OpenAI Apps SDK
- Shell Mode
- Advanced MCP Transport Diagnsotics
- MCP Elicitations
fast-agent is the only tool that allows you to inspect Streamable HTTP Transport usage - a critical feature for ensuring reliable, compliant deployments. OAuth is supported with KeyRing storage for secrets. Use the fast-agent auth command to manage.
[!IMPORTANT]
Documentation is included in this repository under
docs/. Use the docs helper script from the repository root to install, generate, build, serve, screenshot, and assess the site.
Agent Application Development
Prompts and configurations that define your Agent Applications are stored in simple files, with minimal boilerplate, enabling simple management and version control.
Chat with individual Agents and Components before, during and after workflow execution to tune and diagnose your application. Agents can request human input to get additional context for task completion.
Simple model selection makes testing Model <-> MCP Server interaction painless. You can read more about the motivation behind this project here
Get started:
Start by installing the uv package manager for Python. Then:
uv pip install fast-agent-mcp # install fast-agent!
fast-agent go # start an interactive session
fast-agent go --url https://hf.co/mcp # with a remote MCP
fast-agent go --model=generic.qwen2.5 # use ollama qwen 2.5
fast-agent go --pack analyst --model haiku # install/reuse a card pack and launch it
fast-agent scaffold # create an example agent and config files
uv run agent.py # run with default_model or FAST_AGENT_MODEL configured
uv run agent.py --model='gpt-5.4-mini?reasoning=low' # specify a model
uv run agent.py --transport http --port 8001 # expose as MCP server (server mode implied)
fast-agent quickstart workflow # create "building effective agents" examples
With no configured model, an interactive run opens the model picker.
Automation and server runs must pass --model, set FAST_AGENT_MODEL, configure
default_model, or declare a model on the agent.
For packaged starter agents, use fast-agent go --pack <name> --model <model>.
This installs the pack into the selected fast-agent home if needed, then
starts go normally. --model is a fallback for cards without an explicit
model setting; a model declared directly in an AgentCard still wins.
Other quickstart examples include a Researcher Agent (with Evaluator-Optimizer workflow) and Data Analysis Agent (similar to the ChatGPT experience), demonstrating MCP Roots support.
[!TIP] Windows Users - there are a couple of configuration changes needed for the Filesystem and Docker MCP Servers - necessary changes are detailed within the configuration files.
Basic Agents
Defining an agent is as simple as:
@fast.agent(
instruction="Given an object, respond only with an estimate of its size."
)
We can then send messages to the Agent:
async with fast.run() as agent:
moon_size = await agent("the moon")
print(moon_size)
Or start an interactive chat with the Agent:
async with fast.run() as agent:
await agent.interactive()
Here is the complete sizer.py Agent application, with boilerplate code:
import asyncio
from fast_agent import FastAgent
# Create the application
fast = FastAgent("Agent Example")
@fast.agent(instruction="Given an object, respond only with an estimate of its size.")
async def main():
async with fast.run() as agent:
await agent.interactive()
if __name__ == "__main__":
asyncio.run(main())
The Agent can then be run with uv run sizer.py.
Specify a model with the --model switch - for example uv run sizer.py --model sonnet.
Model strings also accept query overrides. For example:
- `uv run
// HOW IT'S BUILT
// FILES
3 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
examples/hf-toad-cards/skills/pr-writing-review/SKILL.md7.3 KB295d54497f55upstream ↗
--- 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}}examples/hf-toad-cards/skills/pr-writing-review/scripts/extract_pr_reviews.py24 KB7507ef7970a6upstream ↗
#!/usr/bin/env -S uv run # /// script # requires-python = ">=3.12" # dependencies = [] # /// """Extract PR review comments and file evolution from a GitHub Pull Request. Outputs structured data for LLM analysis of writing style improvements. Usage: uv run scripts/extract_pr_reviews.py <pr_url> uv run scripts/extract_pr_reviews.py <pr_url> --diff # Show first→final for LLM comparison uv run scripts/extract_pr_reviews.py <pr_url> --json # Raw JSON output Examples: uv run scripts/extract_pr_reviews.py https://github.com/huggingface/blog/pull/3029 uv run scripts/extract_pr_reviews.py huggingface/blog 3029 --diff """ from __future__ import annotations import argparse import json import re import subprocess import sys from dataclasses import asdict, dataclass, field from typing import cast from urllib.parse import quote, urlparse JsonValue = str | int | float | bool | None | list["JsonValue"] | dict[str, "JsonValue"] JsonDict = dict[str, JsonValue] # ----------------- # Data structures # ----------------- @dataclass class ReviewComment: """A single review comment or suggestion.""" id: int reviewer: str path: str original_line: int | None original_text: str comment_type: str # "suggestion", "feedback", or "reply" suggestion_texts: list[str] = field(default_factory=list) # supports multiple suggestion blocks comment_text: str = "" commit_id: str = "" created_at: str = "" html_url: str = "" in_reply_to_id: int | None = None @dataclass class FileEvolution: """Track a file's content from first to final version.""" final_path: str all_paths: list[str] # All names this file had during the PR first_content: str | None = None first_commit: str | None = None final_content: str | None = None final_commit: str | None = None @dataclass class PRReviewData: """Complete review data for a PR.""" owner: str repo: str pr_number: int title: str state: str first_commit_sha: str head_sha: str files: list[dict] comments: list[ReviewComment] commit_history: list[dict] file_evolutions: dict[str, FileEvolution] = field(default_factory=dict) # ----------------- # gh helpers # ----------------- def run_gh(args: list[str], check: bool = True) -> dict | list | str: """Run gh CLI command and return parsed JSON or raw output.""" cmd = ["gh"] + args result = subprocess.run( cmd, capture_output=True, text=True, encoding="utf-8", errors="replace", check=False ) if result.returncode != 0: if check: raise subprocess.CalledProcessError( result.returncode, cmd, result.stdout, result.stderr ) return "" try: return json.loads(result.stdout) except json.JSONDecodeError: return result.stdout def run_gh_jsonlines(args: list[str], check: bool = True) -> list[dict]: """Run gh command that prints one JSON object per line; return list of objects.""" cmd = ["gh"] + args result = subprocess.run( cmd, capture_output=True, text=True, encoding="utf-8", errors="replace", check=False ) if result.returncode != 0: if check: raise subprocess.CalledProcessError( result.returncode, cmd, result.stdout, result.stderr ) return [] out: list[dict] = [] for line in result.stdout.splitlines(): line = line.strip() if not line: continue out.append(json.loads(line)) return out def _ensure_json_value(value: object, label: str) -> JsonValue: if value is None or isinstance(value, str | int | float | bool): return value if isinstance(value, list): return [_ensure_json_value(item, f"{label}[]") for item in value] if isinstance(value, dict): return _ensure_json_dict(value, label) raise ValueError(f"Expected JSON-compatible value for {label}") def _ensure_json_dict(value: object, label: str) -> JsonDict: if not isinstance(value, dict): raise ValueError(f"Expected object for {label}") if not all(isinstance(key, str) for key in value.keys()): raise ValueError(f"Expected string keys for {label}") return cast( "JsonDict", {str(key): _ensure_json_value(val, f"{label}.{key}") for key, val in value.items()}, ) def _get_required_str(data: JsonDict, key: str) -> str: value = data.get(key) if isinstance(value, str): return value raise ValueError(f"Missing or invalid '{key}'") def _get_optional_str(data: JsonDict, key: str) -> str | None: value = data.get(key) if isinstance(value, str): return value return None # ----------------- # Parsing helpers # ----------------- def parse_pr_url(url_or_args: list[str]) -> tuple[str, str, int]: """Parse PR URL or owner/repo + number into components.""" if len(url_or_args) == 1: url = url_or_args[0] parsed = urlparse(url) parts = parsed.path.strip("/").split("/") if len(parts) >= 4 and parts[2] in ("pull", "pulls"): return parts[0], parts[1], int(parts[3]) raise ValueError(f"Invalid PR URL: {url}") if len(url_or_args) == 2: owner_repo, pr_num = url_or_args if "/" in owner_repo: owner, repo = owner_repo.split("/", 1) return owner, repo, int(pr_num) raise ValueError(f"Expected owner/repo format: {owner_repo}") if len(url_or_args) == 3: owner, repo, pr_num = url_or_args return owner, repo, int(pr_num) raise ValueError("Expected PR URL or 'owner/repo pr_number'") def normalize_newlines(text: str) -> str: return text.replace("\r\n", "\n").replace("\r", "\n") def extract_original_from_diff_hunk(diff_hunk: str, num_lines: int = 1) -> str: """Extract the original text a comment targets from a diff hunk. For PR review comments, GitHub provides the diff hunk. Inline comments are typically anchored to the added lines, so we extract the last N added lines. """ if not diff_hunk: return "" lines = normalize_newlines(diff_hunk).split("\n") added_lines: list[str] = [] for line in lines: if line.startswith("+") and not line.startswith("+++"): added_lines.append(line[1:]) if not added_lines: return "" num_lines = max(1, num_lines) if num_lines == 1: return added_lines[-1] return "\n".join(added_lines[-num_lines:]) _SUGGESTION_BLOCK_RE = re.compile(r"```suggestion(?:[^\n`]*)?\s*\n(.*?)```", re.DOTALL) def parse_suggestions(body: str) -> list[str]: """Extract all ```suggestion blocks from a comment body. Supports GitHub variants like: - ```suggestion - ```suggestion:-0+1 and returns *all* suggestion blocks found. """ if not body: return [] body = normalize_newlines(body) suggestions: list[str] = [] for m in _SUGGESTION_BLOCK_RE.finditer(body): s = m.group(1) # Keep internal newlines but strip trailing whitespace/newlines s = normalize_newlines(s).rstrip() suggestions.append(s) return suggestions def count_suggestion_lines(suggestion_text: str) -> int: """Count how many lines a suggestion replaces.""" if not suggestion_text: return 1 return len(normalize_newlines(suggestion_text).split("\n")) # ----------------- # Content helpers # ----------------- def get_file_content_at_ref(owner: str, repo: str, path: str, ref: str) -> str | None: """Get file content at a specific ref using the contents API.""" encoded_path = quote(path, safe="") result = subprocess.run( [ "gh", "api", f"repos/{owner}/{repo}/contents/{encoded_path}?ref={ref}", "-H", "Accept: application/vnd.github.raw", ], capture_output=True, text=True, encoding="utf-8", errors="replace", check=False, ) if result.returncode == 0 and result.stdout: return result.stdout return None def trace_file_through_commits( owner: str, repo: str, commits: list[dict], final_path: str ) -> list[str]: """Trace a file backwards through commits to find all names it had. Returns a list of paths from oldest name to newest. """ paths = [final_path] current_path = final_path # Check each commit in reverse order for renames. for commit in reversed(commits): sha = commit["sha"] files = run_gh( [ "api", f"repos/{owner}/{repo}/commits/{sha}", "--jq", "[.files[] | {filename, previous_filename, status}]", ], check=False, ) if not files or not isinstance(files, list): continue for f in files: if f.get("filename") == current_path and f.get("previous_filename"): prev = f["previous_filename"] if prev not in paths: paths.insert(0, prev) current_path = prev break return paths def find_first_content( owner: str, repo: str, commits: list[dict], paths: list[str] ) -> tuple[str | None, str | None]: """Find the first version of a file, trying all known paths at each commit.""" if not commits: return None, None for commit in commits: sha = commit["sha"] for path in paths: content = get_file_content_at_ref(owner, repo, path, sha) if content: return content, sha[:7] return None, None # ----------------- # Main fetch # ----------------- def fetch_pr_data( owner: str, repo: str, pr_number: int, track_evolution: bool = False ) -> PRReviewData: """Fetch all review data for a PR.""" repo_ref = f"{owner}/{repo}" pr_info = _ensure_json_dict( run_gh( [ "pr", "view", str(pr_number), "--repo", repo_ref, "--json", "title,state,headRefOid,files", ] ), "pr_info", ) # Paginated commits in order (JSON-lines). commits = run_gh_jsonlines( [ "api", f"repos/{repo_ref}/pulls/{pr_number}/commits", "--paginate", "--jq", ".[] | {sha: .sha, message: .commit.message, date: .commit.author.date}", ] ) # Paginated review comments. raw_comments = run_gh_jsonlines( [ "api", f"repos/{repo_ref}/pulls/{pr_number}/comments", "--paginate", "--jq", ".[]", ] ) comments: list[ReviewComment] = [] for c in raw_comments: body = c.get("body", "") or "" suggestion_texts = parse_suggestions(body) clean_body = normalize_newlines(body).strip() if suggestion_texts: comment_type = "suggestion" # Remove suggestion fences from reviewer note output. clean_body = normalize_newlines(_SUGGESTION_BLOCK_RE.sub("", body)).strip() # For extracting original text, use the *largest* suggestion block length. num_lines = max(count_suggestion_lines(s) for s in suggestion_texts) elif c.get("in_reply_to_id"): comment_type = "reply" num_lines = 1 else: comment_type = "feedback" num_lines = 1 original_text = extract_original_from_diff_hunk(c.get("diff_hunk", "") or "", num_lines) comments.append( ReviewComment( id=c["id"], reviewer=c["user"]["login"], path=c.get("path") or "", original_line=c.get("original_line"), original_text=original_text, comment_type=comment_type, suggestion_texts=suggestion_texts, comment_text=clean_body, commit_id=(c.get("commit_id") or "")[:7], created_at=c.get("created_at") or "", html_url=c.get("html_url") or "", in_reply_to_id=c.get("in_reply_to_id"), ) ) comments.sort(key=lambda x: x.created_at) # Paginated PR files. files = run_gh_jsonlines( [ "api", f"repos/{repo_ref}/pulls/{pr_number}/files", "--paginate", "--jq", ".[] | {filename: .filename, previous_filename: .previous_filename, status: .status}", ] ) first_commit_sha = commits[0].get("sha") if commits else "" if not isinstance(first_commit_sha, str): first_commit_sha = "" head_sha = _get_optional_str(pr_info, "headRefOid") if not head_sha and commits: last_sha = commits[-1].get("sha") head_sha = last_sha if isinstance(last_sha, str) else "" file_evolutions: dict[str, FileEvolution] = {} if track_evolution: for f in files: final_path = f["filename"] # Only track text files. if not any(final_path.endswith(ext) for ext in (".md", ".txt", ".rst", ".mdx")): continue all_paths = trace_file_through_commits(owner, repo, commits, final_path) # Also include previous_filename from PR files endpoint if present. if f.get("previous_filename") and f["previous_filename"] not in all_paths: all_paths.insert(0, f["previous_filename"]) # Add paths from comments that reference this file (best-effort). for c in comments: if c.path and c.path not in all_paths: c_base = c.path.split("/")[-1] if any(c_base == p.split("/")[-1] for p in all_paths): all_paths.append(c.path) # Dedupe while preserving order. all_paths = list(dict.fromkeys(all_paths)) evo = FileEvolution(final_path=final_path, all_paths=all_paths) evo.first_content, evo.first_commit = find_first_content( owner, repo, commits, all_paths ) evo.final_content = ( get_file_content_at_ref(owner, repo, final_path, head_sha) if head_sha else None ) evo.final_commit = head_sha[:7] if head_sha else None file_evolutions[final_path] = evo return PRReviewData( owner=owner, repo=repo, pr_number=pr_number, title=_get_required_str(pr_info, "title"), state=_get_required_str(pr_info, "state"), first_commit_sha=first_commit_sha[:7] if first_commit_sha else "", head_sha=head_sha[:7] if head_sha else "", files=files, comments=comments, commit_history=commits, file_evolutions=file_evolutions, ) # ----------------- # Output formatting # ----------------- def fenced_block(text: str, lang: str = "text") -> str: text = text or "" text = normalize_newlines(text).rstrip("\n") return f"```{lang}\n{text}\n```" def maybe_truncate_text(text: str, limit: int | None) -> str: if not limit or limit <= 0 or len(text) <= limit: return text truncated = text[: max(0, limit - 1)].rstrip() return f"{truncated}\n\n...[truncated {len(text) - len(truncated)} chars]" def format_suggestions_and_feedback(data: PRReviewData) -> str: """Format just the suggestions and feedback (no file content).""" lines: list[str] = [] lines.append(f"# PR Review Analysis: {data.title}") lines.append(f"**PR:** {data.owner}/{data.repo}#{data.pr_number}") lines.append(f"**State:** {data.state}") lines.append(f"**Commits:** {len(data.commit_history)} total") lines.append("") # Files lines.append("## Files Changed") for f in data.files: prev = f.get("previous_filename") status = f.get("status", "modified") if prev: lines.append(f"- {f['filename']} ({status}) ← *renamed from {prev}*") else: lines.append(f"- {f['filename']} ({status})") lines.append("") # Suggestions suggestions = [c for c in data.comments if c.comment_type == "suggestion"] if suggestions: total_suggestions = sum(len(c.suggestion_texts) for c in suggestions) lines.append(f"## Writing Suggestions ({total_suggestions})") lines.append("") reviewers: dict[str, list[ReviewComment]] = {} for s in suggestions: reviewers.setdefault(s.reviewer, []).append(s) for reviewer, items in reviewers.items(): reviewer_total = sum(len(c.suggestion_texts) for c in items) lines.append(f"### @{reviewer} ({reviewer_total} suggestions)") lines.append("") idx = 1 for c in items: for s_text in c.suggestion_texts: lines.append(f"**{idx}. Line {c.original_line or '?'}** (`{c.path}`)") lines.append("") lines.append("Original:") lines.append(fenced_block(c.original_text, "text")) lines.append("") lines.append("Suggested:") lines.append(fenced_block(s_text, "text")) lines.append("") if c.comment_text and c.comment_type == "suggestion": lines.append("Reviewer note:") lines.append(c.comment_text.strip()) lines.append("") if c.html_url: lines.append(f"[View on GitHub]({c.html_url})") lines.append("") idx += 1 # Feedback feedback = [c for c in data.comments if c.comment_type == "feedback"] if feedback: lines.append(f"## Reviewer Feedback ({len(feedback)})") lines.append("") for i, c in enumerate(feedback, 1): lines.append(f"### {i}. @{c.reviewer} on `{c.path}` line {c.original_line or '?'}") lines.append("") lines.append(c.comment_text) lines.append("") if c.html_url: lines.append(f"[View on GitHub]({c.html_url})") lines.append("") return "\n".join(lines) def format_diff_comparison(data: PRReviewData, max_file_chars: int | None = None) -> str: """Format for LLM paragraph-by-paragraph comparison.""" lines: list[str] = [] lines.append(f"# PR Style Analysis: {data.title}") lines.append(f"**PR:** {data.owner}/{data.repo}#{data.pr_number}") lines.append("") # Explicit suggestions suggestions = [c for c in data.comments if c.comment_type == "suggestion"] if suggestions: lines.append("## Explicit Suggestions (exact before → after)") lines.append("") k = 1 for c in suggestions: for s_text in c.suggestion_texts: lines.append(f"### {k}. @{c.reviewer}") lines.append(f"**Path:** `{c.path}` ") lines.append(f"**Line:** {c.original_line or '?'}") lines.append("") lines.append("**Before:**") lines.append(fenced_block(c.original_text, "text")) lines.append("") lines.append("**After:**") lines.append(fenced_block(s_text, "text")) lines.append("") if c.comment_text: lines.append("**Reviewer note:**") lines.append(c.comment_text.strip()) lines.append("") if c.html_url: lines.append(f"[View on GitHub]({c.html_url})") lines.append("") k += 1 # Feedback feedback = [c for c in data.comments if c.comment_type == "feedback"] if feedback: lines.append("## Reviewer Feedback (requests without explicit replacement)") lines.append("") for i, c in enumerate(feedback, 1): lines.append(f"{i}. **@{c.reviewer}** ({c.path}:{c.original_line or '?'})") lines.append("") lines.append(c.comment_text) lines.append("") # File evolution if data.file_evolutions: lines.append("---") lines.append("") lines.append("## File Evolution (first draft → final)") lines.append("") lines.append( "*Compare paragraph-by-paragraph to see how the author responded to feedback.*" ) lines.append("") for path, evo in data.file_evolutions.items(): if not evo.first_content and not evo.final_content: continue lines.append(f"### {path}") if len(evo.all_paths) > 1: lines.append(f"*File was renamed: {' → '.join(evo.all_paths)}*") lines.append("") if evo.first_content: lines.append(f"#### FIRST DRAFT ({evo.first_commit})") lines.append( fenced_block( maybe_truncate_text(evo.first_content, max_file_chars), "markdown", ) ) lines.append("") if evo.final_content: lines.append(f"#### FINAL VERSION ({evo.final_commit})") lines.append( fenced_block( maybe_truncate_text(evo.final_content, max_file_chars), "markdown", ) ) lines.append("") return "\n".join(lines) # ----------------- # CLI # ----------------- def parse_cli_args(argv: list[str]) -> argparse.Namespace: parser = argparse.ArgumentParser(description="Extract GitHub PR review data") parser.add_argument("target", nargs="+", help="PR URL or 'owner/repo pr_number'") parser.add_argument("--diff", action="store_true", help="Include file evolution output") parser.add_argument("--json", action="store_true", help="Emit raw JSON instead of Markdown") parser.add_argument( "--max-file-chars", type=int, default=None, help="Trim FIRST/FINAL dumps to this many characters per file", ) parser.add_argument( "--no-files", action="store_true", help="Skip file evolution even when --diff is set" ) return parser.parse_args(argv) def main() -> None: if len(sys.argv) < 2: print(__doc__) sys.exit(1) args = parse_cli_args(sys.argv[1:]) if len(args.target) > 3: print("Error: Expected PR URL or 'owner/repo pr_number'", file=sys.stderr) sys.exit(1) try: owner, repo, pr_number = parse_pr_url(args.target) except ValueError as e: print(f"Error: {e}", file=sys.stderr) sys.exit(1) track_evolution = args.diff and not args.no_files try: data = fetch_pr_data(owner, repo, pr_number, track_evolution=track_evolution) except subprocess.CalledProcessError as e: print(f"Error fetching PR data: {e.stderr}", file=sys.stderr) sys.exit(1) if args.json: output: JsonDict = { "owner": data.owner, "repo": data.repo, "pr_number": data.pr_number, "title": data.title, "state": data.state, "first_commit_sha": data.first_commit_sha, "head_sha": data.head_sha, "files": data.files, "commit_history": data.commit_history, "comments": [asdict(c) for c in data.comments], } if track_evolution: output["file_evolutions"] = { path: { "all_paths": evo.all_paths, "first_content": evo.first_content, "first_commit": evo.first_commit, "final_content": evo.final_content, "final_commit": evo.final_commit, } for path, evo in data.file_evolutions.items() } print(json.dumps(output, indent=2)) return if args.diff: print(format_diff_comparison(data, max_file_chars=args.max_file_chars)) return print(format_suggestions_and_feedback(data)) if __name__ == "__main__": main()README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/evalstate-fast-agent-examples-hf-toad-cards-skills-pr-writing-review.md