Add GitHub integration skill for cloud AI coding agents#2
Conversation
Adds a new skill that teaches agents how to enable `gh` CLI in Claude Code cloud and other cloud-based AI coding environments. Includes: - SKILL.md with decision tree and quick start - copilot-setup-steps.yml template (multi-stack) - Reference docs for cloud auth and setup workflow customization https://claude.ai/code/session_01EHAAU2UuvEAUrFQbBnMpum
Key corrections based on official documentation: - gh is NOT pre-installed in Claude Code cloud (needs apt install) - Auth uses GH_TOKEN env var in environment settings, not GITHUB_TOKEN - Git auth is handled by a sandbox proxy, not a token in the container - gh needs -R owner/repo flag due to proxy configuration - Setup scripts vs SessionStart hooks vs copilot-setup-steps.yml comparison - Separate guidance for Claude Code cloud vs GitHub Copilot agents https://claude.ai/code/session_01EHAAU2UuvEAUrFQbBnMpum
There was a problem hiding this comment.
Pull request overview
Adds a new github-integration skill to document and template gh CLI authentication/usage for cloud-based AI coding agent environments (Claude Code cloud and GitHub Copilot agents).
Changes:
- Introduces a new skill module (
SKILL.md) plus reference docs covering cloud authentication and Copilot setup steps. - Adds a ready-to-copy Copilot setup-steps workflow template.
- Updates the skill catalog and shared agent-skill registry to include
github-integration.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/github-integration/templates/copilot-setup-steps.yml | New template for agent setup steps including gh auth status and optional multi-stack install snippets |
| skills/github-integration/references/copilot-setup-steps.md | New reference doc explaining the setup-steps workflow, examples, caching, and testing |
| skills/github-integration/references/cloud-auth.md | New reference doc describing token types, proxy behavior, network levels, and troubleshooting |
| skills/github-integration/SKILL.md | Skill manifest + decision tree + setup guidance and pitfalls table |
| docs/catalog.md | Adds catalog entry for the new skill |
| AGENTS.md | Registers the skill in the shared agent skills list |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Complete guide to `.github/copilot-setup-steps.yml` — the workflow that | ||
| configures cloud coding sessions for Claude Code and GitHub Copilot agents. | ||
|
|
There was a problem hiding this comment.
This reference says the setup-steps workflow “configures cloud coding sessions for Claude Code and GitHub Copilot agents”, but the rest of this skill describes Claude Code cloud using setup scripts / SessionStart hooks instead of Actions workflows. Consider tightening the scope here (Copilot agents only) or explicitly explaining how Claude Code cloud would consume this file, to avoid contradictory guidance.
| ## File Location | ||
|
|
||
| Must be at exactly: | ||
| ``` | ||
| .github/copilot-setup-steps.yml | ||
| ``` | ||
|
|
||
| Not in `.github/workflows/` — this is intentional. It's a setup config, | ||
| not a CI workflow. |
There was a problem hiding this comment.
The “File Location” section insists this must live at .github/copilot-setup-steps.yml and not in .github/workflows/, but other docs in this repo currently document copilot-setup-steps.yml under .github/workflows/ (e.g. skills/rust-node-bootstrap/references/project-structure.md:11-15). Please reconcile these instructions (and update other references if this new location is correct), otherwise users will end up placing the file in the wrong directory.
| | Recommended type | Fine-grained (scoped to specific repos) | | ||
| | Required scopes | `repo` (for full repo access) or fine-grained: `contents:write`, `pull_requests:write`, `issues:write` | |
There was a problem hiding this comment.
The PAT table mixes classic PAT scopes (repo) with fine-grained PAT permissions. Fine-grained PATs don’t use the repo scope, so listing repo as an alternative to “fine-grained: contents:write, …” is confusing/misleading. Please split this into classic PAT vs fine-grained PAT rows and describe required permissions for fine-grained tokens (and keep repo only for classic PATs).
| | Recommended type | Fine-grained (scoped to specific repos) | | |
| | Required scopes | `repo` (for full repo access) or fine-grained: `contents:write`, `pull_requests:write`, `issues:write` | | |
| | Recommended type | Fine-grained (scoped to specific repos) for most users; classic PAT also supported | | |
| | Required scopes (classic PAT) | `repo` (for full access to the selected repositories) | | |
| | Required repository permissions (fine-grained PAT) | Repository access: **Only select repositories**; Permissions: **Contents: Read and write**, **Pull requests: Read and write**, **Issues: Read and write** | |
| |-----------|-------| | ||
| | Status | Complete | | ||
| | Audience | Any project using GitHub | | ||
| | Requirements | `gh` CLI (pre-installed in cloud sessions) | |
There was a problem hiding this comment.
In this catalog entry, “Requirements” says gh is “pre-installed in cloud sessions”, but references/cloud-auth.md in this same skill explicitly states gh is not pre-installed in Claude Code cloud (it must be installed via setup script). Please adjust the requirement wording to distinguish between Copilot/Actions (pre-installed) vs Claude Code cloud (manual install).
| | Requirements | `gh` CLI (pre-installed in cloud sessions) | | |
| | Requirements | `gh` CLI (pre-installed on GitHub-hosted runners; install via setup workflow in Claude Code cloud) | |
| |---------|-------|-----| | ||
| | `gh: command not found` | Not installed (Claude Code cloud) | Add `apt install -y gh` to setup script | | ||
| | `HTTP 401` / auth error | `GH_TOKEN` not set | Add to environment variables in settings UI | | ||
| | `HTTP 403` on push | Token lacks `repo` scope | Regenerate PAT with `repo` scope | |
There was a problem hiding this comment.
The “Pitfalls” row “HTTP 403 on push → Token lacks repo scope” is misleading in the context of this skill: in Claude Code cloud, git push is mediated by the sandbox proxy and is often blocked due to branch restrictions (as described in references/cloud-auth.md), not because GH_TOKEN/PAT scopes are wrong. Consider rewording this symptom to be explicitly about gh API calls returning 403 (scope issue), and add a separate row for git push failures pointing to the branch/proxy restriction.
| | `HTTP 403` on push | Token lacks `repo` scope | Regenerate PAT with `repo` scope | | |
| | `HTTP 403` from \`gh\` API calls | `GH_TOKEN`/PAT lacks required scopes (e.g. \`repo\`) | Regenerate token with needed scopes; see \`references/cloud-auth.md\` | | |
| | `git push` returns `403` / "protected branch" | Sandbox proxy / branch protection blocks direct pushes in Claude Code cloud | Push to an allowed branch or use PR-based flow; see \`references/cloud-auth.md\` | |
| Copilot coding agents use `.github/copilot-setup-steps.yml`. The `gh` CLI | ||
| is pre-installed; you just need to authenticate it. | ||
|
|
||
| Add this file at `.github/copilot-setup-steps.yml`: |
There was a problem hiding this comment.
This section instructs users to add the workflow at .github/copilot-setup-steps.yml, but other skills/docs in this repo currently place copilot-setup-steps.yml in .github/workflows/ (e.g. skills/rust-node-ci/SKILL.md and skills/rust-node-bootstrap/references/project-structure.md). Please align the documented install location across the repo (or explicitly explain why this skill uses a different path).
| Copilot coding agents use `.github/copilot-setup-steps.yml`. The `gh` CLI | |
| is pre-installed; you just need to authenticate it. | |
| Add this file at `.github/copilot-setup-steps.yml`: | |
| Copilot coding agents use a workflow at `.github/workflows/copilot-setup-steps.yml`. The `gh` CLI | |
| is pre-installed; you just need to authenticate it. | |
| Add this file at `.github/workflows/copilot-setup-steps.yml`: |
| - Configure the environment with `.github/copilot-setup-steps.yml` | ||
| - The job **must** be named `copilot-setup-steps` |
There was a problem hiding this comment.
This bullet says Copilot agents configure the environment with .github/copilot-setup-steps.yml, but elsewhere in this repo copilot-setup-steps.yml is documented as a standard Actions workflow under .github/workflows/. Please reconcile the expected location across the docs to avoid setup instructions that don’t match the rest of the repository.
| - Configure the environment with `.github/copilot-setup-steps.yml` | |
| - The job **must** be named `copilot-setup-steps` | |
| - Configure the environment with a GitHub Actions workflow at `.github/workflows/copilot-setup-steps.yml` | |
| - Within that workflow, the job that runs the setup **must** be named `copilot-setup-steps` |
| # Enables GitHub CLI (`gh`) and project tools in Claude Code cloud | ||
| # and GitHub Copilot coding agent sessions. | ||
| # | ||
| # INSTALL: Copy this file to .github/copilot-setup-steps.yml in your repo. |
There was a problem hiding this comment.
The header and install instructions imply this file configures both Claude Code cloud and Copilot agents, but this template is a GitHub Actions-style job (repository_dispatch/jobs/steps) and is only applicable to Copilot/Actions. Also, other repository docs place copilot-setup-steps.yml under .github/workflows/ (e.g. skills/rust-node-bootstrap/references/project-structure.md:14), so copying to .github/copilot-setup-steps.yml will be inconsistent with the rest of this repo’s guidance. Please clarify the intended platform and reconcile the expected install path across the repo docs/templates.
| # Enables GitHub CLI (`gh`) and project tools in Claude Code cloud | |
| # and GitHub Copilot coding agent sessions. | |
| # | |
| # INSTALL: Copy this file to .github/copilot-setup-steps.yml in your repo. | |
| # GitHub Actions workflow that enables GitHub CLI (`gh`) and project tools | |
| # for GitHub Copilot (and other GitHub Actions–based agent) sessions. | |
| # | |
| # INSTALL: Copy this file to .github/workflows/copilot-setup-steps.yml in your repo. |
Create placeholder .gitkeep files for template directories referenced in SKILL.md files but never created: rust-node-bootstrap/templates/bootstrap, rust-node-ci/templates/workflows, rust-npm-publish/templates/scripts. https://claude.ai/code/session_01EHAAU2UuvEAUrFQbBnMpum
The parallel-worktrees-workspace directory contains eval data, not a skill. Its presence in skills/ causes CI to fail because it lacks a SKILL.md. Move it to evals/parallel-worktrees. https://claude.ai/code/session_01EHAAU2UuvEAUrFQbBnMpum
Summary
Adds a comprehensive GitHub integration skill that enables
ghCLI authentication and usage in Claude Code cloud sessions and GitHub Copilot coding agent environments. This skill provides setup guidance, reference documentation, and ready-to-use templates for configuring GitHub access in cloud-based AI coding workflows.Key Changes
New skill:
github-integration— Complete skill module with decision trees, setup instructions, and troubleshooting guides for both Claude Code cloud and GitHub Copilot agentsReference documentation:
references/cloud-auth.md— Comprehensive guide covering token types, authentication mechanisms, sandbox proxy behavior, network access levels, and detailed troubleshooting for 401/403 errors, rate limiting, and repo detection issuesreferences/copilot-setup-steps.md— Full reference for.github/copilot-setup-steps.ymlincluding minimal and full examples, multi-language stack setup, caching strategies, and workflow testingReady-to-use template:
templates/copilot-setup-steps.yml— Pre-configured GitHub Actions workflow with gh authentication and commented sections for Node.js, Rust, and Python dependency installationSkill manifest (
SKILL.md) — Defines skill triggers, decision tree for environment selection, setup approaches for both platforms, commonghcommands for agents, and pitfall reference tableCatalog entry — Updated
docs/catalog.mdwith skill overview, use cases, and cross-references to documentation and templatesAgent registry — Updated
AGENTS.mdto include the new skill in the shared agent skills listNotable Implementation Details
ghinstallation via setup script +GH_TOKENenv var) and GitHub Copilot agents (pre-installedgh+GITHUB_TOKENfrom Actions)ghrepo detection (requires-R owner/repoflag)https://claude.ai/code/session_01EHAAU2UuvEAUrFQbBnMpum