docs(skills): prefer && chains in github-cli, add worktree-to-PR workflow (#150)

## Summary

- Reduce agent tool calls by chaining sequential gh/git commands with &&
across all three github-cli skill files
- Add push+PR-create combo, CI from-URL shortcut, and new anti-patterns
to SKILL.md
- Add worktree-to-draft-PR workflow to git-worktrees skill;
cross-reference from github-cli Issue-to-PR lifecycle
- Fix pre-existing missing --signoff in several workflow recipes

## Test plan

- [ ] Spot-check bash snippets for quoting and variable expansion
correctness
- [ ] Verify unquoted heredoc used where ISSUE needs expansion; quoted
elsewhere

Made with [Cursor](https://cursor.com)

Signed-off-by: aagonzales <aagonzales@nvidia.com>

Author: binaryaaron

.agent/skills/git-worktrees/SKILL.md

@@ -229,6 +229,27 @@ Lessons from real sessions working in this repo:
 
 - Dependency safety: worktrees default to sharing the main repo's `.venv` via `UV_PROJECT_ENVIRONMENT`. If the worktree changes `pyproject.toml`, unset it and run `uv sync --frozen` to create a local venv. Never run bare `uv sync` in a worktree -- it can silently modify the tracked `uv.lock` file.
 
+## Worktree to Draft PR
+
+Common pattern: make changes in a worktree and open a draft PR in one chain.
+
+```bash
+cd "$SS_WORKTREE_DIR/ss-wt-<name>" \
+  && git add -A && git commit -s -m "feat: description" \
+  && git push -u origin HEAD \
+  && gh pr create --draft --title "feat: description" --body "$(cat <<'EOF'
+## Summary
+- ...
+EOF
+)"
+```
+
+When dispatching this workflow, ask the user whether they want a worktree or a local branch. Worktrees are preferred when:
+
+- The main checkout has uncommitted work or is on a different branch
+- Multiple branches need to be active simultaneously
+- The user explicitly requested a worktree
+
 ## Quick Reference
 
 | Situation | Command |

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

@@ -18,17 +18,16 @@ 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`).
 
+## Prefer && Chains
+
+When running multiple sequential commands (pre-flight, commit, push, PR create), chain them with `&&` in a single shell call. Only use separate calls when you need to read intermediate output before deciding the next step.
+
 ## Pre-flight
 
 Before any `gh` operation, verify the binary is available and authenticated:
 
 ```bash
-# 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
+export PATH="$HOME/.local/bin:$PATH" && gh auth status
 ```
 
 ## Pull Requests
@@ -59,22 +58,26 @@ 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"
+
+# Push and create PR in one call (most common multi-step pattern)
+git push -u origin HEAD && gh pr create --draft --title "feat: short title" --body "$(cat <<'EOF'
+## Summary
+- ...
+EOF
+)"
 ```
 
 ## CI / Actions
 
 ```bash
-# Check CI status for current branch
-gh pr checks
-
-# List workflow runs
-gh run list --limit 10
+# Check CI status + recent runs in one call
+gh pr checks && gh run list --limit 5
 
-# View a failed run
-gh run view <run-id>
-
-# View failed job logs
+# When you already have the run ID (e.g. from a URL the user pasted):
 gh run view <run-id> --log-failed
+
+# Summary + logs in one call
+gh run view <run-id> && gh run view <run-id> --log-failed
 ```
 
 ## Issues
@@ -129,6 +132,8 @@ Keep bodies concise -- 2-4 bullet summary for PRs, problem + options for issues.
 
 ## Common Mistakes
 
+- Don't run `gh run view <id>` and `gh run view <id> --log-failed` as separate calls -- go straight to `--log-failed` when you already have the run ID
 - 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
+- Don't use separate shell calls for `git push` then `gh pr create` -- chain them with `&&`

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

@@ -85,12 +85,13 @@ The project has 7 GitHub Actions workflows:
 ### Investigating Failures
 
 ```bash
-# Failed runs for current branch
-gh run list --branch=$(git branch --show-current) --status=failure
-
-# View failed job logs
+# When you have a run ID (e.g. from a URL the user pasted), go straight to logs:
 gh run view <run-id> --log-failed
 
+# Find and show logs for the latest failure on this branch in one call:
+RUN_ID=$(gh run list --branch=$(git branch --show-current) --status=failure --limit=1 --json databaseId -q '.[0].databaseId') \
+  && [ "$RUN_ID" != "null" ] && gh run view "$RUN_ID" --log-failed
+
 # Full log for a specific job
 gh run view <run-id> --log --job=<job-id>
 

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

@@ -12,8 +12,6 @@ Complete check before merging a PR:
 ```bash
 PR_NUMBER=<number>
 
-# Full status in one call (avoids Projects Classic GraphQL bug with plain `gh pr view`)
-echo "=== PR Summary ==="
 gh pr view $PR_NUMBER \
   --json number,title,state,isDraft,mergeable,reviewDecision,additions,deletions,changedFiles,labels,assignees,author,statusCheckRollup,reviews \
   --jq '{
@@ -23,10 +21,8 @@ gh pr view $PR_NUMBER \
     labels: [.labels[].name],
     checks: [.statusCheckRollup[] | {name: .name, conclusion: .conclusion}],
     reviews: [.reviews[] | {author: .author.login, state: .state}]
-  }'
-
-echo "=== CI Status ==="
-gh pr checks $PR_NUMBER
+  }' \
+  && gh pr checks $PR_NUMBER
 ```
 
 Checklist:
@@ -90,8 +86,7 @@ make test-ci-container
 After fixing locally:
 
 ```bash
