github skill

GitHub Skill

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

---

Triggers

Phrase	Operation
create a PR	new_pr.py
respond to review comments	post_pr_comment_reply.py
check CI status	get_pr_checks.py / get_pr_check_logs.py
close issue	close_issue.py
add label to issue	set_issue_labels.py

---

Transport Preflight

gh can be installed, hold a token, and still be refused for a whole session (agent sandboxes that proxy egress do this). Decide the transport once, before the first GitHub call:

# CLAUDE_PLUGIN_ROOT is set in a vendored install; falls back to .claude in-repo.
SCRIPTS_DIR="${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/github/scripts/utils"
python3 "$SCRIPTS_DIR/check_github_transport.py"

Non-POSIX hosts do not run the block above. The authoritative, per-harness launcher for this one command is check_transport in the scripts map of pr-review-config.yaml: the copilot entry runs it under PowerShell and resolves the interpreter (python3, then py -3, then python), because a Windows host may expose only the launcher. Read it from the map for the harness you are on rather than transcribing a second copy here, which would drift.

• Transport: gh (exit 0). Use the scripts below. This is CI and a normal developer machine.
• Transport: gh_unusable (exit 0). gh cannot reach GitHub here. Route the work through the GitHub MCP operations and do not re-try the scripts to confirm. The verdict names only what was measured: confirm the operations you need are exposed before relying on them. Tool spelling differs by harness (mcp__github__<op> in Claude Code, github/<op> in Copilot CLI).
• Exit 3 or 4. Not a transport problem: a quota window or a fixable token.

Script-to-tool mapping, the operations with no MCP equivalent, and the rules for reporting one: references/transport-routing.md.

A transport failure is an unknown, never a verdict. Do not report a PR as blocked, red, or unmergeable because the API was unreachable.

---

Decision Tree

Which transport? → check_github_transport.py (run once, before the rest)

Need GitHub data?
├─ List PRs (filtered) → get_pull_requests.py
├─ PR info/diff → get_pr_context.py
├─ CI check status → get_pr_checks.py
├─ Failing check also red on main? → triage_red_check.py
├─ CI failure logs → get_pr_check_logs.py
├─ Review comments → get_pr_review_comments.py
├─ Review threads → get_pr_review_threads.py
├─ Review verdicts (approved / changes requested) → get_pr_reviews.py
├─ Bot CHANGES_REQUESTED blocking after threads resolve → detect_stale_bot_review.py
├─ Unique reviewers → get_pr_reviewers.py
├─ Unaddressed bot comments → get_unaddressed_comments.py
├─ PR merged check → test_pr_merged.py
├─ Copilot follow-up PRs → detect_copilot_followup_pr.py
├─ Validate PR description → validate_pr_description.py
├─ Issue info → get_issue_context.py
├─ Issue parent, sub-issues, blockers, related → get_issue_relationships.py
├─ Merge readiness check → test_pr_merge_ready.py
├─ PR reports blocked/dirty and cause is unclear → why_pr_blocked.py
├─ Latest milestone → get_latest_semantic_milestone.py
├─ Actionable backlog → get_actionable_items.py
└─ Need to take action?
   ├─ Create issue → new_issue.py
   ├─ Create PR → new_pr.py
   ├─ Comment on a diff line → new_pr_review_comment.py
   ├─ Reply to review → post_pr_comment_reply.py
   ├─ Reply to thread (GraphQL) → add_pr_review_thread_reply.py
   ├─ Comment on issue → post_issue_comment.py
   ├─ Add reaction → add_comment_reaction.py
   ├─ Apply labels → set_issue_labels.py
   ├─ Set issue milestone → set_issue_milestone.py
   ├─ Set PR/issue milestone (auto-detect) → set_item_milestone.py
   ├─ Assign issue → set_issue_assignee.py
   ├─ Link issues (parent, sub-issue, blocked-by, blocking, relates-to) → set_issue_relationship.py
   ├─ Resolve threads → resolve_pr_review_thread.py
   ├─ Unresolve threads → unresolve_pr_review_thread.py
   ├─ Process AI triage → invoke_pr_comment_processing.py
   ├─ Assign Copilot → invoke_copilot_assignment.py
   ├─ Toggle auto-merge → set_pr_auto_merge.py
   ├─ Update PR branch with its base (server side) → update_pr_branch.py
   ├─ Rerun failed CI jobs on a PR or run → rerun_failed_jobs.py
   ├─ Draft PR ready or back → set_pr_ready.py
   ├─ Close PR → close_pr.py
   └─ Merge PR → merge_pr.py

