diff --git a/AGENTS.md b/AGENTS.md index 5a60837..135ba53 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,6 +18,7 @@ Shared agent skills for Codervisor projects (Ising, Cueless, Synodic, and others | `rust-npm-publish` | Publish Rust binaries to npm via the optionalDependencies platform package pattern | Ising, Cueless, Synodic | | `rust-node-ci` | GitHub Actions CI/CD workflows and installable composite actions | Ising, Cueless, Synodic | | `parallel-worktrees` | Parallel AI agent sessions in git worktrees with GitHub PR sync | Any | +| `github-integration` | Enable `gh` CLI in Claude Code cloud and other cloud AI coding environments | Any | ## Consuming Projects diff --git a/docs/catalog.md b/docs/catalog.md index 964abdf..a1e57dd 100644 --- a/docs/catalog.md +++ b/docs/catalog.md @@ -132,6 +132,43 @@ up after merging. --- +### github-integration + +**Enable `gh` CLI in Claude Code cloud and other cloud-based AI coding environments.** + +| Attribute | Value | +|-----------|-------| +| Status | Complete | +| Audience | Any project using GitHub | +| Requirements | `gh` CLI (pre-installed in cloud sessions) | +| Directory | [`skills/github-integration/`](../skills/github-integration/) | + +**Use when:** Setting up a repo so Claude Code cloud can create PRs and issues, +adding `copilot-setup-steps.yml`, troubleshooting `gh` auth failures in cloud +sessions, or configuring `GITHUB_TOKEN` for headless environments. + +**Covers:** +- `copilot-setup-steps.yml` setup and customization +- `gh` authentication via `GITHUB_TOKEN` / `GH_TOKEN` +- Token scopes and permissions +- Troubleshooting auth failures, 401/403 errors, and rate limiting +- Common `gh` commands for AI agents (PRs, issues, API) + +**References:** + +| File | Purpose | +|------|---------| +| `references/cloud-auth.md` | Token auth, scopes, and troubleshooting | +| `references/copilot-setup-steps.md` | Full guide to customizing the setup workflow | + +**Templates:** + +| File | Purpose | +|------|---------| +| `templates/copilot-setup-steps.yml` | Ready-to-install setup workflow with multi-stack support | + +--- + ## Installation ```bash diff --git a/skills/parallel-worktrees-workspace/evals/evals.json b/evals/parallel-worktrees/evals/evals.json similarity index 100% rename from skills/parallel-worktrees-workspace/evals/evals.json rename to evals/parallel-worktrees/evals/evals.json diff --git a/skills/parallel-worktrees-workspace/iteration-1/benchmark.json b/evals/parallel-worktrees/iteration-1/benchmark.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/benchmark.json rename to evals/parallel-worktrees/iteration-1/benchmark.json diff --git a/skills/parallel-worktrees-workspace/iteration-1/benchmark.md b/evals/parallel-worktrees/iteration-1/benchmark.md similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/benchmark.md rename to evals/parallel-worktrees/iteration-1/benchmark.md diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-0-parallel-session-setup/eval_metadata.json b/evals/parallel-worktrees/iteration-1/eval-0-parallel-session-setup/eval_metadata.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-0-parallel-session-setup/eval_metadata.json rename to evals/parallel-worktrees/iteration-1/eval-0-parallel-session-setup/eval_metadata.json diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-0-parallel-session-setup/with_skill/grading.json b/evals/parallel-worktrees/iteration-1/eval-0-parallel-session-setup/with_skill/grading.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-0-parallel-session-setup/with_skill/grading.json rename to evals/parallel-worktrees/iteration-1/eval-0-parallel-session-setup/with_skill/grading.json diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-0-parallel-session-setup/with_skill/outputs/response.md b/evals/parallel-worktrees/iteration-1/eval-0-parallel-session-setup/with_skill/outputs/response.md similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-0-parallel-session-setup/with_skill/outputs/response.md rename to evals/parallel-worktrees/iteration-1/eval-0-parallel-session-setup/with_skill/outputs/response.md diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-0-parallel-session-setup/with_skill/timing.json b/evals/parallel-worktrees/iteration-1/eval-0-parallel-session-setup/with_skill/timing.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-0-parallel-session-setup/with_skill/timing.json rename to evals/parallel-worktrees/iteration-1/eval-0-parallel-session-setup/with_skill/timing.json diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-0-parallel-session-setup/without_skill/grading.json b/evals/parallel-worktrees/iteration-1/eval-0-parallel-session-setup/without_skill/grading.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-0-parallel-session-setup/without_skill/grading.json rename to evals/parallel-worktrees/iteration-1/eval-0-parallel-session-setup/without_skill/grading.json diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-0-parallel-session-setup/without_skill/outputs/response.md b/evals/parallel-worktrees/iteration-1/eval-0-parallel-session-setup/without_skill/outputs/response.md similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-0-parallel-session-setup/without_skill/outputs/response.md rename to evals/parallel-worktrees/iteration-1/eval-0-parallel-session-setup/without_skill/outputs/response.md diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-0-parallel-session-setup/without_skill/timing.json b/evals/parallel-worktrees/iteration-1/eval-0-parallel-session-setup/without_skill/timing.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-0-parallel-session-setup/without_skill/timing.json rename to evals/parallel-worktrees/iteration-1/eval-0-parallel-session-setup/without_skill/timing.json diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-1-push-and-pr/eval_metadata.json b/evals/parallel-worktrees/iteration-1/eval-1-push-and-pr/eval_metadata.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-1-push-and-pr/eval_metadata.json rename to evals/parallel-worktrees/iteration-1/eval-1-push-and-pr/eval_metadata.json diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-1-push-and-pr/with_skill/grading.json b/evals/parallel-worktrees/iteration-1/eval-1-push-and-pr/with_skill/grading.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-1-push-and-pr/with_skill/grading.json rename to evals/parallel-worktrees/iteration-1/eval-1-push-and-pr/with_skill/grading.json diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-1-push-and-pr/with_skill/outputs/response.md b/evals/parallel-worktrees/iteration-1/eval-1-push-and-pr/with_skill/outputs/response.md similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-1-push-and-pr/with_skill/outputs/response.md rename to evals/parallel-worktrees/iteration-1/eval-1-push-and-pr/with_skill/outputs/response.md diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-1-push-and-pr/with_skill/timing.json b/evals/parallel-worktrees/iteration-1/eval-1-push-and-pr/with_skill/timing.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-1-push-and-pr/with_skill/timing.json rename to evals/parallel-worktrees/iteration-1/eval-1-push-and-pr/with_skill/timing.json diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-1-push-and-pr/without_skill/grading.json b/evals/parallel-worktrees/iteration-1/eval-1-push-and-pr/without_skill/grading.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-1-push-and-pr/without_skill/grading.json rename to evals/parallel-worktrees/iteration-1/eval-1-push-and-pr/without_skill/grading.json diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-1-push-and-pr/without_skill/outputs/response.md b/evals/parallel-worktrees/iteration-1/eval-1-push-and-pr/without_skill/outputs/response.md similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-1-push-and-pr/without_skill/outputs/response.md rename to evals/parallel-worktrees/iteration-1/eval-1-push-and-pr/without_skill/outputs/response.md diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-1-push-and-pr/without_skill/timing.json b/evals/parallel-worktrees/iteration-1/eval-1-push-and-pr/without_skill/timing.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-1-push-and-pr/without_skill/timing.json rename to evals/parallel-worktrees/iteration-1/eval-1-push-and-pr/without_skill/timing.json diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-2-conflict-avoidance/eval_metadata.json b/evals/parallel-worktrees/iteration-1/eval-2-conflict-avoidance/eval_metadata.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-2-conflict-avoidance/eval_metadata.json rename to evals/parallel-worktrees/iteration-1/eval-2-conflict-avoidance/eval_metadata.json diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-2-conflict-avoidance/with_skill/grading.json b/evals/parallel-worktrees/iteration-1/eval-2-conflict-avoidance/with_skill/grading.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-2-conflict-avoidance/with_skill/grading.json rename to evals/parallel-worktrees/iteration-1/eval-2-conflict-avoidance/with_skill/grading.json diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-2-conflict-avoidance/with_skill/outputs/response.md b/evals/parallel-worktrees/iteration-1/eval-2-conflict-avoidance/with_skill/outputs/response.md similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-2-conflict-avoidance/with_skill/outputs/response.md rename to evals/parallel-worktrees/iteration-1/eval-2-conflict-avoidance/with_skill/outputs/response.md diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-2-conflict-avoidance/with_skill/timing.json b/evals/parallel-worktrees/iteration-1/eval-2-conflict-avoidance/with_skill/timing.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-2-conflict-avoidance/with_skill/timing.json rename to evals/parallel-worktrees/iteration-1/eval-2-conflict-avoidance/with_skill/timing.json diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-2-conflict-avoidance/without_skill/grading.json b/evals/parallel-worktrees/iteration-1/eval-2-conflict-avoidance/without_skill/grading.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-2-conflict-avoidance/without_skill/grading.json rename to evals/parallel-worktrees/iteration-1/eval-2-conflict-avoidance/without_skill/grading.json diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-2-conflict-avoidance/without_skill/outputs/response.md b/evals/parallel-worktrees/iteration-1/eval-2-conflict-avoidance/without_skill/outputs/response.md similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-2-conflict-avoidance/without_skill/outputs/response.md rename to evals/parallel-worktrees/iteration-1/eval-2-conflict-avoidance/without_skill/outputs/response.md diff --git a/skills/parallel-worktrees-workspace/iteration-1/eval-2-conflict-avoidance/without_skill/timing.json b/evals/parallel-worktrees/iteration-1/eval-2-conflict-avoidance/without_skill/timing.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/eval-2-conflict-avoidance/without_skill/timing.json rename to evals/parallel-worktrees/iteration-1/eval-2-conflict-avoidance/without_skill/timing.json diff --git a/skills/parallel-worktrees-workspace/iteration-1/feedback.json b/evals/parallel-worktrees/iteration-1/feedback.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-1/feedback.json rename to evals/parallel-worktrees/iteration-1/feedback.json diff --git a/skills/parallel-worktrees-workspace/iteration-2/benchmark.json b/evals/parallel-worktrees/iteration-2/benchmark.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/benchmark.json rename to evals/parallel-worktrees/iteration-2/benchmark.json diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-0-parallel-session-setup/eval_metadata.json b/evals/parallel-worktrees/iteration-2/eval-0-parallel-session-setup/eval_metadata.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-0-parallel-session-setup/eval_metadata.json rename to evals/parallel-worktrees/iteration-2/eval-0-parallel-session-setup/eval_metadata.json diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-0-parallel-session-setup/with_skill/grading.json b/evals/parallel-worktrees/iteration-2/eval-0-parallel-session-setup/with_skill/grading.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-0-parallel-session-setup/with_skill/grading.json rename to evals/parallel-worktrees/iteration-2/eval-0-parallel-session-setup/with_skill/grading.json diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-0-parallel-session-setup/with_skill/outputs/response.md b/evals/parallel-worktrees/iteration-2/eval-0-parallel-session-setup/with_skill/outputs/response.md similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-0-parallel-session-setup/with_skill/outputs/response.md rename to evals/parallel-worktrees/iteration-2/eval-0-parallel-session-setup/with_skill/outputs/response.md diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-0-parallel-session-setup/with_skill/timing.json b/evals/parallel-worktrees/iteration-2/eval-0-parallel-session-setup/with_skill/timing.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-0-parallel-session-setup/with_skill/timing.json rename to evals/parallel-worktrees/iteration-2/eval-0-parallel-session-setup/with_skill/timing.json diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-0-parallel-session-setup/without_skill/grading.json b/evals/parallel-worktrees/iteration-2/eval-0-parallel-session-setup/without_skill/grading.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-0-parallel-session-setup/without_skill/grading.json rename to evals/parallel-worktrees/iteration-2/eval-0-parallel-session-setup/without_skill/grading.json diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-0-parallel-session-setup/without_skill/outputs/response.md b/evals/parallel-worktrees/iteration-2/eval-0-parallel-session-setup/without_skill/outputs/response.md similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-0-parallel-session-setup/without_skill/outputs/response.md rename to evals/parallel-worktrees/iteration-2/eval-0-parallel-session-setup/without_skill/outputs/response.md diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-0-parallel-session-setup/without_skill/timing.json b/evals/parallel-worktrees/iteration-2/eval-0-parallel-session-setup/without_skill/timing.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-0-parallel-session-setup/without_skill/timing.json rename to evals/parallel-worktrees/iteration-2/eval-0-parallel-session-setup/without_skill/timing.json diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-1-push-and-pr/eval_metadata.json b/evals/parallel-worktrees/iteration-2/eval-1-push-and-pr/eval_metadata.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-1-push-and-pr/eval_metadata.json rename to evals/parallel-worktrees/iteration-2/eval-1-push-and-pr/eval_metadata.json diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-1-push-and-pr/with_skill/grading.json b/evals/parallel-worktrees/iteration-2/eval-1-push-and-pr/with_skill/grading.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-1-push-and-pr/with_skill/grading.json rename to evals/parallel-worktrees/iteration-2/eval-1-push-and-pr/with_skill/grading.json diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-1-push-and-pr/with_skill/outputs/response.md b/evals/parallel-worktrees/iteration-2/eval-1-push-and-pr/with_skill/outputs/response.md similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-1-push-and-pr/with_skill/outputs/response.md rename to evals/parallel-worktrees/iteration-2/eval-1-push-and-pr/with_skill/outputs/response.md diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-1-push-and-pr/with_skill/timing.json b/evals/parallel-worktrees/iteration-2/eval-1-push-and-pr/with_skill/timing.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-1-push-and-pr/with_skill/timing.json rename to evals/parallel-worktrees/iteration-2/eval-1-push-and-pr/with_skill/timing.json diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-1-push-and-pr/without_skill/grading.json b/evals/parallel-worktrees/iteration-2/eval-1-push-and-pr/without_skill/grading.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-1-push-and-pr/without_skill/grading.json rename to evals/parallel-worktrees/iteration-2/eval-1-push-and-pr/without_skill/grading.json diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-1-push-and-pr/without_skill/outputs/response.md b/evals/parallel-worktrees/iteration-2/eval-1-push-and-pr/without_skill/outputs/response.md similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-1-push-and-pr/without_skill/outputs/response.md rename to evals/parallel-worktrees/iteration-2/eval-1-push-and-pr/without_skill/outputs/response.md diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-1-push-and-pr/without_skill/timing.json b/evals/parallel-worktrees/iteration-2/eval-1-push-and-pr/without_skill/timing.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-1-push-and-pr/without_skill/timing.json rename to evals/parallel-worktrees/iteration-2/eval-1-push-and-pr/without_skill/timing.json diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-2-conflict-avoidance/eval_metadata.json b/evals/parallel-worktrees/iteration-2/eval-2-conflict-avoidance/eval_metadata.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-2-conflict-avoidance/eval_metadata.json rename to evals/parallel-worktrees/iteration-2/eval-2-conflict-avoidance/eval_metadata.json diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-2-conflict-avoidance/with_skill/grading.json b/evals/parallel-worktrees/iteration-2/eval-2-conflict-avoidance/with_skill/grading.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-2-conflict-avoidance/with_skill/grading.json rename to evals/parallel-worktrees/iteration-2/eval-2-conflict-avoidance/with_skill/grading.json diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-2-conflict-avoidance/with_skill/outputs/response.md b/evals/parallel-worktrees/iteration-2/eval-2-conflict-avoidance/with_skill/outputs/response.md similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-2-conflict-avoidance/with_skill/outputs/response.md rename to evals/parallel-worktrees/iteration-2/eval-2-conflict-avoidance/with_skill/outputs/response.md diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-2-conflict-avoidance/with_skill/timing.json b/evals/parallel-worktrees/iteration-2/eval-2-conflict-avoidance/with_skill/timing.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-2-conflict-avoidance/with_skill/timing.json rename to evals/parallel-worktrees/iteration-2/eval-2-conflict-avoidance/with_skill/timing.json diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-2-conflict-avoidance/without_skill/grading.json b/evals/parallel-worktrees/iteration-2/eval-2-conflict-avoidance/without_skill/grading.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-2-conflict-avoidance/without_skill/grading.json rename to evals/parallel-worktrees/iteration-2/eval-2-conflict-avoidance/without_skill/grading.json diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-2-conflict-avoidance/without_skill/outputs/response.md b/evals/parallel-worktrees/iteration-2/eval-2-conflict-avoidance/without_skill/outputs/response.md similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-2-conflict-avoidance/without_skill/outputs/response.md rename to evals/parallel-worktrees/iteration-2/eval-2-conflict-avoidance/without_skill/outputs/response.md diff --git a/skills/parallel-worktrees-workspace/iteration-2/eval-2-conflict-avoidance/without_skill/timing.json b/evals/parallel-worktrees/iteration-2/eval-2-conflict-avoidance/without_skill/timing.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/eval-2-conflict-avoidance/without_skill/timing.json rename to evals/parallel-worktrees/iteration-2/eval-2-conflict-avoidance/without_skill/timing.json diff --git a/skills/parallel-worktrees-workspace/iteration-2/feedback.json b/evals/parallel-worktrees/iteration-2/feedback.json similarity index 100% rename from skills/parallel-worktrees-workspace/iteration-2/feedback.json rename to evals/parallel-worktrees/iteration-2/feedback.json diff --git a/skills/github-integration/SKILL.md b/skills/github-integration/SKILL.md new file mode 100644 index 0000000..a585f15 --- /dev/null +++ b/skills/github-integration/SKILL.md @@ -0,0 +1,200 @@ +--- +name: github-integration +description: > + Enable the GitHub CLI (`gh`) in Claude Code cloud sessions and GitHub + Copilot coding agent environments. Use this skill when: (1) setting up a + project so cloud AI agents can use `gh` for PRs, issues, and releases, + (2) configuring setup scripts or SessionStart hooks for `gh` installation, + (3) adding `copilot-setup-steps.yml` for GitHub Copilot agents, + (4) troubleshooting `gh` auth failures in cloud sessions, or + (5) configuring `GH_TOKEN` for headless environments. Triggers on: + "enable gh", "github integration", "Claude Code cloud setup", + "copilot setup steps", "gh auth in cloud", "gh not working in cloud", + "setup script", or any request involving GitHub CLI access from + cloud-based AI coding agents. +metadata: + author: Codervisor + version: 0.2.0 + homepage: https://github.com/codervisor/forge +--- + +# GitHub Integration + +Enable `gh` CLI access in Claude Code cloud and GitHub Copilot coding agent +environments so agents can create PRs, manage issues, and interact with +GitHub APIs. + +## When to Use This Skill + +Activate when: +- User wants cloud AI agents to use `gh` (PRs, issues, releases, API calls) +- User needs to install `gh` in Claude Code cloud sessions +- User wants to add `copilot-setup-steps.yml` for GitHub Copilot agents +- `gh` commands fail with auth or "not found" errors in a cloud session +- User wants to enable GitHub integration for any cloud-based AI coding agent + +## Decision Tree + +``` +Which cloud environment? + +Claude Code cloud (claude.ai/code)? + → gh is NOT pre-installed in the default image + → Install via setup script: apt update && apt install -y gh + → Set GH_TOKEN as environment variable in environment settings + → For repo-portable setup, use SessionStart hook instead + → Use -R owner/repo flag with gh due to sandbox proxy + +GitHub Copilot coding agent? + → Add .github/copilot-setup-steps.yml to the repo + → gh IS pre-installed; just configure GH_TOKEN + → Commit and push — agent sessions pick it up automatically + +gh commands failing? + → "command not found" → gh not installed; add to setup script + → HTTP 401 → GH_TOKEN not set; add to environment variables + → HTTP 403 → Token lacks required scope; check permissions + → "could not determine repo" → Use -R owner/repo flag + → See references/cloud-auth.md for more + +Need gh in local dev too? + → Run: gh auth login (interactive, browser-based) + → Or set GH_TOKEN env var for headless/CI use +``` + +## Two Environments, Two Approaches + +### Claude Code Cloud (claude.ai/code) + +Claude Code cloud runs sessions in Anthropic-managed VMs. The `gh` CLI +is **not pre-installed**. You need two things: + +1. **Setup script** — installs `gh` when the session starts +2. **`GH_TOKEN` env var** — authenticates `gh` with your GitHub PAT + +#### Quick Start: Setup Script + +In the Claude Code web UI: Environment Settings → Setup script: + +```bash +#!/bin/bash +apt update && apt install -y gh +``` + +Then add `GH_TOKEN` as an environment variable with your GitHub Personal +Access Token (needs `repo` scope). + +#### Alternative: SessionStart Hook (repo-portable) + +Add to `.claude/settings.json` in your repo: + +```json +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "type": "command", + "command": "if [ \"$CLAUDE_CODE_REMOTE\" = \"true\" ]; then apt update && apt install -y gh; fi", + "timeout": 120 + } + ] + } + ] + } +} +``` + +The `CLAUDE_CODE_REMOTE` check ensures it only runs in cloud sessions. + +#### Important: The `-R` Flag + +Due to the sandbox proxy, `gh` may not auto-detect the repo. Use the +`-R owner/repo` flag: + +```bash +gh pr create -R codervisor/myrepo --title "..." --body "..." +gh issue list -R codervisor/myrepo +``` + +### GitHub Copilot Coding Agent + +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`: + +```yaml +name: "Copilot Setup Steps" + +on: repository_dispatch + +jobs: + copilot-setup-steps: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Authenticate gh CLI + run: gh auth status + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +See `templates/copilot-setup-steps.yml` for a full template with +dependency installation. + +## Setup Scripts vs SessionStart Hooks vs copilot-setup-steps + +| | Setup scripts | SessionStart hooks | copilot-setup-steps.yml | +|------------------|--------------------------|---------------------------------|----------------------------------| +| **Platform** | Claude Code cloud only | Claude Code (local + cloud) | GitHub Copilot agents only | +| **Configured in**| Environment settings UI | `.claude/settings.json` in repo | `.github/copilot-setup-steps.yml`| +| **Runs** | Before Claude launches | After Claude launches | Before Copilot agent launches | +| **Runs on resume**| No (new sessions only) | Yes (every session) | Yes | +| **Network** | Needs registry access | Needs registry access | Full GitHub Actions network | + +## Common gh Commands for Agents + +```bash +# PRs (use -R in Claude Code cloud) +gh pr create -R owner/repo --title "..." --body "..." +gh pr list -R owner/repo +gh pr view -R owner/repo +gh pr merge -R owner/repo --squash --delete-branch + +# Issues +gh issue list -R owner/repo +gh issue view 42 -R owner/repo +gh issue create -R owner/repo --title "..." --body "..." + +# API (for anything not covered by subcommands) +gh api repos/owner/repo/actions/runs +``` + +## Pitfalls + +| Symptom | Cause | Fix | +|---------|-------|-----| +| `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 | +| `could not determine repo` | Sandbox proxy hides git remote | Use `-R owner/repo` flag | +| `gh pr create` fails | No upstream branch | Push with `git push -u origin ` first | +| Setup script fails | No network access | Set network to "Limited" (default) or "Full" | + +## References + +- `references/cloud-auth.md` — Token auth, scopes, proxy details, troubleshooting +- `references/copilot-setup-steps.md` — Full guide to customizing the Copilot setup workflow + +## Setup & Activation + +```bash +npx skills add codervisor/forge@github-integration -g -y +``` + +Auto-activates when: user mentions "gh in cloud", "github integration", +"setup script", "copilot setup steps", or `gh` auth failures in cloud +environments. diff --git a/skills/github-integration/references/cloud-auth.md b/skills/github-integration/references/cloud-auth.md new file mode 100644 index 0000000..69eb7b5 --- /dev/null +++ b/skills/github-integration/references/cloud-auth.md @@ -0,0 +1,282 @@ +# Cloud Authentication Reference + +How `gh` CLI authentication works in Claude Code cloud and GitHub Copilot +coding agent environments. + +## Table of Contents +1. [Claude Code cloud architecture](#claude-code-cloud-architecture) +2. [GitHub Copilot agent architecture](#github-copilot-agent-architecture) +3. [Token types](#token-types) +4. [Configuring gh](#configuring-gh) +5. [The sandbox proxy](#the-sandbox-proxy) +6. [Network access](#network-access) +7. [Troubleshooting](#troubleshooting) + +--- + +## Claude Code Cloud Architecture + +Claude Code cloud runs sessions in **Anthropic-managed VMs** (Ubuntu 24.04). +Key facts: + +- Each session gets an isolated VM with your repo cloned +- `gh` is **not pre-installed** — must be installed via setup script +- Git auth is handled by a **dedicated proxy** (not a token in the sandbox) +- The git client uses a scoped credential that the proxy translates to your + actual GitHub auth token +- `gh` CLI needs its own auth via the `GH_TOKEN` environment variable +- The proxy restricts `git push` to the current working branch only + +### Session Lifecycle + +1. VM spins up, repo is cloned via the GitHub proxy +2. Setup script runs (if configured) — install `gh` here +3. SessionStart hooks run (if configured in `.claude/settings.json`) +4. Claude Code launches and begins working +5. On completion, changes are pushed to a branch via the proxy + +### What's Pre-installed + +The universal image includes Python, Node.js, Ruby, PHP, Java, Go, Rust, +C++, PostgreSQL 16, Redis 7.0, and common package managers. Run +`check-tools` to see the full list. + +**Not pre-installed:** `gh` CLI. Install it in your setup script. + +--- + +## GitHub Copilot Agent Architecture + +GitHub Copilot coding agents (including Claude as a Copilot agent) run in +**GitHub-managed containers** using GitHub Actions infrastructure. + +- `gh` **is pre-installed** and available immediately +- `GITHUB_TOKEN` is provided automatically via `secrets.GITHUB_TOKEN` +- Configure the environment with `.github/copilot-setup-steps.yml` +- The job **must** be named `copilot-setup-steps` + +--- + +## Token Types + +### GitHub Personal Access Token (PAT) — Claude Code Cloud + +For Claude Code cloud, you provide your own PAT: + +| Setting | Value | +|---------|-------| +| Where to create | GitHub → Settings → Developer settings → Personal access tokens | +| 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` | +| Where to set | Claude Code → Environment Settings → Environment Variables | +| Variable name | `GH_TOKEN` | + +**Security:** The PAT is stored in Anthropic's environment settings and +injected into the VM at session start. It is not committed to the repo. + +### GITHUB_TOKEN — Copilot Agent + +For Copilot coding agents, `GITHUB_TOKEN` is provided automatically: + +| Property | Value | +|----------|-------| +| Lifetime | Scoped to the workflow run | +| Scope | Repository that triggered the session | +| Default permissions | `contents:read`, `metadata:read` | +| Configurable | Yes, via `permissions:` block in the workflow | + +--- + +## Configuring gh + +### Claude Code Cloud + +**Option 1: `GH_TOKEN` environment variable (recommended)** + +Set `GH_TOKEN` in the environment settings UI. `gh` detects it automatically. + +```bash +# Verify it works +gh auth status +``` + +**Option 2: `gh auth login --with-token`** + +If you need explicit login (rare): + +```bash +echo "$GH_TOKEN" | gh auth login --with-token +``` + +### Copilot Agent + +Pass the token in the workflow step: + +```yaml +- name: Authenticate gh CLI + run: gh auth status + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +--- + +## The Sandbox Proxy + +Claude Code cloud routes all GitHub traffic through a **dedicated proxy**. + +### How it works + +- The git client inside the sandbox uses a scoped credential +- The proxy verifies this credential and translates it to your actual + GitHub token +- `git push` is restricted to the current working branch +- `git clone`, `git fetch`, and `git pull` work transparently + +### Impact on gh + +The proxy handles git operations, but `gh` makes its own HTTP requests to +the GitHub API. This means: + +1. `gh` needs its own token (`GH_TOKEN`) — it doesn't share the git proxy + credential +2. `gh` may not auto-detect the repo from git remotes due to the proxy + configuration — use the `-R owner/repo` flag + +```bash +# Instead of: +gh pr list + +# Use: +gh pr list -R codervisor/myrepo +``` + +--- + +## Network Access + +### Claude Code Cloud + +Three levels: + +| Level | Description | +|-------|-------------| +| **Limited** (default) | Allows common registries (npm, PyPI, crates.io, etc.) and GitHub domains | +| **Full** | Unrestricted outbound access | +| **None** | No internet (API communication to Anthropic still allowed) | + +Key allowed domains for gh (in Limited mode): +- `github.com`, `api.github.com` +- `raw.githubusercontent.com`, `objects.githubusercontent.com` +- `npm.pkg.github.com`, `ghcr.io` + +**Note:** Setup scripts that install packages (like `apt install gh`) need +network access. The default "Limited" mode allows this since Ubuntu package +repos (`archive.ubuntu.com`, `security.ubuntu.com`) are in the allowlist. + +### Copilot Agent + +Full GitHub Actions network — no restrictions beyond standard Actions limits. + +--- + +## Troubleshooting + +### gh: command not found + +**Environment:** Claude Code cloud only. + +**Cause:** `gh` is not pre-installed in the default image. + +**Fix:** Add to your setup script: +```bash +apt update && apt install -y gh +``` + +Or use a SessionStart hook: +```json +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "type": "command", + "command": "if [ \"$CLAUDE_CODE_REMOTE\" = \"true\" ]; then apt update && apt install -y gh; fi", + "timeout": 120 + } + ] + } + ] + } +} +``` + +### gh auth status shows "not logged in" + +**Cause:** `GH_TOKEN` not set in the environment. + +**Fix (Claude Code cloud):** Add `GH_TOKEN=ghp_...` to Environment Settings → +Environment Variables. + +**Fix (Copilot agent):** Ensure the workflow step has: +```yaml +env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +### "could not determine base repo" / repo not detected + +**Cause:** Sandbox proxy obscures the git remote from `gh`. + +**Fix:** Always pass `-R owner/repo`: +```bash +gh pr create -R codervisor/myrepo --title "..." +``` + +### HTTP 401 Unauthorized + +**Cause:** Token expired, revoked, or never set. + +**Fix:** +1. Check `gh auth status` +2. Verify `GH_TOKEN` is set: `echo $GH_TOKEN | head -c 10` +3. If expired, regenerate the PAT and update environment settings + +### HTTP 403 Forbidden + +**Cause:** Token lacks required permission scope. + +**Fix:** +1. Check error message for the required scope +2. Regenerate PAT with the needed scopes (at minimum: `repo`) +3. For Copilot agents, add permissions to the workflow: + ```yaml + permissions: + contents: write + pull-requests: write + ``` + +### gh works but git push fails + +**Cause:** In Claude Code cloud, git push is restricted to the current +working branch by the proxy. + +**Fix:** Ensure you're pushing to the branch Claude Code checked out. +You cannot push to other branches. + +### Setup script fails to install gh + +**Cause:** Network access is disabled or too restrictive. + +**Fix:** Set network access to "Limited" (default) or "Full" in +environment settings. The default allowlist includes Ubuntu package repos. + +### Rate limiting + +**Cause:** Too many API calls in a short period. + +**Fix:** +1. Check limits: `gh api rate_limit` +2. Use GraphQL for batch queries: `gh api graphql` +3. Add delays between bulk operations diff --git a/skills/github-integration/references/copilot-setup-steps.md b/skills/github-integration/references/copilot-setup-steps.md new file mode 100644 index 0000000..62e48df --- /dev/null +++ b/skills/github-integration/references/copilot-setup-steps.md @@ -0,0 +1,234 @@ +# Copilot Setup Steps Reference + +Complete guide to `.github/copilot-setup-steps.yml` — the workflow that +configures cloud coding sessions for Claude Code and GitHub Copilot agents. + +## Table of Contents +1. [What it is](#what-it-is) +2. [File location](#file-location) +3. [Minimal example](#minimal-example) +4. [Full example](#full-example) +5. [Adding project dependencies](#adding-project-dependencies) +6. [Caching](#caching) +7. [Multiple language stacks](#multiple-language-stacks) +8. [Testing the workflow](#testing-the-workflow) + +--- + +## What It Is + +`copilot-setup-steps.yml` is a GitHub Actions workflow that runs when a +cloud coding session starts. It prepares the environment so the AI agent +can: + +- Authenticate with `gh` CLI +- Install project dependencies +- Build the project +- Run linters, formatters, and tests + +The workflow uses the `repository_dispatch` event and runs in the same +container that the agent session uses. + +--- + +## 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. + +--- + +## Minimal Example + +Just gh authentication — no project-specific setup: + +```yaml +name: "Copilot Setup Steps" + +on: repository_dispatch + +jobs: + copilot-setup-steps: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Authenticate gh CLI + run: gh auth status + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +--- + +## Full Example + +Node.js project with pnpm, linting, and build: + +```yaml +name: "Copilot Setup Steps" + +on: repository_dispatch + +jobs: + copilot-setup-steps: + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + issues: write + steps: + - uses: actions/checkout@v4 + + - name: Authenticate gh CLI + run: gh auth status + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - uses: pnpm/action-setup@v4 + + - uses: actions/setup-node@v4 + with: + node-version: '22' + cache: 'pnpm' + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Build + run: pnpm build + + - name: Verify linter works + run: pnpm lint --quiet +``` + +--- + +## Adding Project Dependencies + +### Node.js (pnpm) + +```yaml +- uses: pnpm/action-setup@v4 +- uses: actions/setup-node@v4 + with: + node-version: '22' + cache: 'pnpm' +- run: pnpm install --frozen-lockfile +``` + +### Node.js (npm) + +```yaml +- uses: actions/setup-node@v4 + with: + node-version: '22' + cache: 'npm' +- run: npm ci +``` + +### Rust + +```yaml +- uses: dtolnay/rust-toolchain@stable +- uses: Swatinem/rust-cache@v2 +- run: cargo build +``` + +### Python + +```yaml +- uses: actions/setup-python@v5 + with: + python-version: '3.12' + cache: 'pip' +- run: pip install -r requirements.txt +``` + +### Go + +```yaml +- uses: actions/setup-go@v5 + with: + go-version: '1.22' +- run: go mod download +``` + +--- + +## Caching + +GitHub Actions caching works in copilot-setup-steps just like in CI. +Use the `cache` parameter in setup actions (e.g., `actions/setup-node`) +or `actions/cache` directly: + +```yaml +- uses: actions/cache@v4 + with: + path: ~/.cache/some-tool + key: ${{ runner.os }}-some-tool-${{ hashFiles('**/lockfile') }} +``` + +Caching significantly speeds up repeated cloud sessions on the same repo. + +--- + +## Multiple Language Stacks + +For hybrid projects (e.g., Rust + Node.js), combine steps: + +```yaml +steps: + - uses: actions/checkout@v4 + + - name: Authenticate gh CLI + run: gh auth status + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + # Node.js + - uses: pnpm/action-setup@v4 + - uses: actions/setup-node@v4 + with: + node-version: '22' + cache: 'pnpm' + - run: pnpm install --frozen-lockfile + + # Rust + - uses: dtolnay/rust-toolchain@stable + - uses: Swatinem/rust-cache@v2 + + - run: pnpm build +``` + +--- + +## Testing the Workflow + +You can't trigger `repository_dispatch` directly from the GitHub UI. +To test: + +### 1. Trigger manually via gh CLI + +```bash +gh api repos/{owner}/{repo}/dispatches \ + --method POST \ + --field event_type=copilot-setup +``` + +### 2. Check the workflow ran + +```bash +gh run list --workflow=copilot-setup-steps.yml +gh run view --log +``` + +### 3. Validate locally + +Run the same commands from the workflow steps in your local terminal to +verify they work before committing. diff --git a/skills/github-integration/templates/copilot-setup-steps.yml b/skills/github-integration/templates/copilot-setup-steps.yml new file mode 100644 index 0000000..e9292c7 --- /dev/null +++ b/skills/github-integration/templates/copilot-setup-steps.yml @@ -0,0 +1,53 @@ +# GitHub Integration — Copilot Setup Steps Template +# +# 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. +# +# CUSTOMIZE: Update the dependency installation and build steps +# to match your project's stack. The gh auth step should stay first. + +name: "Copilot Setup Steps" + +on: repository_dispatch + +jobs: + copilot-setup-steps: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + # --- gh CLI authentication --- + # The GITHUB_TOKEN is provided automatically by the cloud session. + # This step verifies gh can use it. + - name: Authenticate gh CLI + run: gh auth status + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + # --- Node.js projects (uncomment if needed) --- + # - uses: pnpm/action-setup@v4 + # - uses: actions/setup-node@v4 + # with: + # node-version: '22' + # cache: 'pnpm' + # - name: Install dependencies + # run: pnpm install --frozen-lockfile + + # --- Rust projects (uncomment if needed) --- + # - uses: dtolnay/rust-toolchain@stable + # - uses: Swatinem/rust-cache@v2 + + # --- Python projects (uncomment if needed) --- + # - uses: actions/setup-python@v5 + # with: + # python-version: '3.12' + # - run: pip install -r requirements.txt + + # --- Build (uncomment and customize) --- + # - name: Build project + # run: npm run build + + # --- Install CLI tools globally (uncomment and customize) --- + # - run: npm install -g ./packages/cli diff --git a/skills/rust-node-bootstrap/templates/bootstrap/.gitkeep b/skills/rust-node-bootstrap/templates/bootstrap/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/rust-node-ci/templates/workflows/.gitkeep b/skills/rust-node-ci/templates/workflows/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/rust-npm-publish/templates/scripts/.gitkeep b/skills/rust-npm-publish/templates/scripts/.gitkeep new file mode 100644 index 0000000..e69de29