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 |
references/upgrading.md
View on GitHub# Upgrading the Copilot SDK and runtime
The worker is pinned to one GitHub Copilot SDK and the one Copilot runtime that SDK
carries. Upgrading either is a deliberate change made with this procedure, never a side
effect of running the script.
## What is pinned, and where
| What | Where |
| --- | --- |
| The SDK version | `scripts/pins.json` (`sdk`) and the `github-copilot-sdk==` line in the header of `scripts/copilot_worker.py` |
| The runtime version | `scripts/pins.json` (`runtime`). Each SDK release carries its own runtime and downloads it, checked against published checksums, so the two always move together |
| Every package the SDK needs | The same header, each at an exact `==` version |
The header lists the whole dependency set, not only the SDK, because the SDK's own
requirements are loose ranges (`pydantic>=2.0`, `httpx>=0.24`) that would otherwise float.
> [!NOTE]
> A lockfile (`uv lock --script`) was tried and rejected. It records the `exclude-newer`
> setting and package index of the machine that made it, and `uv run` ignores it and
> re-resolves when the user's configuration differs. Exact pins in the header behave the
> same on every machine and mirror.
## What enforces the pins
- The engine refuses to start a worker when the installed SDK or runtime differs from
`scripts/pins.json`. The run ends `failed`, and `stderr.log` names the difference.
- `check` prints a `pins:` line and fails on a mismatch.
- The unit and contract tests run in CI against an environment built from the header, and
fail when the header, `scripts/pins.json`, the installed SDK, or the SDK's dependency set disagree.
## Upgrade procedure
1. **Pick the SDK version** and read its release notes. Look for changes to permission
handling, session options, event types, and the names of the runtime's built-in tools.
2. **Find its runtime and its dependency set:**
```bash
uv run --no-project --no-config --with github-copilot-sdk==NEW \
python -c "from copilot._cli_version import CLI_VERSION; print(CLI_VERSION)"
echo "github-copilot-sdk==NEW" | uv pip compile - --no-config --no-header --no-annotate
```
3. **Update the header** in `scripts/copilot_worker.py` with the compiled list, and
`scripts/pins.json` with the new `sdk` and `runtime`.
4. **Run the tests** from the repository root, in the environment the header describes:
```bash
python - > /tmp/copilot-worker-requirements.txt <<'PY'
import pathlib, re
header = pathlib.Path("skills/copilot-worker/scripts/copilot_worker.py").read_text().split("# ///", 2)[1]
print("\n".join(re.findall(r'^#\s+"([^"]+)",?$', header, re.MULTILINE)))
PY
REQUIRE_SDK_CONTRACT=1 uv run --no-project --with-requirements /tmp/copilot-worker-requirements.txt \
python -m unittest discover -s skills/copilot-worker/scripts -v
```
A failing contract test names the SDK option, class, or field that moved. Change the
engine to match, and do not loosen the test.
5. **Check what the tests cannot see.** The SDK does not validate tool names, so a renamed
runtime tool shows up only as a worker without that tool. Run the live check, then one
`implement` task that runs a shell command, and read `permissions.jsonl` and
`events.jsonl` for anything unexpected:
```bash
uv run skills/copilot-worker/scripts/copilot_worker.py check --live
```
The shell tools differ by platform (`SHELL_TOOLS` in `scripts/worker_engine.py`):
`bash` and its companions on macOS and Linux, `powershell` and its companions on
Windows. Run the `implement` check on Windows too when the upgrade touches shell
handling.
6. **Update the documentation** that mentions behavior the upgrade changed, and say in the
pull request which SDK and runtime versions moved.
## What the contract tests do not cover
- Whether the runtime still offers the built-in tools in `TOOLS` under the same names.
- How the runtime behaves: permission prompts, shell handling, and the content of events.
- Event shapes beyond the fields the engine reads. A parser built on `events.jsonl` needs
its own tests when it exists.
## Housekeeping
The SDK keeps each runtime it has downloaded in its cache directory
(`~/Library/Caches/github-copilot-sdk/cli/` on macOS, `~/.cache/github-copilot-sdk/cli/`
on Linux, `%LOCALAPPDATA%\github-copilot-sdk\cli\` on Windows). Old versions stay there unused after an
upgrade and can be deleted.
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 |