dsh-skills-nexus

LIMITATIONS

Known limitations

- **`add` then visibility**: newly added skills appear after DSH rescans `~/.dsh/skills/`. If the profile was already running, reload it — the official filesystem provider will rescan the skills root and pick up newly created symlinks. - **Version pinning & updates**: pin a ref with `#branch`, `#tag`, or `#commit-sha`. At install time the manifest records the exact resolved commit (`commit`) — a lightweight lock that `list` shows. `update` only fast-forwards **branch**-pinned skills (printing the commit change); **tag/commit**-pinned skills are fixed points: it verifies the checkout still matches the pin (and restores it if it drifted) instead of pulling, so a pinned version never silently drifts. When no `#ref` is given, the CLI detects the remote's default branch via `git ls-remote --symref` (falls back to `main`). - **Skill content repos only**: this is *not* a replacement for `dsh plugin add` of real Cordis plugins. If a repo already ships a `dsh.bundle.patch`, install it the normal way — nexus is for repos that don't. See [nexus vs `dsh plugin`](docs/nexus-vs-plugin.md) for the full decision guide. - **Collection repos & `--subdir`**: collection repos (skills nested under subdirectories, e.g. `trae-community/trae-skills`) are installed piecemeal with `--subdir <path>` — each install is its own entry with its own clone (independent-clone design, see [docs/subdir-design.md](docs/subdir-design.md) for the P1/P2 trade-off). Installing the whole repo without `--subdir` is guarded by a confirmation prompt above 20 skills. Entries cherry-picked from the same repo each keep their own clone, but `list` shows a **SOURCE** column (the origin `owner/repo`) so same-origin entries are easy to spot. - **Flat-markdown filter**: a flat `*.md` file without frontmatter `name` AND `description` is not treated as a skill — collection-repo docs like `README.zh-CN.md`, `CONTRIBUTING.md` or `community-leaderboard.md` are never "fake-installed". Doc-like names (`readme*`, `contributing*`, `license*`, `changelog*`, `code-of-conduct*`, `security*`) are skipped at discovery. - **Name collisions**: DSH indexes skills by name; a later install with the same name overwrites. Use `--name` to distinguish entries, or `--subdir` to install only what you need. enable/disable work per entry, `remove` deletes the whole entry's clone and all its symlinks. - **Skill name validation**: DSH requires lowercase kebab-case skill names (`[a-z0-9]+` segments separated by single `-`). nexus normalizes invalid frontmatter names at `add` time (converted to kebab-case) and warns with `⚠`. - **Build scripts**: because nexus clones content repos itself (not via pnpm), it sidesteps pnpm `allowBuilds` interception entirely. - **Windows links**: nexus creates directory junctions on Windows (`symlink(..., 'junction')`) and plain directory symlinks elsewhere — neither needs Developer Mode or admin privileges.