---

Offline Invocation

In a network-restricted sandbox (triage, PR status checks), run read-only PR scripts under scripts/pr/ with bare python3, not uv run.

uv run <script> resolves the whole project environment first, which downloads anthropic==0.116.0 (a core dependency in pyproject.toml) from PyPI and times out with no network. The read-only PR scripts never import the anthropic SDK. They import only github_core, which parses YAML with a vendored fallback when PyYAML is absent, so no third-party import is required.

# No PyPI round trip. Runs read-only PR status offline.
# CLAUDE_PLUGIN_ROOT is set in a vendored install; falls back to .claude in-repo.
SCRIPTS_DIR="${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/github/scripts/pr"
python3 "$SCRIPTS_DIR/get_pull_requests.py" --state open
python3 "$SCRIPTS_DIR/get_pr_context.py" --pr <N>
python3 "$SCRIPTS_DIR/get_pr_checks.py" --pr <N>

Any python3 works: github_core falls back to a vendored YAML parser when PyYAML is absent, confirmed by running these scripts with both PyYAML and the anthropic SDK blocked. The interpreter from scripts/bootstrap-vm.sh and a project .venv/bin/python3 both ship PyYAML for the faster path. Do not use uv run for read-only triage offline; it forces the resolve that fetches anthropic.

The regression guard tests/test_pr_scripts_offline.py asserts the read-only PR scripts and github_core import with the anthropic SDK blocked.

---

Scripts

PR Operations (scripts/pr/)

