VS Code Copilot Resource Sync

A PowerShell toolkit to sync, install, and manage GitHub Copilot agents, instructions, and skills from the awesome-copilot community catalogue — cherry-picking exactly what each repo needs, with full lifecycle management. Works on Windows, macOS, and Linux.

What This Does

Syncs the latest agents, instructions, and skills from awesome-copilot into a local cache (~/.awesome-copilot/) using git sparse checkout alongside the curated llms.txt catalogue
Initialises repos — intelligently recommends and installs resources into a repo's .github/ folder based on detected language/framework, with full install/update/remove lifecycle management

What goes where

Resource	Location	Description
Agents	`.github/agents/`	Custom Copilot personas (`*.agent.md`)
Instructions	`.github/instructions/`	Code standards and conventions (`*.instructions.md`)
Skills	`.github/skills/`	Multi-file task packages (`<skill-name>/` folders with `SKILL.md`)

Note: Advanced/distribution categories (hooks, plugins, workflows) remain supported via the -Category parameter if explicitly requested.

Prerequisites

PowerShell 7+ — runs on Windows, macOS, and Linux (Download PowerShell)
VS Code with GitHub Copilot extension
gh (GitHub CLI) or git — gh preferred (Download GitHub CLI); handles auth automatically
Internet connection for initial sync

macOS & Linux: Scripts run natively with pwsh. A POSIX wrapper (run.sh) is provided for seamless execution without invoking pwsh directly:
./run.sh configure                     # Run configure.ps1
./run.sh repo                          # Run init-repo.ps1
./run.sh user                          # Run init-user.ps1
./run.sh update                        # Run update-repo.ps1
./run.sh sync                          # Run sync-awesome-copilot.ps1
User directory paths on macOS (~/Library/Application Support/Code/User/prompts) and Linux (~/.config/Code/User/prompts) are resolved automatically. Terminal fuzzy picking is supported via fzf when installed, falling back to a numbered console menu.

Quick Start

1. Clone or Download

git clone <your-repo-url>
cd vscode-copilot-sync

2. Run the Configurator

# Sync from GitHub and prompt to configure user-level and repo resources
.\configure.ps1

# Sync + prompt for both pickers (same as above but explicit)
.\configure.ps1 -Install

# Sync + go straight to a specific scope without prompting
.\configure.ps1 -Install -Scope repo   # repo .github/ only
.\configure.ps1 -Install -Scope user   # user-level only
.\configure.ps1 -Install -Scope both   # both, no prompts

# Check for and apply all upstream updates (no pickers)
.\configure.ps1 -Update
.\configure.ps1 -Update -Force          # skip confirmation prompts
.\configure.ps1 -Update -Scope repo     # repo only
.\configure.ps1 -Update -DryRun         # preview what would be updated

# Sync only (no repo setup)
.\configure.ps1 -SkipInit

# Preview everything without writing any files
.\configure.ps1 -DryRun

3. Configure a Repo

Run from inside any repo to add agents, instructions, and skills to .github/:

cd C:\Projects\my-app
.\configure.ps1

# Or target a repo without cd-ing first
.\configure.ps1 -SkipSync -RepoPath "C:\Projects\my-app"

# Or call the script directly
.\scripts\init-repo.ps1
.\scripts\init-repo.ps1 -RepoPath "C:\Projects\my-app"

The picker auto-detects your language/framework and marks relevant items with ★. Items already installed show their status:

Symbol	Meaning
★	Recommended for this repo
`[*]`	Already installed
`[↑]`	Update available from upstream
`[~]`	Locally modified since install
`[U]`	Already installed at user level (globally)
`[!]`	Requires additional setup (MCP server, API key, etc.)

Tip: [U] items are already available everywhere via init-user.ps1. You can still install them repo-level if you want them committed to .github/.

4. Remove Installed Resources

# Remove resources from the current repo's .github/ only
.\configure.ps1 -Uninstall -Scope repo

# Remove user-level resources (prompts dir + skills dir)
.\configure.ps1 -Uninstall -Scope user

# Remove both repo and user-level resources in one pass
.\configure.ps1 -Uninstall

# Or target a sub-script directly
.\scripts\init-repo.ps1 -Uninstall
.\scripts\init-user.ps1 -Uninstall

Locally modified files are flagged with [~] before removal so you don't accidentally discard work.

Local Cache Structure

~/.awesome-copilot/
├── .git/                  # Git metadata (managed automatically)
├── agents/                # *.agent.md
├── instructions/          # *.instructions.md
├── skills/                # <skill-name>/ directories (SKILL.md + assets)
├── catalogue.json         # Curated catalogue metadata from llms.txt (titles, descriptions)
├── config.json            # Persistent user configuration (registries, defaults)
├── llms.txt               # Raw offline cache of curated catalogue
└── manifest.json          # Sync state (hashes, timestamps, counts)

Common Workflows

New machine setup

Run this once after cloning the repo on a new machine. It syncs the cache, installs your preferred general-purpose resources globally, then sets up whichever repo you are currently working in.

# 1. Sync the awesome-copilot cache
.\scripts\sync-awesome-copilot.ps1

# 2. Install agents, instructions, and skills you want active in every VS Code window
.\scripts\init-user.ps1

# 3. Configure the repo you are currently working in
.\scripts\init-repo.ps1

After this, user-level resources are always active. Repo-level resources are committed to .github/ and available to the whole team.

Configuring a new repo

Run from inside any repo — or pass -RepoPath from anywhere. Language and framework are auto-detected; relevant items are pre-marked with ★.

# From inside the repo
cd C:\Projects\my-app
.\path\to\vscode-copilot-sync\configure.ps1 -Install -Scope repo

# Or target it directly without cd-ing
.\configure.ps1 -Install -Scope repo -RepoPath "C:\Projects\my-app"

# Preview first without writing anything
.\configure.ps1 -Install -Scope repo -DryRun -RepoPath "C:\Projects\my-app"

-Scope repo skips the user-level step and the Y/N prompt, going straight to the repo pickers.

Multi-repo strategy

User-level resources (installed via init-user.ps1) are available in every VS Code window automatically — no .github/ commit needed. Repo-level resources are scoped to a single project and are committed for the whole team.

A practical split:

Use `init-user.ps1` for	Use `init-repo.ps1` for
General coding standards (security, accessibility, performance)	Framework-specific agents (e.g. `angular-expert`, `dotnet-expert`)
Cross-cutting skills (`refactor`, `create-readme`)	Project-specific hooks and workflows
Resources you always want, regardless of project	Resources the whole team should have in their repo

Items already installed at user level are shown with [U] in the repo picker — you can still install them repo-level if you want them committed, but it is not required.

Keeping resources current

Run configure.ps1 -Update whenever you want to pull the latest upstream changes for all subscriptions in one step — it syncs the cache then checks and applies updates for both user-level and repo-level resources.

# Sync + apply all updates (asks before writing)
.\configure.ps1 -Update

# Sync + apply all updates without prompting
.\configure.ps1 -Update -Force

# Scope to a single target
.\configure.ps1 -Update -Scope user    # user-level subscriptions only
.\configure.ps1 -Update -Scope repo    # repo subscriptions only

# Only update a specific category
.\configure.ps1 -Update -Category "agents"
.\configure.ps1 -Update -Category "instructions,hooks" -Scope repo

# Preview what would be updated without writing anything
.\configure.ps1 -Update -DryRun

Or call the update scripts directly for more control:

# 1. Pull the latest from awesome-copilot into the local cache
.\scripts\sync-awesome-copilot.ps1

# 2. Update user-level resources (agents, instructions, skills in %APPDATA% / ~/.copilot)
.\scripts\update-user.ps1

# 3. Update repo-level resources in the current repo
.\scripts\update-repo.ps1

# Or do all three non-interactively
.\scripts\sync-awesome-copilot.ps1
.\scripts\update-user.ps1 -Force
.\scripts\update-repo.ps1 -Force

update-repo.ps1 reads .github/.copilot-subscriptions.json; update-user.ps1 reads ~/.awesome-copilot/user-subscriptions.json. Only items you have previously installed are touched — nothing is added automatically.

Scripts

`configure.ps1` — Main entry point

Chains sync → user-level → repo init in one command.

