proposal: install local path as symlink (--link flag)#207
Conversation
App-bundled skills (e.g. Surge's built-in skill shipped inside the .app bundle) silently fall behind after each app update because skillshare install copies rather than links. Proposes a --link flag for local paths so the source-tree entry is a symlink and skill content stays live. Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds a feature proposal describing a new skillshare install --link flag to install local skills via symlink instead of copying, aimed at keeping app-bundled skills (e.g., Surge) automatically up-to-date.
Changes:
- Introduces a new proposal document for symlink-based installs (
--link/-L) for local-path sources. - Specifies expected behavior across adjacent commands (
list,check,update,uninstall,doctor,sync). - Outlines scope, touch points, and open questions (config persistence, Windows behavior, collect semantics, name override).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | Command | Linked skill behavior | | ||
| |---|---| | ||
| | `skillshare list` | Show `→ /path/to/target` instead of `(local)` to make the live link visible | | ||
| | `skillshare check` | Report "externally managed — link is live" when the target path exists | | ||
| | `skillshare update` | Skip with "externally managed" message (the link is always current) | | ||
| | `skillshare uninstall` | Remove the symlink; do **not** touch the target directory | | ||
| | `skillshare doctor` | Warn when a linked target no longer exists (broken symlink) | |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a feature proposal to add a --link flag to skillshare install, allowing local paths to be installed as symlinks rather than copied. The review feedback suggests several design improvements and clarifications, including visually highlighting broken symlinks in the list command, clarifying how sync handles broken links and target symlink modes, and utilizing directory junctions on Windows to avoid privilege escalation issues.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
|
|
||
| | Command | Linked skill behavior | | ||
| |---|---| | ||
| | `skillshare list` | Show `→ /path/to/target` instead of `(local)` to make the live link visible | |
There was a problem hiding this comment.
Handling Broken Links in skillshare list
If the symlink is broken (i.e., the target directory was deleted or moved), skillshare list should visually indicate this (e.g., by appending a [broken] suffix or displaying the path in red/dimmed text). This will make it immediately obvious to the user that the link is inactive without needing to run skillshare doctor.
|
|
||
| ### Sync behavior | ||
|
|
||
| `skillshare sync` should follow the symlink when propagating to targets, not copy the symlink itself. This matches how the current flow works today when users place symlinks manually in the source directory. |
There was a problem hiding this comment.
Sync Behavior Clarification
It would be beneficial to clarify the behavior of skillshare sync under two specific scenarios:
- Broken Symlinks: If the source symlink is broken (the target path no longer exists), how should
skillshare synchandle it? It should ideally skip the skill and emit a warning rather than failing the entire sync operation. - Target Symlink Mode: If a target is configured with
mode: symlink, should the symlink created in the target directory point to the skillshare source directory symlink (e.g.,~/.config/skillshare/skills/surge) or resolve to the ultimate original path (e.g.,/Applications/...)? Pointing to the source symlink is generally preferred to maintain the indirection, but this should be explicitly specified.
|
|
||
| 1. **Config persistence** — Should `--link` be a CLI-only flag per invocation, or should it be persisted in `config.yaml` (e.g. as `mode: link` at the skill level) so that `skillshare install` (no args, from config) recreates the symlink? A config-level key would make the intent declarative and reproducible across machines. | ||
|
|
||
| 2. **Cross-device / Windows** — On Windows, directory symlinks require elevated permissions or Developer Mode. Should skillshare fall back to a junction point, emit a clear error, or document the limitation? (macOS and Linux have no restrictions.) |
There was a problem hiding this comment.
Windows Junction Fallback
On Windows, directory symlinks indeed require elevated privileges (unless Developer Mode is enabled), whereas directory junctions (junctions) do not.
Since skillshare already has some Windows junction support helper functions (as seen in internal/utils/link.go), the implementation should default to or fall back to creating a directory junction on Windows when --link is used. This ensures a seamless developer experience without requiring users to run the CLI as Administrator.
Type
proposals/only — see CONTRIBUTING.md)Linked Issue
Closes #206
Summary
App-bundled skills silently fall behind after app updates because
skillshare install <local-path>copies files rather than creating a symlink.Concrete example: Surge for macOS ships an authoritative skill at
/Applications/Surge.app/Contents/Resources/Skills/surge. After installing, the skillshare copy diverges from the app bundle on every Surge update. The only fix today is re-runninginstall --forceor manually placing a symlink in the source directory — both bypass skillshare's tracking.This proposal adds a
--linkflag toinstallfor local paths. Instead of copying, skillshare places a symlink in the source tree so skill content always reflects the live path.skillshare install --link /Applications/Surge.app/Contents/Resources/Skills/surge # source tree: ~/.config/skillshare/skills/surge → /Applications/.../surgeSee
proposals/206-install-link.mdfor the full design including CLI surface, metadata, adjacent-command behavior, and open questions.Checklist
make check) — proposal only, no code changes