Script	Purpose	Key Parameters
get_pull_requests.py	List PRs with filters	--state, --label, --author, --base, --head, --search, --limit
get_pr_context.py	PR metadata, diff, files	--pull-request, --include-changed-files, --include-diff
get_pr_checks.py	CI check status with polling (full text: references/script-catalog.md)	--pull-request, --wait, --timeout-seconds, --missing-grace-seconds, --required-only, --output-format {json,human,auto}
get_pr_check_logs.py	Failing CI check logs; names each failed step (FailedSteps)	--pull-request, --check-name (repeatable, case-insensitive), --max-lines, --context-lines
triage_red_check.py	CI triage step 1: is a failing PR check also red on main? Exit 0 green on main, 1 red on main, 3 cannot determine	--check-name, --branch, --history-depth, --pull-request
get_pr_review_comments.py	Paginated review comments with stale detection	--pull-request, --include-issue-comments, --detect-stale, --exclude-stale, --only-stale
get_pr_review_threads.py	Thread-level review data	--pull-request, --unresolved-only
get_pr_reviews.py	Review submissions (verdict state and body)	--pull-request, --state, --output-format {json,human,auto}
detect_stale_bot_review.py	Classify a stale bot CHANGES_REQUESTED review that blocks merge; emits the human dismissal handoff, never dismisses	--pull-request, --output-format {json,human,auto}
get_pr_reviewers.py	Enumerate unique reviewers	--pull-request, --exclude-bots
get_unaddressed_comments.py	Bot comments needing attention	--pull-request
get_unresolved_review_threads.py	Unresolved thread IDs	--pull-request
wait_for_unresolved_zero.py	Settling gate: poll until unresolved count holds at zero across bot scans	--pull-request, --interval-seconds, --max-wait-seconds, --strict-pagination
test_pr_merged.py	Check if PR is merged	--pull-request
detect_copilot_followup_pr.py	Detect Copilot follow-up PRs	--pr-number, --owner, --repo
new_pr_review_comment.py	New diff-line comment	--pull-request, --path, --line, --side (default RIGHT), --body or --body-file, --dry-run
post_pr_comment_reply.py	Threaded replies	--pull-request, --comment-id, --body, --dry-run
add_pr_review_thread_reply.py	Reply to thread by ID (GraphQL)	--pull-request, --thread-id, --body, --resolve (needs one of --expected-head-sha, --expected-base-ref, --expected-base-sha)
resolve_pr_review_thread.py	Mark threads resolved	--thread-id --expected-pull-request or --pull-request --all
unresolve_pr_review_thread.py	Unresolve threads	--thread-id or --pull-request --all, --dry-run
get_thread_by_id.py	Get single thread by ID	--thread-id
get_thread_conversation_history.py	Full thread comment history	--thread-id, --include-minimized
test_pr_merge_ready.py	Check merge readiness	--pull-request, --ignore-ci, --ignore-threads
why_pr_blocked.py	Explain a blocked PR, or say no cause holds (full text: references/script-catalog.md)	--pull-request, --base-branch, --output-format {json,human,auto}
set_pr_auto_merge.py	Enable/disable auto-merge	--pull-request, --enable/--disable, --merge-method, --dry-run
invoke_pr_comment_processing.py	Process AI triage	--pr-number, --verdict, --findings-json, --dry-run
new_pr.py	Create PR, validated	--title, --body, --body-file, --prepare-body-file, --preflight, --base, --head, --draft, --skip-validation, --audit-reason, --validation-base, --dry-run
validate_pr_description.py	Validate PR description	--title, --body, --body-file, --fail-on-violation
update_pr_branch.py	Server-side "Update branch". Exit 0 requested, done, or current; exit 1 PR not open or head differs from --expected-head-sha (head_moved); exit 2 not found; exit 3 other API failure or --wait timeout; exit 4 auth. Unattended callers pass the SHA	--pull-request, --expected-head-sha, --wait, --timeout-seconds, --dry-run
rerun_failed_jobs.py	Rerun failed Actions jobs. Exit 1 run in progress; exit 100 cannot_be_retried (no retry, prints fallbacks). Never use an empty commit	--pull-request or --run-id, --job-id, --dry-run
set_pr_ready.py	Draft to ready, or back. Exit 0 done or no-op; 1 not open or head_moved; 2 not found; 3 API or unverified; 4 auth	--pull-request, --expected-head-sha, --draft, --dry-run
close_pr.py	Close PR with comment	--pull-request, --comment, --dry-run
reopen_pr.py	Reopen a closed PR (merged is exit 1)	--pull-request, --comment, --dry-run
merge_pr.py	Merge pinned to the reviewed head, then read back and audited (ADR-112)	--pull-request, --expected-head-sha, --strategy, --delete-branch, --auto, --dry-run
audit_closing_claims.py	Fleet audit of open-PR closing claims; exit 1 on an unsupported claim, exit 3 without an administration-read token (full text: references/script-catalog.md)	--state open, --artifact, --resume-from, --output-format {json,human,auto}
edit_pr_body.py	PR body edit, SHA-256 guard	--pull-request, --body/--body-file, --expected-hash, --dry-run

Issue Operations (scripts/issue/)

Script	Purpose	Key Parameters
get_issue_context.py	Issue metadata (no comments)	--issue
list_issues.py	List issues	--milestone
get_issue_comments.py	Issue comments	--issue, --limit
new_issue.py	Create issue; --source required, agent needs Step 0	--title, --body, --labels, --source, --blocked-by, --signal, --milestone, --dry-run
close_issue.py	Close with optional comment (full text: references/script-catalog.md)	--issue, --reason, --comment, --verify-claims, --dry-run
reopen_issue.py	Reopen with optional comment	--issue, --comment, --dry-run
set_issue_labels.py	Labels	--issue, --labels, --remove-labels, --priority, --dry-run
set_issue_milestone.py	Assign milestone	--issue, --milestone, --dry-run
post_issue_comment.py	Comments with idempotency	--issue, --body, --marker, --dry-run
invoke_copilot_assignment.py	Context for Copilot	--issue-number, --what-if
set_issue_assignee.py	Assign users	--issue, --assignees, --dry-run
get_issue_relationships.py	Native parent, sub-issues, blocked-by, blocking, relates-to	--issue
set_issue_relationship.py	Add or remove a native issue link (idempotent)	--issue, --relation, --target, --remove, --replace-parent, --dry-run

Milestone Operations (scripts/milestone/)

Script	Purpose	Key Parameters
get_latest_semantic_milestone.py	Latest semantic-version milestone	--owner, --repo
set_item_milestone.py	Assign milestone to PR/issue (auto-detect)	--item-type, --item-number, --milestone-title, --dry-run