.\configure.ps1                                       # Full run (sync + both prompts)
.\configure.ps1 -Install                             # Sync + go straight to repo pickers
.\configure.ps1 -Install -Scope repo                 # Repo pickers only, no prompt
.\configure.ps1 -Install -Scope user                 # User pickers only, no prompt
.\configure.ps1 -Install -Category "agents,skills"   # Only show agents + skills pickers
.\configure.ps1 -Update                              # Sync + update all subscriptions (no pickers)
.\configure.ps1 -Update -Scope repo                  # Repo subscriptions only
.\configure.ps1 -Update -Force                       # Update without confirmation prompts
.\configure.ps1 -Update -Category "instructions"     # Update only instruction subscriptions
.\configure.ps1 -Update -DryRun                      # Preview updates without writing
.\configure.ps1 -User                                # Sync + go straight to user-level picker
.\configure.ps1 -SkipInit                            # Sync + user-level only
.\configure.ps1 -SkipUser                            # Sync + repo only
.\configure.ps1 -SkipSync                            # Repo init only (no sync)
.\configure.ps1 -Uninstall -Scope repo               # Remove repo .github/ resources
.\configure.ps1 -Uninstall -Scope user               # Remove user-level resources
.\configure.ps1 -Uninstall                           # Remove both repo + user resources
.\configure.ps1 -RepoPath "C:\Projects\my-app"      # Target specific repo
.\configure.ps1 -ShowConfig                          # Display persistent configuration
.\configure.ps1 -DryRun                              # Preview all changes

`scripts/sync-awesome-copilot.ps1` — Sync cache

Clones (first run) or pulls (subsequent runs) github/awesome-copilot as a sparse git checkout.

Only downloads the categories you need (agents, instructions, skills by default)
Indexes the official llms.txt catalogue for human-readable titles, rich descriptions, and better recommendation scoring
Employs HTTP conditional requests (ETag / If-Modified-Since) returning HTTP 304 to skip downloading and indexing unchanged catalogues
Stores an offline raw cache in ~/.awesome-copilot/llms.txt with graceful fallback on network loss
SHA256 hash manifest tracks added/updated/removed counts across runs
Auto-recovers from merge conflicts in the local cache
Prefers gh CLI for auth; falls back to git

.\scripts\sync-awesome-copilot.ps1                          # Sync default categories
.\scripts\sync-awesome-copilot.ps1 -Plan                    # Dry run
.\scripts\sync-awesome-copilot.ps1 -Categories "agents,skills"
.\scripts\sync-awesome-copilot.ps1 -GitTool git             # Force git
.\scripts\sync-awesome-copilot.ps1 -Force                   # Skip safety checks

Breaking-change detection — on subsequent syncs the script runs two safety checks and exits before writing the manifest if either triggers:

Check	Trigger	Action
Structural	A previously-synced category folder is absent after pull	`STRUCTURAL CHANGE DETECTED` — lists missing folders, exits 1
Mass-removal	≥ 25 % of tracked files removed in one pull	`MASS-REMOVAL DETECTED` — shows ratio, exits 1

Re-run with -Force once you have reviewed the upstream changes and confirmed the new structure is intentional.

`scripts/init-repo.ps1` — Configure a repo

Interactively selects and installs Copilot resources into .github/.

