Use Copilot

Use Copilot

Core rule

Copilot is a bounded implementation worker that shines for GitHub-integrated work. Claude owns the plan, the prompt file, the audit synthesis, the tests, the commits, and the final answer to the user.

Copilot's killer features over other CLIs:

1. GitHub MCP built-in — --add-github-mcp-toolset all exposes issues, PRs, releases, code search to the agent. Saves you wiring an MCP server yourself when the task involves "look at PR #123 and..."
2. Copilot subscription — if you already pay for Copilot Pro/Business, the CLI usage is included; no separate API token to manage.
3. Reasoning effort knob — --effort xhigh for deep audits, --effort low for cheap fan-out.

When to use vs when to skip

Don't use copilot for:

• Tasks that don't touch GitHub — codex / gemini / cursor are typically faster setups
• Workflows that need raw API access to non-GitHub services (no inherent advantage over codex)
• Live debugging needing mid-flight Claude context

Available models (Copilot picker — verified 2026-07-01)

Use --model <id> to switch; Auto is the default and gets a 10% quota discount (leave --model off to use it). The Quota column is Copilot's premium-request multiplier (higher = more of your monthly quota burned per request) — it's the load-bearing cost signal on Copilot, so pick the cheapest model that clears the task. Confirm exact --model slugs with copilot --model <id> -p ping (display names below; slug format is lowercased-dotted, e.g. claude-opus-4.8, gemini-3.1-pro).

Dropped from the 2026-07-01 picker (were listed 2026-05-03 — probe before relying, likely retired): gpt-5.2, gpt-5.2-codex, gpt-4.1, claude-sonnet-4. Copilot keeps some backward-compat depth (claude-sonnet-4.5, gpt-5.4-mini) but the deep-legacy coverage narrowed. New arrivals since 2026-05: Claude Opus 4.8 (27x), Gemini 3.1 Pro (6x) / 3.5 Flash (14x), MAI-Code-1-Flash (0.33x). Note Copilot has Opus 4.8 but not Sonnet 5 (top Sonnet is 4.6) — same Anthropic ceiling as droid on the Sonnet line, but unlike droid it does carry Opus 4.8.

Picking a model — quick decision

Reading PRs/issues/code-search via GitHub MCP?
  → any of the above — pair with --add-github-mcp-toolset {issues|pulls|code-search|all}

Frontier code review on diff touching money/auth/migration?
  → --model claude-opus-4.8 (newest; or claude-opus-4.7 — same 27x cost)
  OR --model gpt-5.5 (Terminal-Bench SOTA, 57x — priciest seat)
  Run BOTH on copilot for highest-stakes diffs.

Independent second opinion on codex's gpt-5.5 verdict?
  → --model gpt-5.5 on copilot — same model, different harness = independent signal

Bulk fan-out across N tasks? (cheapest = 0.33x)
  → --model gpt-5-mini OR --model claude-haiku-4.5 OR --model mai-code-1-flash
  ⚠ NOT gpt-5.4-mini — it is 6x now, no longer a cheap fan-out seat.

Backward-compat testing — "did this old model handle it differently?"
  → copilot still exposes some prior-gen IDs (claude-sonnet-4.5, gpt-5.4-mini), but the
    2026-07-01 picker DROPPED gpt-5.2, gpt-5.2-codex, gpt-4.1, claude-sonnet-4 — probe with
    `copilot --model <id> -p ping` before relying on any legacy ID.

Verify availability before long runs: probe with copilot --model <id> -p "ping". Wrong IDs return clear errors immediately.

Workflow

digraph copilot_workflow {
  "Identify copilot-fittable task" -> "Verify copilot CLI auth";
  "Verify copilot CLI auth" -> "Write task spec file";
  "Write task spec file" -> "Pick effort level + GitHub MCP scope";
  "Pick effort level + GitHub MCP scope" -> "Launch copilot -p";
  "Launch copilot -p" -> "Wait for exit";
  "Wait for exit" -> "Audit diff via subagent";
  "Audit diff via subagent" -> "Run tests";
  "Run tests" -> "Claude commits";
}

1. Verify copilot is installed and authed

which copilot && copilot --version
echo "noop test" | copilot -p --allow-all "echo hello" --log-dir /tmp 2>&1 | tail -5

If which copilot returns empty, copilot was not installed. Install the official CLI package at the exact version verified from npm registry metadata on 2026-07-14: npm install -g @github/copilot@1.0.70. The user must run copilot login themselves.

2. Write the task spec file

