GitHub Skill

Use these scripts instead of raw gh commands for consistent error handling and structured output.

Decision Tree

Need GitHub data?
├─ PR info/diff → Get-PRContext.ps1
├─ CI check status → Get-PRChecks.ps1
├─ Review comments → Get-PRReviewComments.ps1
├─ Review threads → Get-PRReviewThreads.ps1
├─ Unique reviewers → Get-PRReviewers.ps1
├─ Unaddressed bot comments → Get-UnaddressedComments.ps1
├─ PR merged check → Test-PRMerged.ps1
├─ Copilot follow-up PRs → Detect-CopilotFollowUpPR.ps1
├─ Issue info → Get-IssueContext.ps1
└─ Need to take action?
   ├─ Create issue → New-Issue.ps1
   ├─ Create PR → New-PR.ps1
   ├─ Reply to review → Post-PRCommentReply.ps1
   ├─ Comment on issue → Post-IssueComment.ps1
   ├─ Add reaction → Add-CommentReaction.ps1
   ├─ Apply labels → Set-IssueLabels.ps1
   ├─ Set milestone → Set-IssueMilestone.ps1
   ├─ Resolve threads → Resolve-PRReviewThread.ps1
   ├─ Process AI triage → Invoke-PRCommentProcessing.ps1
   ├─ Assign Copilot → Invoke-CopilotAssignment.ps1
   ├─ Close PR → Close-PR.ps1
   └─ Merge PR → Merge-PR.ps1

Script Reference

PR Operations (scripts/pr/)

Issue Operations (scripts/issue/)

Reactions (scripts/reactions/)

Quick Examples

# Get PR with changed files
pwsh -NoProfile scripts/pr/Get-PRContext.ps1 -PullRequest 50 -IncludeChangedFiles

# Check if PR is merged before starting work
pwsh -NoProfile scripts/pr/Test-PRMerged.ps1 -PullRequest 50

# Get CI check status
pwsh -NoProfile scripts/pr/Get-PRChecks.ps1 -PullRequest 50

# Wait for CI checks to complete (timeout 10 minutes)
pwsh -NoProfile scripts/pr/Get-PRChecks.ps1 -PullRequest 50 -Wait -TimeoutSeconds 600

# Get only required checks
pwsh -NoProfile scripts/pr/Get-PRChecks.ps1 -PullRequest 50 -RequiredOnly

# Detect Copilot follow-up PRs
pwsh -NoProfile scripts/pr/Detect-CopilotFollowUpPR.ps1 -PRNumber 50

# Reply to review comment (thread-preserving)
pwsh -NoProfile scripts/pr/Post-PRCommentReply.ps1 -PullRequest 50 -CommentId 123456 -Body "Fixed."

# Resolve all unresolved review threads
pwsh -NoProfile scripts/pr/Resolve-PRReviewThread.ps1 -PullRequest 50 -All

# Create new issue
pwsh -NoProfile scripts/issue/New-Issue.ps1 -Title "Bug: Login fails" -Body "Steps..." -Labels "bug,P1"

# Create PR with validation
pwsh -NoProfile scripts/pr/New-PR.ps1 -Title "feat: Add feature" -Body "Description"

# Close PR with comment
pwsh -NoProfile scripts/pr/Close-PR.ps1 -PullRequest 50 -Comment "Superseded by #51"

# Merge PR with squash
pwsh -NoProfile scripts/pr/Merge-PR.ps1 -PullRequest 50 -Strategy squash -DeleteBranch

# Post idempotent comment (prevents duplicates)
pwsh -NoProfile scripts/issue/Post-IssueComment.ps1 -Issue 123 -Body "Analysis..." -Marker "AI-TRIAGE"

# Add reaction to single comment
pwsh -NoProfile scripts/reactions/Add-CommentReaction.ps1 -CommentId 12345678 -Reaction "eyes"

# Add reactions to multiple comments (batch - 88% faster)
pwsh -NoProfile scripts/reactions/Add-CommentReaction.ps1 -CommentId @(123, 456, 789) -Reaction "eyes"

# Acknowledge all comments on a PR (batch)
$ids = pwsh -NoProfile scripts/pr/Get-PRReviewComments.ps1 -PullRequest 42 | ConvertFrom-Json | ForEach-Object { $_.id }
pwsh -NoProfile scripts/reactions/Add-CommentReaction.ps1 -CommentId $ids -Reaction "eyes"

Common Patterns

Owner/Repo Inference

All scripts auto-infer from git remote when -Owner and -Repo are omitted.

Idempotency with Markers

Use -Marker to prevent duplicate comments:

# First call: posts comment with <!-- AI-TRIAGE --> marker
pwsh -NoProfile scripts/issue/Post-IssueComment.ps1 -Issue 123 -Body "..." -Marker "AI-TRIAGE"

# Second call: exits with code 5 (already exists)

Body from File

For multi-line content, use -BodyFile to avoid escaping issues.

Thread Management Workflow

# 1. Get unresolved threads
$threads = pwsh -NoProfile scripts/pr/Get-PRReviewThreads.ps1 -PullRequest 50 -UnresolvedOnly | ConvertFrom-Json

# 2. Reply to each thread
foreach ($t in $threads.Threads) {
    pwsh -NoProfile scripts/pr/Post-PRCommentReply.ps1 -PullRequest 50 -CommentId $t.FirstCommentId -Body "Fixed."
}

# 3. Resolve all threads
pwsh -NoProfile scripts/pr/Resolve-PRReviewThread.ps1 -PullRequest 50 -All

# 4. Merge
pwsh -NoProfile scripts/pr/Merge-PR.ps1 -PullRequest 50 -Strategy squash -DeleteBranch

