Willie b0d87fba28 feat(sync): make prefixed target naming misconfigurations visible (#503)
* feat(sync): make prefixed target naming misconfigurations visible

Prefixed naming (#497) works, but several of its failure modes only showed up
at sync time or gave advice that cannot be followed:

- A collision that only prefixing creates told the user to "rename one in
  SKILL.md", which a tracked skill cannot do, and never said the prefix caused
  it. The hint now names the prefixing and points at renaming the other skill or
  re-tracking the repo with --name.
- `target add` silently wrote mode: copy when the inherited naming is prefixed.
  The CLI now says so.
- A target that resolves to prefixed outside copy mode was reported only by
  sync. status, doctor and target list (plain and JSON) now flag it, and the
  sync/validation and `--skills=true` errors say how to fix it.
- The dim "duplicate skill names (isolated by ...)" line printed on every sync
  even when nothing was wrong, and before a failing sync. Isolated duplicates
  are not a problem, so it is dropped; the website docs still showed an
  outdated form of this output and are corrected in all locales.

* fix(status): flag prefixed-outside-copy in the TUI list and status --json

Codex review of #503 found two surfaces the new check missed:

- The interactive `target list` (the default on a terminal) never read the
  item's naming error, so a prefixed + merge target looked healthy there. The
  list row now marks the mode with "!" and the detail panel shows the fix.
- `status --json` (global and project) builds its target entries directly, so
  scripts got no signal. Each target now carries a `warning` string, matching
  `target list --json`.

* docs(troubleshooting): sync no longer prints a message for isolated duplicates

The collision troubleshooting tip still said sync shows an info message when
filters isolate duplicate skill names. That line was dropped, so the tip now
says sync prints nothing about them. Codex review of #503 flagged the stale
English page and its four translations.

* fix(config): point managed-project naming errors at the project settings

The "set mode: copy on the target" hint is wrong for a target a global
`projects:` entry expands into: it cannot be edited with `target` or under
`targets:`, and the mode lives in the project's skills settings. The hint now
depends on whether the target belongs to a managed project (Codex review of
#503).

The naming/mode check becomes a TargetConfig method so status, doctor and
target list share it, which also lets the hint see the project root. Along the
way: doctor reuses it, the TUI list renders the mode once, and
reportTargetAdded takes a flag instead of comparing a mode string.

* fix(config): hint the project settings for managed-project naming errors

ProjectNamingError (the config-load check for a global `projects:` entry) still
returned the bare naming error, so a project that inherits prefixed with a
non-copy mode got no fix. It now names the project's skills settings, like the
expanded targets do. The built-in skill's sync reference also mentions that
status, doctor and target list flag the misconfiguration before sync.

Found by the second /code-review pass on #503.

* fix(sync): detect prefix collisions from the colliding paths

reportCollisions decided a collision came from prefixing when its name was not
also a duplicate in the source. A tracked skill that joined two ordinary
skills already sharing the name was therefore sent to the "rename one in
SKILL.md" hint, which a tracked skill cannot follow (Codex review of #503).

A collision on a prefixed target that includes a tracked path now gets the
tracked-skill hint, whatever else shares the name. The wording no longer claims
prefixing renamed the skill, since a name that already starts with the repo
name is unchanged.

* fix(sync): use discovered repo metadata for the tracked-skill hint

The collision hint treated any path segment starting with "_" as a tracked
repo, so an ordinary skill under a folder such as org/_drafts (no .git) was
told it could not be renamed and to re-track a repo that does not exist. It now
uses DiscoveredSkill.IsInRepo, the same signal prefixed naming uses.

The prefixed docs also gain the fix for a target a global `projects:` entry
expands into (projects.<root>.skills.mode: copy), since `target` cannot edit
those. Both from Codex review of #503.

* fix(sync): keep both collision hints when targets disagree

The same name can clash on a prefixed target with a tracked skill and on
another target between ordinary skills only. The prefixed flag was OR-ed across
targets, so the second case lost its rename/filter hint. Track both kinds
separately while grouping, and print each hint that applies (Codex review of
#503).

* fix(sync): keep the rename hint inside a mixed collision group

When a tracked skill and two ordinary skills share a prefixed name, re-tracking
the repo fixes only the tracked one; the ordinary pair still clashes and is
excluded. The group now also shows the rename/filter hint when at least two of
its participants are not tracked (Codex review of #503).

* fix(sync): offer filters in the tracked-skill collision hint

Two tracked skills of the same repo with the same name collide after
prefixing, and neither renaming a tracked skill nor re-tracking the repo
separates them. The hint now also names include/exclude filters, so every
collision on a prefixed target has an actionable remedy (Codex review of #503).

* docs(sync-modes): limit the target list claim to targets under targets

target list builds from the config without project expansion, so it cannot
flag a target a `projects:` entry expands into; status and doctor can. The
prefixed paragraph and the built-in skill reference said all three flag it
(Codex review of #503).
2026-10-10 00:00:23 +08:00
2026-10-08 08:37:55 +00:00
2026-10-02 03:46:48 +08:00
2026-09-25 02:32:37 +08:00
2026-01-14 18:09:36 +08:00
2026-09-25 02:32:37 +08:00

skillshare

skillshare

English · Deutsch · Español · Français · 日本語 · 한국어 · Português · 简体中文 · 繁體中文

Website License: MIT Release Downloads Platform Ask DeepWiki Support skillshare on Ko-fi

Star on GitHub

runkids%2Fskillshare | Trendshift

Your AI coding setup, everywhere.
Manage skills, agents, rules, MCP connections and hooks in one place.
For Claude Code, Codex, Pi, OpenCode and more.

Website • Install • Quick Start • Highlights • Screenshots • Desktop App • Docs

skillshare demo

Note

Latest: v0.25.0 — skillshare mcp serve serves your skills over MCP (the SEP-2640 Skills extension) to agents that can only reach an MCP endpoint, with list_skills and read_skill tools for clients without the extension, and the dashboard's Add server gets a Skillshare tab for it; skillshare link and unlink add or remove a folder kept elsewhere, such as your own checkout or an external drive, as a followed source link, also from the Skills page; and the Oh My Pi (omp) target gains MCP, code hooks, plugins and extension selection. All releases →

Why skillshare

Switching AI tools should not mean rebuilding your setup. skillshare gives your skills and other AI resources a home you control.

  • Switch tools, keep your skills — edit once, then sync to Claude Code, Codex, Pi and the other tools you use.
  • Take your setup with you — version your source in Git and pull it onto another machine.
  • Share with your team — keep project resources with your code and distribute shared skills through tracked repositories.

One teammate uses Claude Code, another uses Codex. Keep their shared code-review checklist in .skillshare/ alongside the project. New teammates install the declared skills and sync to the configured tools instead of copying instructions from chat. Team onboarding →

Use the desktop app or CLI to manage everything locally, audit skills before use, and choose what each tool receives.

Coming from another tool? Migration Guide · Comparison

CLI and UI Preview

Skill Detail Security Audit
CLI sync output CLI install with security audit
UI Dashboard UI Skills
Web dashboard overview Web UI skills page

Installation

Tip

Use skillshare from your desktop. Get Skillshare App for macOS (Apple Silicon), Windows and Linux. First launch helps you install or locate the CLI, choose your AI tools and run your first sync. Installation guide.

Desktop App — visual setup and daily management

Skillshare App puts skills, agents, MCP and hooks in a desktop window. Install the app, open it, and follow first-launch setup.

macOS (Apple Silicon), with Homebrew:

brew tap runkids/tap
brew install --cask skillshare-app

Windows / Linux, or a manual macOS install: Download the latest app installers. See the Desktop App guide for platform details.

CLI: macOS / Linux

curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh

The script installs to ~/.local/bin by default, so normal installs and updates do not need sudo. If the installer prints PATH setup instructions, follow them before running skillshare. Add the suggested line to your shell config (such as ~/.zshrc or ~/.bashrc) for future terminals. Set INSTALL_DIR to use another location.

Windows PowerShell

irm https://raw.githubusercontent.com/runkids/skillshare/main/install.ps1 | iex

CLI: Homebrew

brew install skillshare

Tip: Run skillshare upgrade to update to the latest version. It auto-detects your install method and handles the rest.

GitHub Actions

- uses: runkids/setup-skillshare@v1
  with:
    source: ./skills
- run: skillshare sync

See setup-skillshare for all options (audit, project mode, version pinning).

Shorthand (Optional)

Add an alias to your shell config (~/.zshrc or ~/.bashrc):

alias ss='skillshare'

Quick Start

skillshare init            # Create config, source, and detected targets
skillshare sync            # Sync skills to all targets

How It Works

  • macOS / Linux: ~/.config/skillshare/
  • Windows: %AppData%\skillshare\
┌─────────────────────────────────────────────────────────────┐
│                    Source Directory                         │
│   ~/.config/skillshare/skills/    ← skills (SKILL.md)       │
│   ~/.config/skillshare/agents/    ← agents                  │
│   ~/.config/skillshare/extras/    ← rules, commands, etc.   │
└─────────────────────────────────────────────────────────────┘
                              │ sync
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
       ┌───────────┐   ┌───────────┐   ┌───────────┐
       │  Claude   │   │  OpenCode │   │ OpenClaw  │   ...
       └───────────┘   └───────────┘   └───────────┘
Platform Skills Source Agents Source Extras Source Link Type
macOS/Linux ~/.config/skillshare/skills/ ~/.config/skillshare/agents/ ~/.config/skillshare/extras/ Symlinks
Windows %AppData%\skillshare\skills\ %AppData%\skillshare\agents\ %AppData%\skillshare\extras\ NTFS Junctions for folders (no admin required); file symlinks need Developer Mode, otherwise copied
Imperative (install-per-command) Declarative (skillshare)
Source of truth Skills copied independently Single source → symlinks (or copies)
New machine setup Re-run every install manually git clone config + sync
Security audit None Built-in audit + auto-scan on install/update
Web dashboard None skillshare ui
Runtime dependency Node.js + npm None (single Go binary)

Full comparison →

Highlights

Install & update skills —from GitHub, GitLab, or any Git host

skillshare install github.com/reponame/skills
skillshare update --all
skillshare target claude --mode copy  # if symlinks don't work

Symlink issues? — switch to copy mode per target

skillshare target <name> --mode copy
skillshare sync

Security audit —scan before skills reach your agent

skillshare audit

Project skills —per-repo, committed with your code

skillshare init -p && skillshare sync

Agents —sync custom agents to agent-capable targets

skillshare sync agents            # sync agents only
skillshare sync --all             # sync skills + agents + extras + MCP + hooks together

Extras —manage rules, commands, prompts & more

skillshare extras init rules          # create a "rules" extra
skillshare sync --all                 # sync skills + agents + extras + MCP + hooks together
skillshare extras collect rules       # collect local files back to source

MCP connections —configure once for Claude Code, Codex, Pi, VS Code, OpenCode and more

skillshare mcp add                    # guided URL or JSON setup
skillshare sync mcp --dry-run         # preview native configuration changes
skillshare sync mcp                   # apply connection settings

Keep definitions in config.yaml or reference a separate mcp.yaml. See MCP setup for examples, environment references and importing existing connections.

Manage native hooks without executing them:

skillshare hooks add check --file ./check.yaml
skillshare hooks sync --dry-run
skillshare hooks sync

Plugins —install a complete plugin and pick which tools receive it

skillshare plugin add                 # guided: source, plugin, targets, review
skillshare plugin add owner/repo --target claude --target codex --no-tui
skillshare sync plugins --dry-run     # plugins sync separately from sync --all

Existing native installations can be adopted with plugin import. See Manage plugins across tools.

Shell completion —tab-complete commands, flags, and subcommands

skillshare completion bash --install   # also: zsh, fish, powershell, nushell

Local checkpoints — commit source changes without pushing

skillshare commit -m "Update review skill"
skillshare commit --dry-run

Web dashboard — visual control panel

skillshare ui

All commands & guides →

Contributing

Contributions welcome! Open an issue first, then submit a draft PR with tests. See CONTRIBUTING.md for setup details.

git clone https://github.com/runkids/skillshare.git && cd skillshare
make check  # format + lint + test

Tip

Not sure where to start? Browse open issues or try the Playground for a zero-setup dev environment.

Contributors

Thanks to everyone who helped shape skillshare.

leeeezx Vergil333 romanr xocasdashdash philippe-granet terranc benrfairless nerveband EarthChen gdm257 skovtunenko TyceHerrman 1am2syman thealokkr JasonLandbridge masonc15 richardwhatever reneleonhardt ndeybach hhh2210 leoarry salmonumbrella daylamtayari dstotijn ipruning massukio kevincobain2000 StephenPAdams mk-imagine Curtion amdoi7 jessica-engel AlimuratYusup thor-shuang bishopmatthew chaosky iFwu ildunari aestilog xarthurx m0cun bit3125 eekryuos Bongseop-Kim sophodex PeterTianbuhan dotned ismferd jblackburn21 jnhu76 jacobleft rhysmcneill druellan 12britz askpatrickw Almost42 Brett-Best isCopyman svob michal-grzelak shikbupt LeoYeAI TIR44 Ajaymamtora vishaldialpad kankan0829 dnabb thinhngotony skaurus jamesbraza 2BAB zdlldz elstiaan FaintFlower yantinglin21 chung1912 r-fynn cescox hhdebb Snurppa s0undt3ch danscheer 7zq12lvm-b DarkiT harisonw wuhaoyujerry star-nebula AdamMagued mbury 483218131


Support skillshare ❤️

skillshare is free and open source.

If skillshare saves you time, consider buying me a coffee. Every contribution helps with ongoing development, cross-platform testing, documentation, and maintenance.

☕ Buy me a coffee

You can also help by giving skillshare a ⭐ on GitHub!

Star History

Star History Chart


License

MIT

Languages
Go 73.7%
TypeScript 20.2%
JavaScript 3%
Shell 1.4%
CSS 0.9%
Other 0.7%