docs(skills): update github-cli skill from chat analysis (#116)

## Summary
- Add pre-flight/PATH discovery section (agents wasted 2-3 turns per
session hunting for `gh`)
- Add draft PR, diff, check-before-create, issue edit commands
- Document HEREDOC body pattern and conciseness guidance (users asked to
"cut it down" in 4+ sessions)
- Add inline review comments via `gh api` (not accessible through `gh pr
view --json`)
- Add issue-to-PR lifecycle, review comment addressing, and retroactive
signoff workflows
- Add common mistakes section (WebFetch on private repos, missing
signoff, verbose bodies)

## Test plan
- [ ] Spot-check rendered markdown in PR diff

---------

Signed-off-by: aagonzales <aagonzales@nvidia.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: binaryaaron

.agent/skills/github-cli/SKILL.md

@@ -18,12 +18,17 @@ Note: The commands below are quick references. For comprehensive detail and mult
 
 Always use `required_permissions: ["all"]` when running `gh` commands. Sandboxed environments fail with TLS certificate errors (`x509: OSStatus -26276`).
 
-## Setup
+## Pre-flight
+
+Before any `gh` operation, verify the binary is available and authenticated:
 
 ```bash
-brew install gh
-gh auth login
-gh auth status  # verify
+# Verify gh is available (check PATH, then common install location)
+which gh 2>/dev/null || ls ~/.local/bin/gh 2>/dev/null
+# If found at ~/.local/bin/gh but not on PATH:
+export PATH="$HOME/.local/bin:$PATH"
+# Verify authentication
+gh auth status
 ```
 
 ## Pull Requests
@@ -42,6 +47,18 @@ gh pr create --title "Title" --body "Description"
 
 # Check out a PR locally
 gh pr checkout <number>
+
+# Create a draft PR (WIP)
+gh pr create --draft --title "Title" --body "Description"
+
+# View PR diff
+gh pr diff <number>
+
+# Check if a PR already exists for the current branch before creating
+gh pr view --json number,url 2>/dev/null && echo "PR exists" || echo "No PR yet"
+
+# Edit an existing PR's title/body
+gh pr edit <number> --title "New title" --body "New body"
 ```
 
 ## CI / Actions
@@ -66,6 +83,9 @@ gh run view <run-id> --log-failed
 gh issue list
 gh issue view <number>
 gh issue create --title "Title" --body "Description"
+
+# Edit an existing issue
+gh issue edit <number> --body "Updated body"
 ```
 
 ## Code Review
@@ -88,3 +108,27 @@ gh release list
 gh release view <tag>
 gh release create <tag> --generate-notes
 ```
+
+## Writing PR and Issue Bodies
+
+Always use HEREDOC for multiline bodies:
+
+```bash
+gh pr create --title "feat: short title" --body "$(cat <<'EOF'
+## Summary
+- 2-4 bullet points, not a full audit
+
+## Test plan
+- [ ] Verify X
+- [ ] Check Y
+EOF
+)"
+```
+
+Keep bodies concise -- 2-4 bullet summary for PRs, problem + options for issues. Don't generate long audit dumps or parameter inventories. When the user asks for "succinct" -- 1-3 sentences, no lists.
+
+## Common Mistakes
+
+- Don't WebFetch GitHub Actions URLs for private repos -- use `gh run view` instead (auth required)
+- Don't propose `gh pr create` without checking if a PR already exists first
+- Don't generate long PR/issue bodies -- users consistently ask agents to cut them down

.agent/skills/github-cli/references/full-reference.md

@@ -27,6 +27,35 @@ gh pr view <number> --json number,title,state,url,headRefName,baseRefName,isDraf
   }'
 ```
 
+## Review Comments
+
+`gh pr view --json comments` returns top-level PR conversation comments only. Inline code review comments (attached to specific diff lines) require the REST API:
+
+```bash
+# Inline code review comments on a PR
+gh api repos/NVIDIA-NeMo/Safe-Synthesizer/pulls/<number>/comments
+
+# Issue discussion thread
+gh api repos/NVIDIA-NeMo/Safe-Synthesizer/issues/<number>/comments
+```
+
+## Useful Data Extraction
+
+```bash
+# Get a PR's base commit SHA (useful for lockfile diff diagnosis)
+gh pr view <number> --json baseRefOid -q .baseRefOid
+```
+
+## Repo Settings via API
+
+```bash
+# Configure squash merge to use PR title + body as commit message
+gh api repos/NVIDIA-NeMo/Safe-Synthesizer \
+  --method PATCH \
+  -f squash_merge_commit_title=PR_TITLE \
+  -f squash_merge_commit_message=PR_BODY
+```
+
 ## CODEOWNERS
 
 Defined in `.github/CODEOWNERS`:

.agent/skills/github-cli/references/workflows.md

@@ -259,3 +259,91 @@ gh pr review <number> --request-changes --body "Format check fails locally, see
 git checkout -
 git stash pop
 ```
+
+## Issue-to-PR Lifecycle
+
+End-to-end workflow: create an issue, branch, implement, and open a draft PR.
+
+### Step 1: Create the Issue
+
+```bash
+gh issue create \
+  --title "fix: short description of the problem" \
+  --body "$(cat <<'EOF'
+Problem statement in 1-2 sentences.
+
+Proposed fix: brief description.
+EOF
+)"
+```
+
+### Step 2: Create Branch and Implement
+
+```bash
+ISSUE=<number-from-step-1>
+git checkout -b $USER/$ISSUE-short-name origin/main
+# ... make changes ...
+git add -A
+git commit -s -m "fix: description (closes #$ISSUE)"
+git push -u origin HEAD
+```
+
+### Step 3: Open Draft PR
+
+```bash
+gh pr create --draft \
+  --title "fix: description" \
+  --body "$(cat <<'EOF'
+Closes #<issue-number>
+
+- Change 1
+- Change 2
+EOF
+)"
+```
+
+## Fetch and Address Review Comments
+
+### Step 1: Get Inline Comments
+
+```bash
+# Inline code review comments (not available via gh pr view --json)
+gh api repos/NVIDIA-NeMo/Safe-Synthesizer/pulls/<number>/comments
+```
+
+### Step 2: Address Comments in Code
+
+Make fixes, commit with signoff:
+
+```bash
+git add -A
+git commit -s -m "fix: address review feedback"
+git push
+```
+
+### Step 3: Update PR Body for Squash Merge
+
+```bash
+gh pr edit <number> --body "$(cat <<'EOF'
+## Summary
+- Updated summary reflecting all changes
+
+## Test plan
+- [x] Tests pass
+EOF
+)"
+```
+
+## Retroactive Signoff
+
+If commits were pushed without `--signoff` (`-s`):
+
+```bash
+# Amend the last commit to add signoff
+git commit --amend --signoff --no-edit
+git push --force-with-lease
+
+# For multiple commits, interactive rebase (careful -- rewrites history)
+git rebase --signoff HEAD~<n>
+git push --force-with-lease
+```