Pre-Review Check

Always check if PR is merged before starting review work:

$result = pwsh -NoProfile scripts/pr/Test-PRMerged.ps1 -PullRequest 50
if ($LASTEXITCODE -eq 1) {
    Write-Host "PR already merged, skipping review"
    exit 0
}

Batch Reactions

Use batch mode for 88% faster acknowledgment of multiple comments:

# Get all review comment IDs
$comments = pwsh -NoProfile scripts/pr/Get-PRReviewComments.ps1 -PullRequest 50 | ConvertFrom-Json
$ids = $comments | ForEach-Object { $_.id }

# Batch acknowledge (saves ~1.2s per comment vs. individual calls)
$result = pwsh -NoProfile scripts/reactions/Add-CommentReaction.ps1 -CommentId $ids -Reaction "eyes" | ConvertFrom-Json

# Check results
Write-Host "Acknowledged $($result.Succeeded)/$($result.TotalCount) comments"
if ($result.Failed -gt 0) {
    Write-Host "Failed reactions: $($result.Results | Where-Object { -not $_.Success } | ForEach-Object { $_.CommentId })"
}

CI Check Verification

Check CI status before claiming PR review complete:

# Quick check - get current status
$checks = pwsh -NoProfile scripts/pr/Get-PRChecks.ps1 -PullRequest 50 | ConvertFrom-Json

if ($checks.AllPassing) {
    Write-Host "All CI checks passing"
} elseif ($checks.FailedCount -gt 0) {
    Write-Host "BLOCKED: $($checks.FailedCount) check(s) failed"
    $checks.Checks | Where-Object { $_.Conclusion -notin @('SUCCESS', 'NEUTRAL', 'SKIPPED', $null) } | ForEach-Object {
        Write-Host "  - $($_.Name): $($_.DetailsUrl)"
    }
    exit 1
} else {
    Write-Host "Pending: $($checks.PendingCount) check(s) still running"
}

Wait for checks to complete before merge:

# Poll until all checks complete (or timeout)
$checks = pwsh -NoProfile scripts/pr/Get-PRChecks.ps1 -PullRequest 50 -Wait -TimeoutSeconds 600 | ConvertFrom-Json

if ($LASTEXITCODE -eq 7) {
    Write-Host "Timeout waiting for checks"
    exit 1
}

if ($checks.AllPassing) {
    pwsh -NoProfile scripts/pr/Merge-PR.ps1 -PullRequest 50 -Strategy squash -DeleteBranch
}

Copilot Directive Prompts

GitHub Copilot is amnesiac. It has no memory of the codebase, PR context, or prior work. Every @copilot directive must be a complete, self-contained prompt.

Before posting any @copilot directive, use the prompt-builder agent to generate a high-quality prompt.

Workflow

1. Gather context (PR diff, review comments, codebase patterns)
2. Invoke prompt-builder to synthesize a comprehensive prompt
3. Post the generated prompt via issue comment or PR comment reply

# Step 1: Gather context
$pr = pwsh -NoProfile scripts/pr/Get-PRContext.ps1 -PullRequest 50 -IncludeChangedFiles | ConvertFrom-Json
$threads = pwsh -NoProfile scripts/pr/Get-UnresolvedReviewThreads.ps1 -PullRequest 50 | ConvertFrom-Json

# Step 2: Use prompt-builder agent to generate the directive
# Pass context to prompt-builder, which will create an actionable, specific prompt

# Step 3: Post the generated prompt
pwsh -NoProfile scripts/issue/Post-IssueComment.ps1 -Issue 123 -Body "$generatedPrompt"
# OR for PR comment reply:
pwsh -NoProfile scripts/pr/Post-PRCommentReply.ps1 -PullRequest 50 -CommentId 123 -Body "$generatedPrompt"

Prompt Quality Requirements

Copilot prompts MUST include:

• Specific file paths: Copilot cannot infer which files to modify
• Exact requirements: Use imperative language (MUST, WILL, NEVER)
• Success criteria: Define what "done" looks like
• Constraints: Coding standards, patterns to follow, things to avoid
• Context: Relevant code snippets, error messages, or review feedback

Anti-patterns

BAD:  "@copilot please fix this"
BAD:  "@copilot refactor the code"
BAD:  "@copilot address the review comments"

GOOD: "@copilot In src/Services/UserService.cs, refactor the GetUser method 
       to use async/await. MUST maintain the existing interface signature. 
       MUST add null checks for the userId parameter. Follow the pattern 
       in src/Services/OrderService.cs line 45-60."

When to Use Each Tool

Prompt-Builder Integration

The prompt-builder agent follows a structured process:

1. Research: Analyzes codebase patterns, README, existing code
2. Draft: Creates specific, imperative instructions
3. Validate: Tests prompt clarity through Prompt Tester persona
4. Iterate: Refines until success criteria are met

Invoke prompt-builder with the context you gathered:

Create a @copilot prompt for:
- Task: [what Copilot should do]
- Files: [which files to modify]
- Context: [PR diff, review comments, error messages]
- Constraints: [coding standards, patterns to follow]

Output Format

All scripts output structured JSON with Success boolean:

$result = pwsh -NoProfile scripts/pr/Get-PRContext.ps1 -PullRequest 50 | ConvertFrom-Json
if ($result.Success) { ... }

See Also

• references/api-reference.md: Exit codes, API endpoints, troubleshooting
• references/copilot-synthesis-guide.md: Copilot context synthesis documentation
• modules/GitHubHelpers.psm1: Shared helper functions
• .claude/agents/prompt-builder.md: Agent for creating high-quality @copilot prompts
• .claude/skills/prompt-engineer/SKILL.md: Skill for optimizing existing prompts