github / github/copilot-cli

Document symlink behavior on Windows and other OS for files in .copilot folder

Open
#3,264 1 comment 0 reactions 0 assignees View on GitHub
area:configuration area:plugins
Dominant language
Shell
Stars
11.2k
Forks
1.9k
Avg merge
14h 16m
Merged PRs (30d)
6

Description

### Describe the feature or problem you'd like to solve

I want to use symlinks for .copilot files so that I can separately maintain and share them

### Proposed solution

Title: Document symlink support for ~/.copilot/ configuration files (instructions, skills)

Labels: documentation, enhancement

-------------------------------------------------------------------------------------------------------------------

Summary

The Copilot CLI loads several configuration artifacts from ~/.copilot/ at startup — including
copilot-instructions.md, skills/*/SKILL.md, lsp-config.json, and mcp-config.json. The current documentation is
silent on whether symbolic links within this directory tree are followed when the CLI reads these files. This
creates uncertainty for users who want to manage their Copilot configuration under version control.

-------------------------------------------------------------------------------------------------------------------

Use Case

I maintain a personal set of Copilot skills and instruction files that I want to:

1. Version-control in a GitHub repository (e.g., a copilot-config or dotfiles repo) so that changes are tracked,
documented, and revertible.
2. Share with colleagues so that team-wide instructions, shared skills, and MCP configurations are consistent
across machines without manual copying.
3. Keep a single source of truth — the git repo — rather than maintaining separate copies in ~/.copilot/ and a
config repo that can drift out of sync.

The natural solution is to store the canonical files in the git repo and create symbolic links from ~/.copilot/ into
the repo:

~/.copilot/copilot-instructions.md → ~/dotfiles/.copilot/copilot-instructions.md
~/.copilot/skills/my-skill/ → ~/dotfiles/.copilot/skills/my-skill/
~/.copilot/mcp-config.json → ~/dotfiles/.copilot/mcp-config.json

This is a standard pattern for managing dotfiles (used widely with tools like stow, chezmoi, and dotbot) and is
directly analogous to how many developers manage shell configs (.bashrc, .zshrc, .gitconfig, etc.).

-------------------------------------------------------------------------------------------------------------------

Current Problem

It is not documented whether the Copilot CLI:

- Follows symlinks when reading files from ~/.copilot/ (the common OS behavior for file reads)
- Resolves and validates paths before loading, which might reject symlinks pointing outside ~/.copilot/
- Watches for changes via filesystem events in a way that may or may not propagate through symlinks

Without documentation, users who set up symlinks have no confidence the setup works correctly, and there's no way to
know if a future CLI update might break it.

-------------------------------------------------------------------------------------------------------------------

Requested Change

1. Document explicitly whether symbolic links are supported for:
- ~/.copilot/copilot-instructions.md
- ~/.copilot/skills//SKILL.md (and the directory itself)
- ~/.copilot/mcp-config.json and ~/.copilot/lsp-config.json
2. If symlinks are supported, add a brief example in the docs showing the dotfiles pattern above and confirming it
works on Windows (mklink/junction), macOS, and Linux.
3. If symlinks are not currently supported, consider it as a feature request — the implementation cost is typically
zero (just avoid O_NOFOLLOW flags and don't restrict paths), and the benefit to configuration-management workflows
is significant.

-------------------------------------------------------------------------------------------------------------------

Environment

- Platform: Windows 11 (PowerShell 7)
- CLI version:
1.0.45
- Use case: personal productivity + project team shared skills

-------------------------------------------------------------------------------------------------------------------

### Example prompts or workflows

Most of the workflows I would use would be manual and security controlled, so likely not instituted by copilot, just reenforces my ability to use configuration control to manage these artifacts.

### Additional context

_No response_

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.