-git add -A && git commit -m "fix: resolve CI failure"
-git push
+git add -A && git commit -s -m "fix: resolve CI failure" && git push
 
 # Or re-run failed jobs directly
 gh run rerun $RUN_ID --failed
@@ -113,14 +108,9 @@ The release process uses the `release.yml` manual workflow dispatch.
 ### Step 1: Verify Readiness
 
 ```bash
-# Ensure main is clean and up to date
-git checkout main && git pull
-
-# Check the version in package_info.py
-grep VERSION src/nemo_safe_synthesizer/package_info.py
-
-# Confirm no open blockers
-gh issue list --label "priority:high" --state open
+git checkout main && git pull \
+  && grep VERSION src/nemo_safe_synthesizer/package_info.py \
+  && gh issue list --label "priority:high" --state open
 ```
 
 ### Step 2: Trigger the Release
@@ -171,12 +161,7 @@ gh issue view <number>
 ### Step 2: Label and Assign
 
 ```bash
-# Add appropriate labels
-gh issue edit <number> --add-label "bug"        # or "enhancement", "documentation"
-gh issue edit <number> --add-label "priority:high"
-
-# Assign to someone
-gh issue edit <number> --add-assignee username
+gh issue edit <number> --add-label "bug" --add-label "priority:high" --add-assignee username
 ```
 
 ### Step 3: Link to Milestone (if applicable)
@@ -212,35 +197,19 @@ gh pr checkout <number>
 ### Step 2: Understand the Changes
 
 ```bash
-# See the diff
-gh pr diff
-
-# List changed files
-gh pr view --json files | jq -r '.files[].path'
-
-# Read the PR description
-gh pr view <number>
+gh pr diff && gh pr view --json files -q '[.files[].path]'
 ```
 
 ### Step 3: Run Local Checks
 
 ```bash
-# Format check
-make format
-
-# Lint
-make lint
-
-# Unit tests
-make test
+make format && make lint && make test
 ```
 
 ### Step 4a: Push Fixes (if contributing to the PR)
 
 ```bash
-git add -A
-git commit -m "fix: address lint/format issues"
-git push
+git add -A && git commit -s -m "fix: address lint/format issues" && git push
 ```
 
 ### Step 4b: Leave a Review (if just reviewing)
@@ -264,6 +233,8 @@ git stash pop
 
 End-to-end workflow: create an issue, branch, implement, and open a draft PR.
 
+Before branching, ask the user whether to use a local branch (`git checkout -b`) or a worktree for isolated development. Worktrees are preferred when the main checkout has uncommitted work or when multiple branches need to be active simultaneously. See the [git-worktrees skill](../../git-worktrees/SKILL.md) for the worktree-to-draft-PR workflow.
+
 ### Step 1: Create the Issue
 
 ```bash
@@ -277,24 +248,19 @@ EOF
 )"
 ```
 
-### Step 2: Create Branch and Implement
+### Step 2: Create Branch, Implement, and Open Draft PR
 
 ```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>
+git add -A \
+  && git commit -s -m "fix: description (closes #$ISSUE)" \
+  && git push -u origin HEAD \
+  && gh pr create --draft \
+    --title "fix: description" \
+    --body "$(cat <<EOF
+Closes #$ISSUE
 
 - Change 1
 - Change 2
@@ -316,9 +282,7 @@ gh api repos/NVIDIA-NeMo/Safe-Synthesizer/pulls/<number>/comments
 Make fixes, commit with signoff:
 
 ```bash
-git add -A
-git commit -s -m "fix: address review feedback"
-git push
+git add -A && git commit -s -m "fix: address review feedback" && git push
 ```
 
 ### Step 3: Update PR Body for Squash Merge