Repository Settings (repo/ scripts)

Script	Purpose	Key Parameters
manage_squash_merge_message.py	Read or update squash_merge_commit_message behind an expected-value guard (full text: references/script-catalog.md)	--set, --expected-current, --dry-run, --output-format {json,human,auto}

Reactions (scripts/reactions/)

Script	Purpose	Key Parameters
add_comment_reaction.py	Add emoji reactions (batch)	--comment-id, --reaction, --comment-type, --pull-request, --dry-run

Notifications (scripts/notifications/)

Script	Purpose	Key Parameters
get_actionable_items.py	List actionable backlog (reviews, PRs, issues)	--owner, --repo, --limit

Utilities (scripts/utils/)

Script	Purpose	Key Parameters
extract_github_context.py	Extract issue/PR references from text	--text, --require-pr, --require-issue
check_github_transport.py	Report whether this session should use gh or the MCP tools	--output-format

More Scripts

Parameters: references/script-catalog.md. Gate-script usage and exit codes: references/gate-script-usage.md. PR: check_pr_live_state.py, get_pr_code_scanning_alerts.py, check_pr_round_cap.py, run_completion_gate.py, check_review_thread_resolution_shas.py, check_suppressed_review_findings.py, detect_stale_pr_comments.py, get_pr_comments_by_reviewer.py, prepare_pr_body.py. Issue: check_existing_pr_for_issue.py, claim_issue.py, edit_issue_body.py, redact_secrets.py.

Workflow Testing (scripts/)

Script	Purpose	Key Parameters
test_workflow_locally.py	Test Actions locally with act	--workflow, --event, --job, --dry-run

---

Output Format

All scripts output structured JSON wrapped in a standard envelope per ADR-051.

Success envelope:

{
  "Success": true,
  "Data": { "Number": 42, "Title": "..." },
  "Error": null,
  "Metadata": { "Script": "get_pr_checks.py", "Version": "1.0.0", "Timestamp": "..." }
}

Error envelope:

{
  "Success": false,
  "Data": null,
  "Error": { "Message": "PR not found", "Code": 2, "Type": "NotFound" },
  "Metadata": { "Script": "get_pr_checks.py", "Version": "1.0.0", "Timestamp": "..." }
}

Usage:

SCRIPTS_DIR="${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/github/scripts"
result=$(python3 "$SCRIPTS_DIR/pr/get_pr_context.py" --pull-request 50)
echo "$result" | jq '.Data'

Exit codes follow ADR-035: 0=success, 1=logic error, 2=config error, 3=external failure, 4=auth error.

---

Process

Basic Usage:

1. Identify the operation needed using the Decision Tree
2. Find the corresponding script in the Script Reference
3. Call the script with required parameters
4. Parse the JSON output
5. Reading an issue or PR: read the full discussion, open every linked item, recurse until no new links

Example Flow:

SCRIPTS_DIR="${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/github/scripts"

# Get PR context
python3 "$SCRIPTS_DIR/pr/get_pr_context.py" --pull-request 123

# Check CI status
python3 "$SCRIPTS_DIR/pr/get_pr_checks.py" --pull-request 123

# Reply in a thread (new_pr_review_comment.py starts one)
python3 "$SCRIPTS_DIR/pr/post_pr_comment_reply.py" --pull-request 123 --comment-id 456 --body "CI failures detected"

---

GitHub Keywords for Issue Linking

GitHub automatically links and closes issues when PRs use specific keywords in PR descriptions, commit messages, or PR comments.

Supported Keywords

Keyword	Variations	Example
Closes	close, closed	Closes #<number>
Fixes	fix, fixed	Fixes #<number>
Resolves	resolve, resolved	Resolves #<number>

Usage Patterns

In PR Descriptions:

## Summary
This PR adds feature X.

Closes #<number>
Fixes #<number>

In Commit Messages:

feat: Add feature X

Implements the new feature as specified.

Closes #<number>

Best Practices:

• Use keywords in PR description for primary issue
• Use keywords in commit bodies for related issues
• One keyword per line for clarity
• Place keywords in dedicated section or at end of description

---

Linking Issues to Each Other

A #<number> in an issue body is text only. It sets no parent, no dependency, and no relation. Whenever an issue body names another issue as a parent, child, blocker, or context, add the native link with set_issue_relationship.py.

The text says	--relation
"Parent", "child of #N", "part of epic #N", "umbrella #N"	parent
An epic lists its children	sub-issue
"Blocked by #N", "depends on #N", or an epic's execution steps name #N	blocked-by
"Blocks #N", "unblocks #N"	blocking
Problem statement, context, "split out of #N", "follow-up to #N"	relates-to

After new_issue.py, link the new issue in the next call. Pull requests cannot be linked this way; use a closing keyword. Full decision rules, the audit procedure, and the MCP fallback: references/issue-relationships.md.

Issue Provenance

new_issue.py requires --source, which records who selected the work:

• human: an explicit human request selected this issue. An owner login, a human-started session, or a user approving publication does not qualify.
• agent: anything an agent chose. It also needs Step 0 evidence: --blocked-by (who is blocked, and on what) and --signal (the metric, log, run, or ticket that proves it). A body that already carries a ## Step 0 block with ### Q3 and ### Q5 supplies the evidence instead; passing both is an error.

Blank answers, canonical hedge phrases, and conflicting source:* labels exit 2 before any GitHub call. The script creates the source:human or source:agent label when the repository lacks it, and passes it to gh issue create itself, so a label failure creates no issue. The script redacts flag evidence before it publishes it. It refuses a body Step 0 block that carries a secret, because it publishes the body unchanged.

--source human also appends <!-- source:human --> as the last body line. The script rejects that marker in any other body.

Ground repo-state issues first: guide.

The GitHub MCP issue_write tool, raw gh issue create, and workflow steps that call the API bypass this script's check. The Label Issue Source workflow labels those issues: bots and owner-login issues without a trailing human marker get source:agent, a burst of owner issues within ten minutes forces source:agent, and every other author gets source:human. It only labels.

---

Anti-Patterns

Avoid	Why	Instead
Raw gh pr view commands	No structured output	Use get_pr_context.py
Raw gh api for comments	Doesn't preserve threading	Use post_pr_comment_reply.py
Replying to thread expecting auto-resolve	Replies DON'T auto-resolve threads	Use resolve_pr_review_thread.py after reply
Inline issue creation	Missing validation	Use new_issue.py
"Blocked by #N" or "Parent: #N" in a body with no native link	GitHub shows no dependency, parent, or progress	Add the link with set_issue_relationship.py
Raw gh api graphql for addSubIssue, addBlockedBy, addRelatesTo	No idempotency, no PR or parent-conflict guard	Use set_issue_relationship.py
Multiple individual reactions	88% slower	Use batch mode in add_comment_reaction.py
Hardcoding owner/repo	Breaks in forks	Let scripts infer from git remote
Ignoring exit codes	Missing error handling	Check exit codes per ADR-035
Skipping idempotency markers	Duplicate comments	Use --marker parameter
Raw gh notify or notifications API	403 with app tokens	Use get_actionable_items.py
Retrying gh after a session refusal	The refusal has no reset; retries only burn the budget	Run the transport preflight, then use the GitHub MCP operations
Reporting a PR blocked because a call failed	An unreachable API is an unknown, not a verdict	Name the transport failure as the cause
Treating mergeable_state/mergeStateStatus: blocked as self-explanatory	It is a cached, frequently-stale field. why_pr_blocked.py does not query reviewDecision or the required-approving-review count	Run why_pr_blocked.py first and resolve unresolved threads with resolve_pr_review_thread.py. Details: references/api-reference.md, "Blocked PR diagnosis"

---

See Also

Document	Content
examples.md	Script examples
patterns.md	Reusable workflow patterns
copilot-prompts.md	Creating @copilot directives
copilot-synthesis-guide.md	Copilot context synthesis
api-reference.md	Exit codes, endpoints, body-file rule, troubleshooting
transport-routing.md	Picking gh or the MCP tools, and the script-to-tool map
issue-relationships.md	Choosing parent, sub-issue, blocked-by, blocking, or relates-to
scripts/github_core/	Shared Python helper functions

---

Verification

Before completing a GitHub operation:

• Correct script selected from Decision Tree
• Required parameters provided (PR/issue number)
• Response JSON parsed successfully
• Exit code is 0 (success)
• State change verified (for mutating operations)