From pr-workflow
This skill should be used when the user asks to "review PR and save results", "run PR review with documentation", "create PR review document", "review and document PR", "save PR review to docs", "document PR review", or mentions reviewing a PR with the intention of saving the review results. Executes comprehensive PR review using pr-review-toolkit with opus model and posts results as a PR comment.
How this skill is triggered — by the user, by Claude, or both
Slash command
/pr-workflow:pr-review-and-documentThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Execute comprehensive PR review using pr-review-toolkit and post structured results as a PR comment.
Execute comprehensive PR review using pr-review-toolkit and post structured results as a PR comment.
Invoke this skill when:
PR_NUMBER=$("${CLAUDE_PLUGIN_ROOT}/scripts/get-pr-number.sh")
This uses the branch-to-PR-number cache (branch-map.json) with 1-hour TTL, falling back to GitHub API on cache miss.
If no PR exists for the current branch, inform the user and stop.
EXISTING_CONTENT=$(${CLAUDE_PLUGIN_ROOT}/scripts/cache-read-comment.sh "$PR_NUMBER")
This uses the local cache if available, falling back to GitHub API on cache miss.
If content is returned:
<!-- pr-review-metadata ... --> blockreview_round and issues status.pr-review-cache/pr-${PR_NUMBER}.json and save .content_hash as EXPECTED_CONTENT_HASH[Gemini] and [Codex] issues and review_sources metadata when writing the next reviewLaunch the pr-review-toolkit with opus model using the Skill tool:
Skill: pr-review-toolkit:review-pr
Args: all
Model: opus
Required agents (always run):
Important: All agents are mandatory for every review to ensure comprehensive coverage.
Structure the review as a PR comment with hidden metadata and collapsible sections.
Character Limit: Keep total content under ~40K characters (GitHub limit is 65,536).
Multi-source compatibility: If an existing review comment is present, do not blindly regenerate the whole comment. Merge the new Claude findings into the existing structure:
1.1 before writing. Prefer the shared helper:
METADATA_JSON=$(printf '%s\n' "$EXISTING_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-upgrade.sh --stdin --last-writer pr-review-and-document)
jq), replace the hidden block with the shared helper:
# Set up a temp file for the modified metadata JSON.
# (If this code block already declares its own trap, extend it instead of adding a second line.)
METADATA_FILE=$(mktemp)
trap 'rm -f "$METADATA_FILE"' EXIT
# Write the edited metadata JSON to the temp file.
printf '%s' "$METADATA_JSON" > "$METADATA_FILE"
# Replace the metadata block in the comment.
UPDATED_CONTENT=$(printf '%s\n' "$EXISTING_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-replace.sh --stdin --metadata-file "$METADATA_FILE")
review_sources.gemini, review_sources.codex, [Gemini] issues, and [Codex] issues✅, ⏭️, ⚠️, 🔴) unless the new Claude review proves they changedreview_round only when this review adds new findings; empty refreshes only update review_sources.claude.last_reviewed_*The metadata block uses HTML comment syntax with a specific marker for identification:
<!-- pr-review-metadata (marker on same line as opening)--> on its own line after the JSONImportant: The find-review-comment.sh script searches for <!-- pr-review-metadata to identify review comments. Do not modify this marker format.
<!-- pr-review-metadata
{
"schema_version": "1.1",
"created_by": "pr-review-and-document",
"last_writer": "pr-review-and-document",
"skill": "pr-review-and-document",
"review_round": 1,
"created_at": "YYYY-MM-DDTHH:MM:SSZ",
"updated_at": "YYYY-MM-DDTHH:MM:SSZ",
"branch": "branch-name",
"base": "main",
"issues": {
"critical": { "total": 0, "fixed": 0 },
"important": { "total": 0, "fixed": 0 },
"suggestions": { "total": 0, "fixed": 0 }
},
"agents_run": ["code-reviewer", "silent-failure-hunter", "type-design-analyzer", "pr-test-analyzer", "code-simplifier", "comment-analyzer"],
"review_sources": {
"claude": {
"last_reviewed_head": "HEAD_SHA",
"last_reviewed_at": "YYYY-MM-DDTHH:MM:SSZ",
"agents_run": ["code-reviewer", "silent-failure-hunter", "type-design-analyzer", "pr-test-analyzer", "code-simplifier", "comment-analyzer"]
},
"gemini": {
"consumed_comment_ids": [],
"last_integrated_at": null
},
"codex": {
"last_reviewed_head": null,
"last_reviewed_at": null,
"posted_finding_ids": []
}
}
}
-->
## 🤖 PR Review
**Branch:** `branch-name` → `base-branch`
**Round:** N | **Updated:** YYYY-MM-DD
**Reviewer Sources:** Claude
---
### 📊 Summary
| Category | Total | Fixed | Remaining |
|----------|-------|-------|-----------|
| 🔴 Critical | X | X | X |
| 🟡 Important | X | X | X |
| 💡 Suggestions | X | X | X |
**Status:** [✅ Ready to merge | ⚠️ Needs attention | 🔴 Blocking issues]
---
### 🔴 Critical Issues
<details open>
<summary><b>1. [Status Emoji] Issue Title</b></summary>
**File:** `path/to/file.ts:line`
**Problem:** Description of the issue.
**Fix:** Resolution or suggested fix.
</details>
[Repeat for each critical issue]
---
### 🟡 Important Issues
<details>
<summary><b>1. [Status Emoji] Issue Title</b></summary>
**File:** `path/to/file.ts:line`
**Problem:** Description.
**Fix:** Resolution.
</details>
[Repeat for each important issue]
---
### 💡 Suggestions
<details>
<summary>View N suggestions (M addressed)</summary>
| # | Suggestion | Status |
|---|------------|--------|
| 1 | Description | ✅ / ⏭️ |
</details>
---
### ✨ Strengths
- Positive observation 1
- Positive observation 2
---
### 📋 Type Design Ratings
| Type | Encap. | Express. | Useful. | Enforce. | Overall |
|------|--------|----------|---------|----------|---------|
| TypeName | X/10 | X/10 | X/10 | X/10 | **X/10** |
---
### 🎯 Action Plan
**Before Merge:**
- [ ] Action item 1
- [x] Completed item
**After Merge (Backlog):**
- [ ] Future improvement
---
<sub>Generated by pr-review-and-document skill | Round N | [View edit history](click edited)</sub>
Pipe the formatted content directly to cache-write-comment.sh via --stdin:
if [ -n "${EXPECTED_CONTENT_HASH:-}" ]; then
printf '%s\n' "$REVIEW_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/cache-write-comment.sh --stdin "$PR_NUMBER" --expected-content-hash "$EXPECTED_CONTENT_HASH"
else
printf '%s\n' "$REVIEW_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/cache-write-comment.sh --stdin "$PR_NUMBER"
fi
The script will:
.pr-review-cache/pr-{N}.json)upsert-review-comment.sh --stdin(stdin pipe,不使用 temp file)4 if another tool updated the cache after this skill read it; re-read, merge your changes into the newer comment, and retry onceConfirm the comment was posted successfully by checking the returned URL.
Use consistent status indicators:
| Indicator | Meaning |
|---|---|
| ✅ | Fixed / Resolved |
| ⏭️ | Deferred / Skipped intentionally |
| ⚠️ | Needs attention |
| 🔴 | Blocking / Critical |
When updating an existing review:
review_round and timestamps based on whether this round adds new findings:
review_round, update updated_at, update issue counts and statuses.review_round unchanged; update only review_sources.claude.last_reviewed_head and review_sources.claude.last_reviewed_at. Do not modify existing issue statuses or counts.review_sources metadata and existing non-Claude issue sections.Previous review content is preserved in GitHub's "edited" dropdown, providing full audit trail.
When reading older schema_version: "1.0" metadata, upgrade in memory before writing:
| 1.0 field | 1.1 field |
|---|---|
skill | created_by if missing, skill legacy field, and current last_writer |
agents_run | review_sources.claude.agents_run and top-level agents_run during compatibility window |
gemini_integrated_ids | review_sources.gemini.consumed_comment_ids |
gemini_integration_date | review_sources.gemini.last_integrated_at |
Do not downgrade. New writes should use comment metadata schema 1.1; the cache envelope remains schema_version: "1.0".
Use ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-upgrade.sh for this migration when possible, then use ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-replace.sh to merge the returned JSON back into the <!-- pr-review-metadata ... --> block without touching issue sections.
This skill wraps the pr-review-toolkit:review-pr command and:
If review content exceeds ~40K characters:
<details>If the current branch has no open PR:
gh pr createBefore posting the review comment:
npx claudepluginhub marxbiotech/pr-review-toolkit --plugin pr-workflowGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.