Save at <repo>/.claude/copilot_task_<short-name>.md. Same shape as use-codex / use-cursor / use-droid spec templates.

If task is a driver script for a long-running remote job: cite your own job-driver conventions if you keep them documented, and require copilot to load + apply whatever environment-setup prerequisites (dependency pins, version upgrades) the target environment needs before the main work starts, so the job doesn't crash partway through.

For GitHub-touching work add an extra section:

## GitHub context (read-only via MCP)
- Read issue #<N> for the bug report
- Read PR #<M> for the prior fix attempt
- Cross-reference branch `<branch>` with main: `gh pr view <M>`
- Inspect Action run <run_id> if the bug surfaced in CI

## GitHub actions allowed
- ❌ Do NOT comment on PRs / issues
- ❌ Do NOT close / merge / approve
- ❌ Do NOT push branches
- ✅ Read-only API calls only

3. Launch copilot

Read-only audit pass:

nohup copilot \
  --effort xhigh \
  --add-dir <workspace>/<repo> \
  -p "Read .claude/copilot_task_<name>.md and execute its instructions. Read-only — no file edits, no GitHub writes." \
  --log-dir /tmp/copilot_<name>_logs \
  > /tmp/copilot_<name>.log 2>&1 &
echo $! > /tmp/copilot_<name>.pid

Implementation pass with GitHub MCP enabled:

nohup copilot \
  --effort high \
  --allow-all-tools \
  --add-dir <workspace>/<repo> \
  --add-github-mcp-toolset all \
  -p "Read .claude/copilot_task_<name>.md and execute every TODO. Edit files in-place. Do NOT git commit, git add, or git push. Print final summary line and exit." \
  --log-dir /tmp/copilot_<name>_logs \
  > /tmp/copilot_<name>.log 2>&1 &

Permission flags — pick the minimum that gets the work done:

Always pair --allow-all-paths (or --allow-all) with --add-dir <repo> so paths outside the repo are still gated.

4. Wait for exit, then layered audit: subagent first, you second

while kill -0 $(cat /tmp/copilot_<name>.pid) 2>/dev/null; do sleep 30; done
echo "exited"
tail -60 /tmp/copilot_<name>.log
ls -la /tmp/copilot_<name>_logs/   # copilot writes per-tool logs here
git diff --stat

Same layered review pattern as the other CLIs:

1. Subagent audits copilot's diff first — dispatch a feature-dev:code-reviewer Agent subagent with spec + diff.
2. You audit the subagent's report + flagged hunks only — don't re-read whole diff.
3. If clean — git add explicit files, commit, push.
4. If subagent flags issues — rewrite spec to be more explicit, relaunch copilot.

5. Tests + commit

Run only the tests touching changed files. If clean: git add explicit files, commit with a message that credits copilot (worker: copilot --effort high), push.

Prompt shape — required fields

Same as the other use-* skills.

Guardrails

• Never paste raw markdown into the -p argument for non-trivial prompts. Reference a spec file path: -p "Read <path> and execute". Long inline prompts hit shell-quoting bugs and get truncated.
• No backticks in the -p string. Reference the spec by path.
• --add-dir is the path-allowlist gate. If you forget it but pass --allow-all-paths, copilot can write anywhere on the filesystem. Always pair them.
• GitHub MCP scope: --add-github-mcp-toolset all is convenient but exposes write tools too. For audit-only passes, omit it or pass an explicit subset like --add-github-mcp-toolset issues --add-github-mcp-toolset pulls.
• Process pollution check: ps -ef | grep -E "copilot" | grep -v grep
• Don't trust copilot's success report alone. Audit diff + run tests yourself.
• Log dir: always pass --log-dir <path> so per-tool traces are recoverable. Default location is platform-dependent and gets noisy.

When to escalate / abort

• Copilot exits non-zero or prints a BLOCKER → tail log, diagnose, possibly rewrite spec + relaunch
• Copilot edits files outside the "Edits required" scope → revert via git checkout -- <file>, narrow spec
• Copilot commits despite no-commit constraint → git reset --soft HEAD~1 to keep work, audit, re-commit cleanly
• Copilot stalls past expected wall → kill $(cat /tmp/copilot_*.pid), inspect log, decide whether to retry

Routing — when copilot beats codex / gemini / cursor / droid

Cross-references

• Sibling skills: use-codex, use-gemini, use-cursor, use-droid
• If you run a multi-seat review orchestrator, it can combine all of the above into a single multi-stage deliberation.
• Evidence-backed model picker: keep your own model-task benchmark notes if you maintain them, and cite the doc here.