use-copilot

name	use-copilot
description	Use when delegating bounded coding, audit, or review work to GitHub Copilot CLI. Copilot's edge is GitHub-native MCP integration (issues, PRs, code search) on a GitHub Copilot subscription with no separate billing. Sibling skill of use-codex / use-gemini / use-cursor / use-droid.

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

Use copilot	Use Claude Agent / other CLI
Tasks that require reading GitHub issues / PRs / code-search results	Local-only tasks (codex/cursor are simpler)
GitHub Actions debugging using actual run logs	Pure-Python audit (use codex)
Cross-repo work where the agent must navigate org repos	Single-repo bounded edits (use cursor)
When the user already pays for Copilot and wants to amortize the sub	When other CLIs already match — don't add a 5th workflow
Audit pass with --effort xhigh for second opinion	Real-time iteration (Edit tool is faster)

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).

Model ID	Family	Quota	Best for	Headline benchmark	Don't use for
gpt-5.5	OpenAI	57x	Frontier review (auth/billing/migrations), terminal/agentic work	Terminal-Bench 2.0 82.7% (SOTA), GDPval 84.9%	Routine work — priciest seat by far
gpt-5.4	OpenAI	6x	Default everyday coding, multi-file edits	SWE-Bench Pro 57.7%, OSWorld 75.0%	Beyond 272K context (price cliff)
gpt-5.3-codex	OpenAI	6x	Long-horizon agentic loops (hours+), cost-per-patch matters	Terminal-Bench 77.3%, SWE-Lancer IC 81.4%	Now eclipsed by 5.5 on Terminal-Bench
gpt-5.4-mini	OpenAI	6x	OSWorld/screenshot work	OSWorld 72.1%	No longer cheap (6x now) + long-context retrieval (MRCR 47.7% @64-128K). For bulk fan-out use the 0.33x models instead
gpt-5-mini	OpenAI	0.33x	Cheap default + bulk subagent fan-out	—	Frontier reasoning
claude-opus-4.8	Anthropic	27x	NEWEST Anthropic — multi-file production review, frontier blast-radius decisions	Opus 4.8 flagship	Terminal-heavy work — gpt-5.5 wins
claude-opus-4.7	Anthropic	27x	Prior-gen Opus; multi-file review	SWE-Bench Pro 64.3% (beat GPT-5.5's 58.6%)	Prefer 4.8 — same 27x cost
claude-sonnet-4.6	Anthropic	9x	Mid-tier; ~ what Agent tool model: "sonnet" invokes. Top Sonnet on Copilot — NO Sonnet 5 here	GDPval-AA 57% (beat gemini-3.1-pro's 40%)	Multi-file refactors where Opus fits
claude-sonnet-4.5	Anthropic	6x	Backward-compat against pre-4.6 Sonnet behavior	—	New work — pick 4.6
claude-haiku-4.5	Anthropic	0.33x	Cheap: TTFT-critical interactive paths, parallel fan-out	TTFT leader; GPQA 73.0%	Frontier reasoning
gemini-3.1-pro	Google	6x	Distributed-system reasoning, cross-doc consistency (Preview)	—	—
gemini-3.5-flash	Google	14x	Google-family fast reasoning	—	Cost-sensitive fan-out — 14x is pricey for a "flash" tier
mai-code-1-flash	Microsoft	0.33x	Cheap MS-native fan-out (Microsoft MAI)	—	Frontier / high-stakes work

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:

Flag	What it does
(default)	Read-only mode; copilot prompts on every edit
--allow-all-tools	Tool calls run without confirmation. Required for -p non-interactive mode.
--allow-all-paths	File-write paths not gated. Use only with --add-dir <repo> to bound the worktree.
--allow-all-urls	URL access ungated. Avoid unless the task requires fetching arbitrary URLs.
--allow-all	All three above. Same blast-radius as --skip-permissions-unsafe on droid. Reserve for specs you wrote and trust.

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

Situation	Pick
Read PR/issue context as part of the task	copilot (built-in GitHub MCP) — others need MCP setup
Use Copilot subscription you already pay for	copilot (no per-task billing)
Cross-org repo navigation via code search	copilot (GitHub MCP code-search)
Frontier peer review on diff that touches money/auth/migration	codex (gpt-5.5) — cleaner single-model SOTA review
Distributed-system reasoning / cross-doc consistency	gemini (3.1-pro plan-mode, dead post-2026-06-18 -> use agy/droid) — different blind spots
Multi-file content write ≥3 files	cursor (unlimited tokens, auto-mode)
Multi-agent mission worker+validator	droid (--mission) — only CLI with this primitive
Cross-provider second opinion in one tool	droid (-m switching)

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.