Smart recommendations — scans repo files for language/framework signals (.cs, package.json, go.mod, Dockerfile, .github/workflows/*.yml, etc.) and pre-marks relevant items with ★. Falls back to an intent questionnaire for empty repos.

Full lifecycle — install, update, and remove, all tracked in .github/.copilot-subscriptions.json.

.\scripts\init-repo.ps1                                     # Interactive
.\scripts\init-repo.ps1 -RepoPath "C:\Projects\my-app"
.\scripts\init-repo.ps1 -DryRun                             # Preview
.\scripts\init-repo.ps1 -Uninstall                          # Remove resources
.\scripts\init-repo.ps1 -SkipAgents                         # Skip categories
.\scripts\init-repo.ps1 -Category "agents,skills"           # Show only agents + skills pickers
.\scripts\init-repo.ps1 -Agents "devops-expert,se-security-reviewer" -Instructions "powershell"

`scripts/update-repo.ps1` — Apply upstream updates

Reads .github/.copilot-subscriptions.json and applies any upstream changes from the local cache to installed resources.

.\scripts\update-repo.ps1                    # Interactive — prompts per item
.\scripts\update-repo.ps1 -DryRun           # Show what would change
.\scripts\update-repo.ps1 -Force            # Apply all without prompting
.\scripts\update-repo.ps1 -Category "agents,hooks"   # Only check these categories
.\scripts\update-repo.ps1 -RepoPath "C:\Projects\my-app"

Tip: The [↑] column in init-repo.ps1 shows update availability inline — run update-repo.ps1 when you want to apply them all at once.

`scripts/init-user.ps1` — Configure user-level resources

Installs agents, instructions, and skills into user-level locations, making them available across all repos and VS Code windows — no .github/ needed.

Resource	Location
Agents	`%APPDATA%\Code\User\prompts\*.agent.md`
Instructions	`%APPDATA%\Code\User\prompts\*.instructions.md`
Skills	`~/.copilot/skills/<name>/`

This is ideal for general-purpose, tech-agnostic resources you always want active (e.g. security standards, accessibility guidelines, cross-cutting agents). Tech-specific items are still available in the picker but not pre-starred.

Full lifecycle — install, update, and remove, tracked in ~/.awesome-copilot/user-subscriptions.json.

.\scripts\init-user.ps1                                # Interactive (agents + instructions + skills)
.\scripts\init-user.ps1 -DryRun                        # Preview
.\scripts\init-user.ps1 -Uninstall                     # Remove user-level resources
.\scripts\init-user.ps1 -Bootstrap                     # Register already-installed files (no picker, no copies)
.\scripts\init-user.ps1 -Bootstrap -DryRun             # Preview what bootstrap would register
.\scripts\init-user.ps1 -SkipSkills                    # Agents + instructions only
.\scripts\init-user.ps1 -SkipAgents -SkipInstructions  # Skills only
.\scripts\init-user.ps1 -Category "agents,skills"      # Show only agents + skills pickers
.\scripts\init-user.ps1 -Agents "beastmode,se-security-reviewer"
.\scripts\init-user.ps1 -Instructions "security-and-owasp,markdown-accessibility"
.\scripts\init-user.ps1 -Skills "refactor,create-readme"

# Non-default VS Code installations
.\scripts\init-user.ps1 -PromptsDir "$env:APPDATA\Code - Insiders\User\prompts"

-Bootstrap is useful when user-subscriptions.json is missing but resources are already on disk — for example after upgrading from v1.x or after manually copying files from the cache. It registers them all as subscriptions so update-user.ps1 can track and update them without requiring a full reinstall through the picker.

`scripts/update-user.ps1` — Apply upstream updates to user-level resources

Reads ~/.awesome-copilot/user-subscriptions.json and refreshes installed user-level agents, instructions, and skills from the local cache.

.\scripts\update-user.ps1                    # Interactive
.\scripts\update-user.ps1 -DryRun           # Show what would change
.\scripts\update-user.ps1 -Force            # Apply all without prompting
.\scripts\update-user.ps1 -Category "agents,skills"   # Only check these categories
.\scripts\update-user.ps1 -SkillsDir "~/custom/skills"  # Non-default skills location

Configuration

Persistent Configuration (`config.json`)

The toolkit supports persistent configuration stored in ~/.awesome-copilot/config.json. To inspect current settings:

.\configure.ps1 -ShowConfig

This file configures default synchronisation scopes, default category sets, custom registries, and directory overrides without needing command-line flags on every run.

Authentication

gh CLI is preferred — inherits from gh auth login, no extra setup. If only git is available, the public github/awesome-copilot repo requires no credentials. For private forks, configure git credentials as usual.

Custom Source Repository

Edit two variables near the top of scripts/sync-awesome-copilot.ps1:

$RepoSlug = 'your-username/your-fork'
$RepoUrl  = 'https://github.com/your-username/your-fork.git'

Troubleshooting

Execution policy error (Windows only)

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

This is a Windows-only restriction. macOS and Linux are unaffected.

Sync fails with merge conflict

The script auto-recovers (git reset --hard origin/HEAD). If it persists, delete ~/.awesome-copilot and re-run — it will re-clone fresh.

Logs

Sync logs are written to scripts/logs/sync-YYYYMMDD-HHMMSS.log:

Get-ChildItem .\scripts\logs\sync-*.log | Sort-Object LastWriteTime -Descending | Select-Object -First 1 | Get-Content

FAQ

What is awesome-copilot? awesome-copilot is the community-maintained catalogue of GitHub Copilot resources — agents, hooks, instructions, skills, and workflows contributed by hundreds of developers. vscode-copilot-sync makes it easy to cherry-pick and manage resources from that catalogue.

Does vscode-copilot-sync work on macOS and Linux? Yes. All scripts run on PowerShell 7+ (pwsh) on Windows, macOS, and Linux, and a POSIX wrapper (run.sh) is provided for Unix environments. The interactive picker defaults to a cross-platform console selector (fzf fuzzy multi-select or numbered console menu) across all platforms. The legacy Windows GUI table picker (-Gui / Out-GridView) is deprecated and scheduled for removal in v3.0.

Will it overwrite files I've written myself? No. The scripts only track and manage files they installed, recorded in .github/.copilot-subscriptions.json. User-created files are never touched. Locally modified files are flagged with [~] and require explicit confirmation before any update.

Do I need a GitHub account? No account is needed to sync from the public awesome-copilot repository. The scripts use gh CLI if available but fall back to unauthenticated git for the public source.

How is this different from VS Code's built-in Settings Sync? VS Code Settings Sync backs up editor settings and extensions. vscode-copilot-sync manages Copilot-specific resources (agents, instructions, skills) from the community catalogue — content that Settings Sync does not cover.

How often should I run the sync? Run .\configure.ps1 -Update whenever you want to pull upstream additions. This syncs the cache and applies any updates to your subscriptions in one step. There is no scheduled sync — you decide when to update.

Related Projects

Project	Description
Symdicate	Composable multi-agent framework for GitHub Copilot — persona grafting, cognitive identity caching, and agent fusion
ReFrame	GitHub Copilot agent for PC game configuration optimisation — detects hardware and recommends targeted performance improvements
awesome-copilot	The community catalogue that vscode-copilot-sync syncs from

Security & Accessibility

Security Architecture: Strictly isolates local environments, enforces $ErrorActionPreference = 'Stop', and guards against path traversal with Assert-PathWithin across all write and update operations. See SECURITY.md for vulnerability reporting and containment details.
Terminal Accessibility: Every status indicator pairs ANSI colour with unambiguous text symbols ([★], [*], [↑], [~], [U], [!]), ensuring full legibility on monochrome terminals and for users with protanopia, deuteranopia, or low vision. Contrast adheres to WCAG standards across dark and light terminal themes.
Interactive Navigation: Cross-platform terminal selection is the default on all platforms. With fzf installed, fuzzy filtering includes keyboard shortcuts (TAB to toggle, ENTER to confirm, ESC to cancel); without fzf, a numbered console menu provides range selection (1-3) and recommendation shortcuts (rec / r). The legacy -Gui switch (Out-GridView) is deprecated and scheduled for removal in v3.0.

Contributing

Contributions welcome! Fork, branch, test, PR.

License

MIT — see LICENSE

Acknowledgments

awesome-copilot — Community resource repository
GitHub Copilot — AI pair programmer

Made with ❤️ for the VS Code + Copilot community

Name		Name	Last commit message	Last commit date
.github		.github
schemas		schemas
scripts		scripts
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.markdownlint.jsonc		.markdownlint.jsonc
.markdownlintignore		.markdownlintignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
TODO.md		TODO.md
configure.ps1		configure.ps1
cspell.json		cspell.json
llms.txt		llms.txt
package-lock.json		package-lock.json
package.json		package.json
run.sh		run.sh

Latest commit

History

Folders and files

Repository files navigation

VS Code Copilot Resource Sync

What This Does

What goes where

Prerequisites

Quick Start

1. Clone or Download

2. Run the Configurator

3. Configure a Repo

4. Remove Installed Resources

Local Cache Structure

Common Workflows

New machine setup

Configuring a new repo

Multi-repo strategy

Keeping resources current

Scripts

configure.ps1 — Main entry point

scripts/sync-awesome-copilot.ps1 — Sync cache

scripts/init-repo.ps1 — Configure a repo

scripts/update-repo.ps1 — Apply upstream updates

scripts/init-user.ps1 — Configure user-level resources

scripts/update-user.ps1 — Apply upstream updates to user-level resources

Configuration

Persistent Configuration (config.json)

Authentication

Custom Source Repository

Troubleshooting

Execution policy error (Windows only)

Sync fails with merge conflict

Logs

FAQ

Related Projects

Security & Accessibility

Contributing

License

Acknowledgments

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`configure.ps1` — Main entry point

`scripts/sync-awesome-copilot.ps1` — Sync cache

`scripts/init-repo.ps1` — Configure a repo

`scripts/update-repo.ps1` — Apply upstream updates

`scripts/init-user.ps1` — Configure user-level resources

`scripts/update-user.ps1` — Apply upstream updates to user-level resources

Persistent Configuration (`config.json`)