2026-04-14: Syncing organisation-wide agent skills via a shared Git repository and a shell script

2026-04-14 Accepted

Context

GitHub Copilot supports Agent Skills: structured SKILL.md files placed in a directory that VS Code reads at startup. Skills encode domain-specific workflows and best practices that the AI agent can follow consistently across sessions.

Two categories of skills exist in our context:

• Repository-scoped skills — knowledge tied to a specific codebase (stack conventions, project-specific workflows). These live inside the repository they describe.
• Organisation-wide skills — transversal knowledge applicable to any project (e.g. how to write an ADR, how to generate a README, our task automation standard). These need to be shared across all developers and all repositories.

The question is: how should organisation-wide skills be distributed to every developer’s local machine so they are always available, regardless of which project is open?

Alternatives considered:

1. Commit skills into every repository — duplicate content across repos; hard to keep in sync.
2. A dedicated GitHub Package or registry — no native support exists in the Copilot ecosystem for this; would require custom tooling.
3. Claude’s skill marketplace — only applicable to Claude-based agents; we do not use Claude as our primary tool.
4. A central repository + a sync script — check in skills once, pull them on demand to ~/.copilot/skills/.

Decision

Organisation-wide agent skills are maintained in skills/ inside the Groupe-3D/Groupe-3D repository. A shell script (skills/sync.sh) sparse-clones the repository and copies each skill directory into ~/.copilot/skills/ on the developer’s machine. Developers run the script manually (or via a shell alias) whenever they want to pull the latest skills.

Rationale

Why not commit skills into every repository

Duplicating skill files across every project repository creates a maintenance burden: a change to a shared skill requires a PR in every affected repo. There is no single source of truth, and drift between copies is inevitable.

Why not a dedicated package registry

No package manager or registry integration exists today for Copilot skills. Building one would require significant custom infrastructure for a problem that can be solved with much simpler tooling.

Why not Claude’s marketplace

The organisation’s primary AI assistant is GitHub Copilot, not Claude. A Claude-specific distribution mechanism does not apply here.

Why a central repository + sync script

• The Groupe-3D/Groupe-3D repository is already the organisation-wide reference for cross-cutting decisions and tooling. Hosting skills there is consistent with its purpose.
• A shell script is the simplest possible distribution mechanism: no new infrastructure, no dependencies beyond git and rsync, and auditable in a single file.
• ~/.copilot/skills/ is the standard location VS Code reads for user-level skills. Installing there keeps repo-scoped and organisation-scoped skills clearly separated.
• The script uses a sparse clone (--depth 1 --sparse) so developers only download the skills/ subtree — the rest of the repository is not transferred.
• Personal skill directories the developer placed in ~/.copilot/skills/ are never deleted: the script only writes directories present in the organisation repository. Files manually added inside an org-managed skill directory are not preserved, as those directories are mirrored exactly from the repo (rsync --delete).

Trade-offs

• The setup requires a one-time manual step (cloning the org repo and either running the script or setting up the alias). It is not automatic.
• Skills are not updated in real time. Developers must re-run the sync script to pick up changes. This is acceptable given that skills evolve infrequently.
• The repository is private, which prevents simpler distribution methods (e.g. curl from raw.githubusercontent.com). All developers must have SSH access to the organisation.
• Local edits or extra files inside organisation-managed skill directories are not preserved across syncs, because the script uses rsync --delete when refreshing those directories.
• Devcontainer users require additional configuration (a bind mount and a VS Code setting) to expose the host skills inside the container.

Consequences

• skills/ in Groupe-3D/Groupe-3D is the single source of truth for organisation-wide agent skills.
• Every developer must run skills/sync.sh (or the sync-skills alias) at least once to install skills, and again after any update to the skills/ directory.
• Devcontainer configurations in project repositories must include the bind mount and github.copilot.chat.skillsLocations setting documented in the codex AI tools page.
• Repository-scoped skills (if any) continue to live inside the relevant repository, independently of this mechanism.
• When Copilot introduces native skill distribution (e.g. a marketplace or organisation-level settings), this ADR should be revisited and potentially superseded.