Agent-Skills.md

Agent Skills: PR Review

Use when posting code review comments on pull requests via gh-review

UncategorizedID: rcdailey/dotfiles/gh-pr-review

Repository

rcdailey/dotfiles
rcdailey

Install this agent skill to your local

pnpm dlx add-skill https://github.com/rcdailey/dotfiles/tree/HEAD/home/dot_config/opencode/exact_skills/gh-pr-review

Skill Files

Browse the full folder contents for gh-pr-review.

Download Skill

Loading file tree…

home/dot_config/opencode/exact_skills/gh-pr-review/SKILL.md

Skill Metadata

Name
gh-pr-review
Description
>-

PR Review

All PR comment operations (reading, writing, replying) MUST go through gh-review. Do NOT use raw gh api or gh pr for any review-related task. Run gh-review --help and gh-review <command> --help for authoritative syntax; this skill covers workflow and semantics only.

Unlike gh, gh-review takes the repository as a positional owner/repo argument, NOT a --repo flag. The reading and review-creating commands share the shape gh-review <command> owner/repo NUMBER (e.g. gh-review view sketchy/cortex-backend 2794, gh-review start owner/repo 42).

Critical Rules

  • NEVER submit reviews. The user manually submits pending reviews via GitHub UI.
  • All new review comments MUST go through a pending review. Never post comments directly.
  • When a line target is outside diff hunks, comment automatically retries as a file-level comment on the same file. The output includes a note: line indicating the fallback. No manual retry or relocation needed.

Review Etiquette

Priorities (in order)

  • Security: Credentials, injection, auth flaws, input validation
  • Architecture: Resource config, error handling, data loss risks, breaking changes
  • Code quality: Duplication, logic errors, performance, missing config

Medium/low (only when explicitly requested): Organization, docs, test coverage, style, naming

Tone

  • Bugs/defects: Direct language ("I think this is a bug...", "This will cause...")
  • Style/architecture: Questions ("What do you think about...", "Would it make sense to...")
  • Use contractions, be conversational, comment on code not developer
  • Skip comments that just repeat what other reviewers already said
  • Bot comments (infer from context: [bot] suffix, known CI/analysis tools, automated comment patterns): use neutral, factual statements. Explain what was done and why, or why something will not be done. Do not address the bot conversationally or phrase replies as if speaking to a person.

Verification

Use ctx7 and web search to verify unfamiliar patterns, best practices, and security implications before writing comments. Every technical claim must be verified.

Pending Review Workflow

  1. gh-review view the PR. If the output includes a PENDING REVIEWS section, reuse that PRR_... ID. Otherwise, gh-review start to create one.
  2. gh-review comment for each inline comment, passing the review ID.
  3. Stop. The user submits the review manually via the GitHub UI.

To discard a pending review: gh-review delete PRR_....

Replying to Comments

gh-review reply posts to an existing thread. It auto-detects whether the target is a review thread or conversation comment and routes to the correct API.

The COMMENT_ID argument is the numeric database ID shown as #ID in view output headers (e.g. @reviewer (2026-05-14) #98765:). Extract the number after #.

Editing and Removing Comments

gh-review edit modifies an existing review comment. Two paths depending on what changed:

  • Body only (no positioning args): patches the comment in place. One API call.
  • Repositioning (any of --path, --line, --start-line, --side, --start-side): deletes the old comment and creates a new one on the same pending review. Requires both --review-id and --line, even when only --path changes (the underlying comment node does not expose its line, so it cannot be inferred). --path and --body are merged from the current comment when omitted; --side defaults to RIGHT rather than being read from the existing comment.

gh-review remove deletes a single review comment.

Both commands take the comment node ID (PRRC_... from comment output's comment-node-id field). These commands operate on pending review comments only; edit will reject published comments with an error. When this happens, do NOT fall back to reply or any other command as a workaround. Published comments can only be edited through the GitHub UI; inform the user and stop.

Line Targeting

GitHub's API only supports line-level comments on lines within diff hunks (changed lines plus surrounding context). Lines in the gap between hunks cannot be targeted as line comments.

When comment targets a non-diff line, it automatically falls back to a file-level comment on the same file (using subjectType: FILE). The output includes a note: field explaining the fallback. The comment still lands on the correct file; it just appears at the top of the file's diff rather than on a specific line.

To post a file-level comment directly (skipping the line attempt), omit --line:

gh-review comment --review-id PRR_... --path {file} --body '{body}'

Suggestion blocks: Suggestions only work on line-level comments. The --start-line to --line range defines what GitHub replaces when a suggestion is applied. The range MUST exactly match the lines being replaced. Do NOT include surrounding context lines in the range; they will be deleted.

ID Formats

  • PRR_...: Review node ID (from start or view)
  • PRRT_...: Thread node ID (emitted as the id: field by comment; not surfaced by view)
  • PRRC_...: Comment node ID (from comment output's comment-node-id field); used by edit and remove
  • #NNN: Numeric database ID (from view output or comment output's comment-id field); used by reply