CowboyLogic/ai-dev / skills/copilot-worker
copilot-worker
FlaggedDelegate work to GitHub Copilot instead of doing it yourself, to save Claude tokens. Use this BEFORE reading three or more files (roughly 500 lines or more) to answer a question about a codebase ("look into", "find out how", "where is", "why does", "explain how X works", "does the code do Y", "give me an overview", "summarize"), before any code review of a diff or files, and before any implementation task that touches more than a file or two. Also use when the user says "use Copilot", "delegate", "hand off", or "worker". You plan the task and verify the result; Copilot does the bulk work.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 5.3 KB |
| SKILL.md | skill md | 12.2 KB |
| references/upgrading.md | markdown | 4.3 KB |
| scripts/copilot_worker.py | script | 30.0 KB |
| scripts/pins.json | config | 46 B |
| scripts/test_copilot_worker.py | script | 41.4 KB |
| scripts/test_sdk_contract.py | script | 7.0 KB |
| scripts/test_worker_engine.py | script | 36.5 KB |
| scripts/worker_engine.py | script | 42.7 KB |
README.md
View on GitHub# Copilot Worker
A skill that lets Claude Code run GitHub Copilot as a worker. Claude Code plans the
work, hands a bounded task to Copilot, and verifies the result. The bulk work is billed
to the Copilot subscription instead of Claude tokens.
## What it does
- **Research** and **review** run read-only in the current checkout.
- **Implementation** runs in a throwaway Git worktree on its own branch, which keeps the
worker's edits off the branch you are on.
- Each run is a separate process that Claude Code starts in the background. There is no
server to install and no time limit imposed by the client.
- Each run leaves a directory with the task, the worker's final message, usage, a log of
every tool call it asked for, and a `result.json`.
- It drives Copilot through the official GitHub Copilot SDK, which pins its own Copilot
runtime. Updates to the `copilot` command-line tool cannot break it.
- The script decides every permission request itself: workers can only read and write
inside their workspace, and a deny list rejects `git push`, `gh`, and similar commands
in their common forms. Neither your Copilot hooks nor the repository's run inside it.
## Requirements
- [`uv`](https://docs.astral.sh/uv/). It installs Python 3.11 or later and the pinned
`github-copilot-sdk` from the script's header on first run.
- A GitHub Copilot login on the machine. Signing in once with the Copilot CLI
(`copilot login`) is enough; the worker reuses that login.
- Git
- macOS, Linux, or Windows (x64 or ARM64). Inside WSL it runs as it does on Linux.
On Windows the worker runs inside a job object, so ending a run ends every process it
started. An `implement` worker's shell is PowerShell (`pwsh` when it is installed,
otherwise Windows PowerShell), and the deny list reads PowerShell and `cmd.exe` syntax
as well as POSIX shell syntax.
The first run downloads the Copilot runtime the SDK pins, into the SDK's cache.
The SDK, the runtime it carries, and every package it needs are pinned to exact
versions (`scripts/pins.json` and the header of `scripts/copilot_worker.py`). The current
SDK/runtime pair is **1.0.28 / 1.0.105**. The worker
refuses to start when the installed versions differ, and `check` reports it. Upgrading is a
deliberate change; [references/upgrading.md](references/upgrading.md) has the procedure.
## Install
```bash
npx skills add CowboyLogic/ai-dev --skill copilot-worker --agent claude-code -g
```
## Check the setup
From inside a Git repository:
```bash
uv run ~/.claude/skills/copilot-worker/scripts/copilot_worker.py check --live
```
`check` confirms the SDK, its runtime version, and the repository. `--live` also checks that the model catalog offers each profile's model and effort, then sends one small prompt
to each of the four profiles, which uses Copilot credits.
## Make delegation reliable
A skill description is only a hint, and an agent's standing guidance to do small jobs
itself usually wins over it. If you want delegation to happen consistently in a
repository, add a line like this to that repository's `CLAUDE.md` or `AGENTS.md`, which
is in context on every turn:
```markdown
Codebase research, code review, and implementation that touches more than a file or two
go through the `copilot-worker` skill. Load it before reading three or more files.
```
## Models
Each run uses a profile, which fixes one model and one reasoning effort:
| Profile | Model | Effort |
| --- | --- | --- |
| `light` | `gpt-6-luna` | `medium` |
| `standard` | `gpt-6.1-terra` | `medium` |
| `deep` | `gpt-6.1-sol` | `medium` |
| `heavy` | `gpt-6-astra` | `medium` |
| Mode | Default profile |
| --- | --- |
| `research` | `light` |
| `review` | `deep` |
| `implement` | `standard` |
`review` defaults to a different model from `implement`, so worker-written code is not
reviewed by the model that wrote it. A run off its mode's default needs a `--reason`,
which `result.json` records, and a run that fails verification can be retried one
profile up, at most twice. Effort is capped at `xhigh`.
The profiles and defaults are the `PROFILES` and `DEFAULT_PROFILES` constants in
[scripts/copilot_worker.py](scripts/copilot_worker.py). `check --live` confirms that the
model catalog offers each profile's model and effort before it probes them.
## Safety
> [!WARNING]
> An implementation worker has full shell access apart from a short deny list
> (`git push`, `git remote`, `git worktree`, `gh`, `sudo`, `runas`), and its file tools are
> confined to its workspace. The deny list catches common forms of those commands, not
> code passed to an interpreter. The worktree isolates the
> worker's normal edits. It is not a sandbox: a shell command can still reach files
> outside it, including your live checkout.
See [SKILL.md](SKILL.md) for the full workflow and limits.
## Tests
From the repository root:
```bash
python -m unittest discover -s skills/copilot-worker/scripts -v
```
The unit tests need Python 3.11 or later but not the SDK. They use a fake engine and spend
no credits. `test_sdk_contract.py` checks the installed SDK against the pinned versions and
the names the engine uses, so it needs the SDK: without it those tests skip, and with
`REQUIRE_SDK_CONTRACT=1` they fail instead. CI sets that variable. To run them in the
environment the script header pins, follow step 4 of
[references/upgrading.md](references/upgrading.md).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |