Copilot Drive

Engineering guidance for building things for GitHub Copilot.

If your organization only allows Copilot, this is the tool that helps you build well inside it: what already exists officially, which artifact type fits your problem, how to structure it, and what silently breaks across IDEs.

Status: pre-alpha (v0.1.0). Working, and not yet published anywhere. Development plan in docs/plano-de-desenvolvimento.md (Portuguese).

What this is, next to what already exists

Catalogues like awesome-copilot give you artifacts for tasks — hundreds of instructions, agents and skills to drop in. This is the other half: it does not hand you an artifact, it tells you which one to build and what will silently fail.

Three things it carries that a catalogue does not:

• Dated deprecation knowledge. *.chatmode.md was renamed in VS Code v1.106, November 2025, and Copilot still generates the dead format unprompted. mode: became agent:. infer: was split into two fields, and Copilot CLI fails to parse an agent that still has it. Every such claim in the manuals carries a verification date, and CI warns when one goes stale.
• A portability matrix across clients. AGENTS.md reaches 2 of 6 IDEs. Path-specific instructions never reach Eclipse. Hook event names are camelCase on GitHub and PascalCase in VS Code, so a hook written from the GitHub docs does not fire in VS Code. Only copilot-instructions.md reaches everything.
• A reviewer for artifacts you already have, plus a validator you can run in CI.

The closest neighbour we found, htekdev/copilot-plugin-skill, covers building CLI plugins only — no instructions, no prompt files, no review, no deprecation tracking.

Install

npx cit-copilot-drive install .          # the repository you are in
npx cit-copilot-drive remove .           # take it back out

That copies the skill to .github/skills/cit-copilot-drive/ and the agents to .github/agents/, which VS Code reads on its own. Nothing is registered, no setting is changed, and uninstalling is deleting files.

The npm package is cit-copilot-drive; the skill it installs is cit-copilot-drive, and that is the name you reach in chat. They differ because the package name had to be free on a public registry — nothing about the artifacts changed.

Why npm and not the plugin marketplace. The supported route is copilot plugin marketplace add

• copilot plugin install, and it is the better one where it is available — it installs once per user and works in every repository. It is not available to the people this ships to, whose environments block fetching a plugin from its source but already allow the npm registry. So the channel that actually arrives is the one documented above.

🔴 Per repository, not per user. Because these land in .github/, they become part of that repository. Run the install in each repository where you want the tool, and do not commit the files unless you mean to share them with everyone working there.

If you do have the plugin route

copilot plugin marketplace add filiperibeirociandt/cit-copilot-drive
copilot plugin install cit-copilot-drive@cit-copilot-drive

Plugins installed with the Copilot CLI are also picked up by VS Code, under Agent Plugins — Installed. VS Code has its own routes too: Chat: Open Customizations → Plugins tab → Browse Marketplace · Chat: Install Plugin From Source with a Git URL · or point chat.pluginLocations at a local folder.

🔴 That setting wants the folder holding plugin.json — here that is plugins/cit-copilot-drive/, not the repository root. See references/plugins.md. It was also observed registering a plugin while its components did not load, and we never isolated why.

What's inside

| Component | How you reach it | Purpose | |---|---|---| | cit-copilot-drive skill | /cit-copilot-drive in either client | Decides which artifact you need, how to structure it, and what breaks | | 16 reference manuals | opened by the skill on demand | One self-contained manual per artifact type, plus portability, cost, security, evals and cross-OS | | review agent | copilot --agent cit-copilot-drive:cit-review-v2 | Detects known defects in artifacts you already have — dead formats, silent load failures, reach gaps, least-privilege problems. An orchestrator over six single-job workers, read-only by design |

Known limitations — read before relying on it

These are measured, not guessed. Each one is written up in the reference manuals.

The skill does not load automatically in VS Code. VS Code does not expose skills as tools to the model at all, so it will never pick this up on its own there — use /cit-copilot-drive. In Copilot CLI automatic invocation does work. The VS Code documentation says otherwise; it is wrong.

Reference manuals may need the plugin path granted. The manuals live in the plugin directory, which is outside the repository you are working in, and the CLI denies reads outside the workspace. If an answer looks thin, grant the path:

copilot --add-dir ~/path/to/cit-copilot-drive/plugins/cit-copilot-drive/skills/cit-copilot-drive

Windows is unverified. The deliverable is Markdown and JSON only, so it has no operating system of its own, and the maintenance scripts are Node with no dependencies. But nothing here has been run on Windows yet.

The review agent detects; it does not judge. Its rubric is a documented, growing checklist. On a held-out set of ten cases it caught every defect it had a rule for, and missed almost every case where the artifact was well written and simply the wrong kind of thing. Use it to catch what you would have to memorise — not as a second opinion on whether the thing should exist.

The slash command differs between clients. /cit-copilot-drive in Copilot CLI; /cit-copilot-drive cit-copilot-drive in VS Code, which the autocomplete collapses to /cit-copilot-drive.

Repository layout

plugins/cit-copilot-drive/            the artifacts themselves — this is what ships
.github/agents/cit-refresh.agent.md   re-verifies the dated facts — maintenance, does NOT ship
bin/copilot-drive.mjs                         the published CLI: `npx cit-copilot-drive install`
lib/install.mjs                   what it does, so the CLI and the script cannot drift apart
.github/plugin/marketplace.json   kept for the plugin route, where that route is open
scripts/validate-kit.mjs          holds this kit to the rules it teaches
evals/                             activation A/B harness, and the reviewer's fixture
docs/                             decisions and development plan (Portuguese)
research/                         the verified knowledge base this is built on (Portuguese)

Everything under plugins/ is Markdown and JSON — what gets installed executes nothing. The CLI and the maintenance scripts are Node with built-ins only: the package.json exists to publish the CLI and declares no dependencies.

Contributing

node scripts/validate-kit.mjs          # invisible Unicode, blind refs, manifests, least privilege
node evals/description-activation.mjs  # does the model still invoke the skill on its own?

🔴 Never change the skill's description without running the second one. A longer, better-looking description was measured killing automatic invocation on six of six prompts, with no error message anywhere.

License

MIT © 2026 CI&T