From 1c84866eebcfba7370e249c364bdd7c1f7d739ca Mon Sep 17 00:00:00 2001 From: Willie Date: Fri, 27 Feb 2026 20:39:34 +0800 Subject: [PATCH] docs: add install duplicate detection docs and v0.16.4 changelog - Add Duplicate Detection section to install.md (same-repo skip, cross-path detection, conflict with different repo) - Update --force flag description to mention dedup override - Add v0.16.4 changelog entry to CHANGELOG.md and website --- CHANGELOG.md | 24 +++++++++++ website/docs/reference/commands/install.md | 48 +++++++++++++++++++++- website/src/pages/changelog.md | 24 +++++++++++ 3 files changed, 95 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f5fe8189c..bd55d45ce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,29 @@ # Changelog +## [0.16.4] - 2026-02-27 + +### New Features + +- **Cross-path duplicate detection** — `install` now detects when a repo is already installed at a different location and blocks the operation with a clear hint: + ```bash + skillshare install runkids/feature-radar --into feature-radar + # later... + skillshare install runkids/feature-radar + # ✗ this repo is already installed at skills/feature-radar/scan (and 2 more) + # Use 'skillshare update' to refresh, or reinstall with --force to allow duplicates + ``` +- **Same-repo skip** — reinstalling a skill from the same repo now shows a friendly `⊘ skipped` indicator instead of an error; skipped skills are grouped by directory with repo label in the summary +- **Web UI install dedup** — the Web UI install endpoints enforce the same cross-path duplicate check as the CLI, returning HTTP 409 when duplicates are found + +### Fixed + +- **`--force` hint accuracy** — the force hint now uses the actual repo URL (not per-skill subpath) and includes `--into` when applicable +- **`update` root-level skills** — root-level skill repos (SKILL.md at repo root) no longer appear as stale/deleted during batch update; fixed `Subdir` normalization mismatch between metadata (`""`) and discovery (`"."`) + +### Improvements + +- **`update` batch summary** — batch update summary now uses the same single-line stats format as `sync` with color-coded counts + ## [0.16.3] - 2026-02-27 ### Improvements diff --git a/website/docs/reference/commands/install.md b/website/docs/reference/commands/install.md index 9c05472e1..d795a95b3 100644 --- a/website/docs/reference/commands/install.md +++ b/website/docs/reference/commands/install.md @@ -241,7 +241,7 @@ See [Project Setup](/docs/how-to/sharing/project-setup) for the full guide. |------|-------|-------------| | `--name ` | | Override installed name when exactly one skill is installed | | `--into ` | | Install into subdirectory (e.g. `--into frontend` or `--into frontend/react`) | -| `--force` | `-f` | Overwrite existing skill; also override audit blocking | +| `--force` | `-f` | Overwrite existing skill; override audit blocking and cross-path duplicate check | | `--update` | `-u` | Update if exists (git pull or reinstall) | | `--track` | `-t` | Keep `.git` for tracked repos | | `--skill` | `-s` | Select specific skills from multi-skill repo (comma-separated) | @@ -255,6 +255,52 @@ See [Project Setup](/docs/how-to/sharing/project-setup) for the full guide. | `--global` | `-g` | Install into global `~/.config/skillshare/skills/` | | `--dry-run` | `-n` | Preview only | +## Duplicate Detection + +skillshare automatically detects when you're about to install something that already exists: + +### Same-repo reinstall + +If a skill already exists and was installed from the **same repo**, skillshare skips it with a warning instead of failing: + +```bash +skillshare install anthropics/skills/skills/pdf +# ✓ Installed pdf + +skillshare install anthropics/skills/skills/pdf +# ⊘ pdf — already installed from same repo +``` + +Use `--update` to refresh, or `--force` to overwrite. + +### Cross-path duplicate + +If a repo is already installed at one location and you try to install it at a **different** location, skillshare blocks the operation: + +```bash +# First install (into a subdirectory) +skillshare install runkids/feature-radar --into feature-radar + +# Later, forget about the first install +skillshare install runkids/feature-radar +# ✗ this repo is already installed at skills/feature-radar/scan (and 2 more) +# Use 'skillshare update' to refresh, or reinstall with --force to allow duplicates +``` + +This prevents accidental duplicates across different paths. Use `--force` to allow it intentionally. + +### Conflict with different repo + +If the destination directory exists but was installed from a **different** repo, the error message includes the original source: + +```bash +skillshare install owner/repo-b --name my-skill +# ✗ my-skill already exists (installed from https://github.com/owner/repo-a.git). +# To overwrite: skillshare install owner/repo-b --name my-skill --force +``` + +The `--force` hint always includes the correct flags (including `--into` if applicable). + ## Common Scenarios **Install with custom name:** diff --git a/website/src/pages/changelog.md b/website/src/pages/changelog.md index cab315b2c..cb62b4290 100644 --- a/website/src/pages/changelog.md +++ b/website/src/pages/changelog.md @@ -9,6 +9,30 @@ All notable changes to skillshare are documented here. For the full commit histo --- +## [0.16.4] - 2026-02-27 + +### New Features + +- **Cross-path duplicate detection** — `install` now detects when a repo is already installed at a different location and blocks the operation with a clear hint: + ```bash + skillshare install runkids/feature-radar --into feature-radar + # later... + skillshare install runkids/feature-radar + # ✗ this repo is already installed at skills/feature-radar/scan (and 2 more) + # Use 'skillshare update' to refresh, or reinstall with --force to allow duplicates + ``` +- **Same-repo skip** — reinstalling a skill from the same repo now shows a friendly `⊘ skipped` indicator instead of an error; skipped skills are grouped by directory with repo label in the summary +- **Web UI install dedup** — the Web UI install endpoints enforce the same cross-path duplicate check as the CLI, returning HTTP 409 when duplicates are found + +### Fixed + +- **`--force` hint accuracy** — the force hint now uses the actual repo URL (not per-skill subpath) and includes `--into` when applicable +- **`update` root-level skills** — root-level skill repos (SKILL.md at repo root) no longer appear as stale/deleted during batch update; fixed `Subdir` normalization mismatch between metadata (`""`) and discovery (`"."`) + +### Improvements + +- **`update` batch summary** — batch update summary now uses the same single-line stats format as `sync` with color-coded counts + ## [0.16.3] - 2026-02-27 ### Improvements