Skip to content
This repository was archived by the owner on Oct 22, 2026. It is now read-only.
CTOUTPublic archive

About

PowerShell toolkit to sync, install, and manage GitHub Copilot agents, instructions, hooks, and skills from awesome-copilot — works on Windows, macOS, and Linux.

Topics

Resources

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

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.

Project Status

Project Status: This is the final feature release (v2.5) of vscode-copilot-sync. The repository will be archived. Its successor, agentsmith, continues this work as a cross-environment, runtime-agnostic agent asset manager supporting VS Code, Kiro, Antigravity, and more.

What This Does

  1. 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
  2. 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

Project Direction

The current toolkit focuses on Awesome Copilot resources and Copilot-oriented destinations. The longer-term product direction is cross-agent asset management across supported IDEs, CLIs, and agent workspaces. See Product Direction for the strategy, interoperability boundaries, and validation questions. This is a direction under validation; it does not describe capabilities already implemented.

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-level customizations are installed under ~/.copilot on all platforms. Existing files in the former VS Code prompts directory remain manageable for update, uninstall, and bootstrap operations. 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 (~/.copilot and its skills directory)
.\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, and skills under ~/.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 Copilot harness sessions in all repos — no .github/ needed.

Resource Location
Agents ~/.copilot/agents/*.agent.md
Instructions ~/.copilot/instructions/*.instructions.md
Skills ~/.copilot/skills/<name>/

Note: If skills are found in ~/.agents/skills from a previous setup, they are migrated automatically to ~/.copilot/skills on the next run.

VS Code stores user MCP server configuration separately in $COPILOT_HOME/mcp-config.json, or ~/.copilot/mcp-config.json when COPILOT_HOME is not set. These scripts do not manage that file.

On the next user-scoped configure.ps1 run, install, update, bootstrap, or uninstall, legacy *.agent.md and *.instructions.md files in the former VS Code prompts directory are migrated to the locations above. The source is removed only after the copied file's SHA-256 hash is verified. Identical duplicates are removed; conflicting files are left intact and reported for manual resolution. Other prompt files are not moved.

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"

# Override the user customization directories
.\scripts\init-user.ps1 -AgentsDir "$HOME/.copilot/agents" -InstructionsDir "$HOME/.copilot/instructions"

-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


Made with ❤️ for the VS Code + Copilot community

About

PowerShell toolkit to sync, install, and manage GitHub Copilot agents, instructions, hooks, and skills from awesome-copilot — works on Windows, macOS, and Linux.

Topics

Resources

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages