Discuss locally → prepare friendly comments → dry-run preview → user confirms → atomic submit
Control plane (this SKILL.md) handles conversation, tone, orchestration.
Data plane (JS script) handles validation, API calls, safety.

Tone Guidelines

Claude prepares comments following these rules:

Rule	Description	Example
Questions over commands	Use "would it make sense to" instead of "change this to"	"Would it make sense to extract this to a shared utility?"
Code, not person	Subject is the code, not "you"	"This logic seems to..." not "You wrote..."
Explain why	Give the reason, not just the what	"If one copy gets a bug fix but the other doesn't..."
Assume good intent	Confirm rather than accuse	"Just want to confirm this trade-off is intentional"
Praise first	Acknowledge before suggesting	"This async design is great. One thought though..."
No emoji	Unless user explicitly requests	--
Follow PR language	Match the language used in the PR	--

Internal classification (Conventional Comments, not shown in output):

Label	Purpose	Blocking
`suggestion`	Improvement proposal	Configurable
`question`	Clarification	No
`issue`	Points out a problem	Yes
`nitpick`	Stylistic preference	No
`praise`	Positive feedback	No

Workflow

sequenceDiagram
    participant U as User
    participant C as Claude (Conversation)
    participant SK as SKILL.md (Orchestration)
    participant JS as pr-comment.js (Data Plane)
    participant GH as GitHub API

    Note over U,C: Phase 1: Natural conversation
    U->>C: Discuss PR diff, observations
    C->>U: Draft N friendly comments
    U->>C: Adjust tone / content / count

    Note over U,GH: Phase 2: Skill invoked
    U->>SK: /pr-comment [PR#]
    SK->>SK: Collect comments from conversation

    SK->>JS: prepare --pr N --repo owner/repo --input comments.json
    JS->>GH: gh pr view (metadata)
    JS->>GH: gh api pulls/N/files (changed files)
    JS->>GH: gh api pulls/N (head SHA)
    JS-->>SK: Validated payload + validation summary

    SK->>U: Dry-run preview (default)

    alt User confirms
        SK->>U: AskUserQuestion gate
        U->>SK: Approved
        SK->>JS: submit --pr N --repo owner/repo --input payload.json
        JS->>JS: Re-fetch head SHA, drift check
        JS->>GH: POST /repos/{owner}/{repo}/pulls/{N}/reviews
        GH-->>JS: 200/201 Success
        JS-->>SK: Success + review URL
        SK->>U: Review posted successfully
    end

Step-by-Step

Step 0: Collect Comments

From the conversation context, gather the user's review comments. Each comment needs:

Field	Required	Default	Description
`path`	Yes	--	File path (repo-relative)
`line`	Yes	--	Line number (positive integer)
`side`	No	`RIGHT`	`RIGHT` (new) or `LEFT` (deleted)
`body`	Yes	--	Comment content

Step 1: Prepare (Dry-run)

Write the comments to a temp JSON file, then run:

bash scripts/run-skill.sh pr-comment pr-comment.js \
  prepare --pr <N> --repo <owner/repo> --input <comments.json>

Parse the JSON output. Display to user:

## PR #<N>: <title>
**Target**: <owner/repo> | **Head**: <branch> | **State**: <state>

### Comments to Post (<valid>/<total> valid)

| # | File | Line | Side | Preview |
|---|------|------|------|---------|
| 1 | path/to/file.go | 136 | RIGHT | First 80 chars of body... |

### Validation
- Valid: N | Invalid: M (excluded) | Warnings: K

If invalid comments exist, show them with reasons. If warnings exist, note them but include in payload.

Step 2: Confirm

Use AskUserQuestion to get user approval before submitting.

Step 3: Submit

Save the prepare output (including payload) to a temp file, then run:

bash scripts/run-skill.sh pr-comment pr-comment.js \
  submit --pr <N> --repo <owner/repo> --input <payload.json>

Step 4: Handle Results

Exit Code	Meaning	Action
0	Success	Report review URL
2	Error (including 422)	Report error details
3	SHA drift	Warn user, offer to re-prepare

SHA Drift Handling

If submit returns exit 3:

Inform user: "PR head has changed since prepare"
Re-run prepare with new SHA
Show updated dry-run preview
AskUserQuestion for re-confirmation
Re-submit

Verification Checklist

Comments collected from conversation context
prepare validates paths against changed files
prepare validates line numbers (positive integer)
prepare validates body (non-empty)
Dry-run preview shown to user before submit
AskUserQuestion gate before submit
SHA drift detected and handled
Review URL reported on success
jq + temp file pattern used (no shell interpolation)

References

references/api-and-guardrails.md -- API contract + safety rules + exit codes

Need	Use Instead
Read existing PR review comments	`/load-pr-review`
Create a code review (automated)	`/codex-review-fast` or `/codex-review`
Create a PR	`/create-pr`
PR status overview	`/pr-summary`

pr-comment

PR Comment

Trigger Keywords

When NOT to Use

Core Principle