docs(skill): expand pull-requests SKILL.md beyond inline instructions

The bundled skill now reads differently from the inline server
instructions rather than mirroring them, showing the point of
progressive disclosure: a skill-aware host spends no extra context on
every request but can pull the deeper version on demand.

Restructure into "When to use", "Workflow" (numbered steps), and
"Caveats" sections per the agentskills.io spec's recommended body
shape. Add content that is *not* in the inline instructions:
- when to skip this flow (single top-level comment / approve without
  inline feedback)
- the pending-ness hinges on omitting `event` in step 1
- specific line-ref parameter names (path, line, side, startLine,
  startSide)
- the concrete `APPROVE | REQUEST_CHANGES | COMMENT` event values
- pending reviews are invisible to the PR author and can be deleted
  via `method: "delete_pending"`

Update the embedded-content test to check for the new `## Workflow`
section header and a second tool-name presence assertion.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: olaservo

pkg/github/bundled_skills_test.go

@@ -44,8 +44,9 @@ func Test_PullRequestsSkill_EmbeddedContent(t *testing.T) {
 	assert.Equal(t, "pull-requests", frontmatterName, "frontmatter name must match final skill-path segment in %s", pullRequestsSkillURI)
 
 	body := md[4+end+5:]
-	assert.Contains(t, body, "## PR review workflow")
+	assert.Contains(t, body, "## Workflow", "skill body must carry the workflow section")
 	assert.Contains(t, body, "pull_request_review_write", "review workflow content must be preserved")
+	assert.Contains(t, body, "add_comment_to_pending_review", "review workflow content must be preserved")
 	assert.Contains(t, body, "submit_pending", "the distinctive tool method must be present")
 }
 

skills/pull-requests/SKILL.md

@@ -3,6 +3,24 @@ name: pull-requests
 description: Submit a multi-comment GitHub pull request review using the pending-review workflow (pull_request_review_write → add_comment_to_pending_review → submit_pending). Use when leaving line-specific feedback on a pull request, when asked to review a PR, or whenever creating any review with more than one comment.
 ---
 
-## PR review workflow
+## When to use
 
-PR review workflow: Always use 'pull_request_review_write' with method 'create' to create a pending review, then 'add_comment_to_pending_review' to add comments, and finally 'pull_request_review_write' with method 'submit_pending' to submit the review for complex reviews with line-specific comments.
+Use this skill when submitting a pull request review that will include more than one comment, especially line-specific comments placed on particular files or diff lines.
+
+**Skip this flow** — call `pull_request_review_write` with `method: "create"` and supply `body` and `event` directly — when:
+
+- Leaving a single top-level comment with no line references.
+- Approving or requesting changes without inline feedback.
+
+## Workflow
+
+Submit a multi-comment review using the three-step pending-review flow:
+
+1. **Open a pending review.** Call `pull_request_review_write` with `method: "create"` **and no `event`**. Omitting `event` is what makes the review pending instead of submitting it immediately.
+2. **Add each comment.** Call `add_comment_to_pending_review` once per comment, supplying `path` and a line reference (`line`/`side` for a single line, or `startLine`/`startSide` plus `line`/`side` for a multi-line range). This tool requires that a pending review already exists for the current user on this PR.
+3. **Submit the review.** Call `pull_request_review_write` with `method: "submit_pending"`, an optional summary `body`, and an `event` indicating the review state — one of `APPROVE`, `REQUEST_CHANGES`, or `COMMENT`.
+
+## Caveats
+
+- **Always complete step 3.** A pending review is invisible to the PR author until `submit_pending` is called. If you stop partway through, the draft stays on the reviewer's side and can be resumed later or removed with `method: "delete_pending"`.
+- **Do not pass `event` in step 1.** Providing `event` to `create` submits the review immediately and leaves no pending review for `add_comment_to_pending_review` to attach to.