Problem
skillshare install <local-path> always copies the skill directory into the skillshare source tree. This works fine for standalone skills but breaks the expected workflow when the skill is owned by another application that ships it as part of its bundle.
Concrete example — Surge for macOS:
Surge ships a built-in skill at /Applications/Surge.app/Contents/Resources/Skills/surge. This skill describes every surge-cli command and is the authoritative reference for the Surge skill. The app team maintains and updates it with each release.
After skillshare install /Applications/Surge.app/Contents/Resources/Skills/surge, skillshare creates a snapshot copy in ~/.config/skillshare/skills/surge/. When Surge updates (e.g., new commands added to command-reference.md), the copy silently falls behind. There is no skillshare update path because the source is not a git repo — the only fix is to re-run skillshare install --force, which most users will not remember to do.
The workaround is to manually delete the copy and create a symlink in the source directory pointing to the app bundle path — but this bypasses skillshare's metadata and requires direct edits to the source directory, which CONTRIBUTING.md explicitly discourages.
Proposed Solution
Add a --link flag to skillshare install for local paths:
skillshare install --link /Applications/Surge.app/Contents/Resources/Skills/surge
Instead of copying the directory, skillshare places a symlink in the source tree:
~/.config/skillshare/skills/surge → /Applications/Surge.app/Contents/Resources/Skills/surge
The skill content always reflects the live app bundle. No manual re-install needed after app updates.
Other design points worth discussing in a proposal:
skillshare list should display linked skills with a distinct indicator (e.g. → /path/to/source) so users can see which skills are live-linked vs. copiedskillshare check / skillshare update should handle linked skills gracefully (skip or report "externally managed")skillshare uninstall should remove the symlink without touching the target directoryskillshare doctor could warn when a link target no longer exists
Who Is Affected
Anyone who installs skills that are bundled and maintained by another application (e.g. Surge, or any CLI tool that ships its own skill file). Also useful for developers who author a skill in one repo and want it live-linked into their skillshare source without maintaining a copy.
Alternatives Considered
- Re-run
install --force after each app update — fragile, easy to forget, breaks the "install once" contract
- Manual symlink in source dir — works but bypasses skillshare metadata/tracking entirely
- Watch-based auto-sync — heavier than needed; a simple symlink at install time is sufficient
Problem
skillshare install <local-path>always copies the skill directory into the skillshare source tree. This works fine for standalone skills but breaks the expected workflow when the skill is owned by another application that ships it as part of its bundle.Concrete example — Surge for macOS:
Surge ships a built-in skill at
/Applications/Surge.app/Contents/Resources/Skills/surge. This skill describes everysurge-clicommand and is the authoritative reference for the Surge skill. The app team maintains and updates it with each release.After
skillshare install /Applications/Surge.app/Contents/Resources/Skills/surge, skillshare creates a snapshot copy in~/.config/skillshare/skills/surge/. When Surge updates (e.g., new commands added tocommand-reference.md), the copy silently falls behind. There is noskillshare updatepath because the source is not a git repo — the only fix is to re-runskillshare install --force, which most users will not remember to do.The workaround is to manually delete the copy and create a symlink in the source directory pointing to the app bundle path — but this bypasses skillshare's metadata and requires direct edits to the source directory, which CONTRIBUTING.md explicitly discourages.
Proposed Solution
Add a
--linkflag toskillshare installfor local paths:Instead of copying the directory, skillshare places a symlink in the source tree:
The skill content always reflects the live app bundle. No manual re-install needed after app updates.
Other design points worth discussing in a proposal:
skillshare listshould display linked skills with a distinct indicator (e.g.→ /path/to/source) so users can see which skills are live-linked vs. copiedskillshare check/skillshare updateshould handle linked skills gracefully (skip or report "externally managed")skillshare uninstallshould remove the symlink without touching the target directoryskillshare doctorcould warn when a link target no longer existsWho Is Affected
Anyone who installs skills that are bundled and maintained by another application (e.g. Surge, or any CLI tool that ships its own skill file). Also useful for developers who author a skill in one repo and want it live-linked into their skillshare source without maintaining a copy.
Alternatives Considered
install --forceafter each app update — fragile, easy to forget, breaks the "install once" contract