From 5d9a77372dbdcf02ed630403f27d42087fbeb341 Mon Sep 17 00:00:00 2001 From: Willie Date: Fri, 27 Feb 2026 23:23:34 +0800 Subject: [PATCH] feat(init): label universal as shared agent directory and add coexistence docs - Change universal description from "(recommended)" to "(shared agent directory)" in detect, checklist, and discover flows - Add FAQ section on using universal alongside npx skills: merge vs copy mode differences, name collision caveats, lock file visibility - Add universal info admonition to supported-targets page - Add E2E runbook for universal target path verification - Update CHANGELOG and release notes for v0.16.4 --- CHANGELOG.md | 5 +- .../tests/universal_target_path_runbook.md | 136 ++++++++++++++++++ cmd/skillshare/init.go | 8 +- tests/integration/init_test.go | 1 + .../reference/targets/supported-targets.md | 6 + website/docs/troubleshooting/faq.md | 29 ++++ website/src/pages/changelog.md | 5 +- 7 files changed, 183 insertions(+), 7 deletions(-) create mode 100644 ai_docs/tests/universal_target_path_runbook.md diff --git a/CHANGELOG.md b/CHANGELOG.md index dc5e6d303..c67c7d104 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,8 +21,9 @@ ### Fixed -- **`universal` target path** — corrected global path from `~/.config/agents/skills` to `~/.agents/skills` so that `npx skills list` picks up synced skills -- **`init` auto-includes `universal`** — `init` and `init --discover` now automatically recommend the `universal` target whenever any AI CLI is detected, since `~/.agents/` doesn't exist on disk until skillshare creates it +- **`universal` target path** — corrected global path from `~/.config/agents/skills` to `~/.agents/skills` (the shared agent directory used by multiple AI CLIs) +- **`init` auto-includes `universal`** — `init` and `init --discover` now automatically include the `universal` target whenever any AI CLI is detected; labeled as "shared agent directory" so users understand what it is +- **`universal` coexistence docs** — added FAQ section explaining how skillshare and `npx skills` coexist on the same `~/.agents/skills` path, including sync mode differences and name collision caveats - **`--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 (`"."`) diff --git a/ai_docs/tests/universal_target_path_runbook.md b/ai_docs/tests/universal_target_path_runbook.md new file mode 100644 index 000000000..6a9e4d847 --- /dev/null +++ b/ai_docs/tests/universal_target_path_runbook.md @@ -0,0 +1,136 @@ +# Universal Target Path Verification + +Verify that the `universal` target path in `targets.yaml` matches the actual runtime path used by `npx skills` (vercel-labs/skills). + +## Scope + +- `internal/config/targets.yaml` — universal global_path +- `cmd/skillshare/init.go` — universal auto-injection in `detectCLIDirectories()` and `detectNewAgents()` +- Cross-validation with upstream `npx skills` CLI behavior + +## Environment + +- Devcontainer with network access (needs npm registry) +- `ssenv` isolated HOME +- Node.js / npm available in container +- A public GitHub repo with skills (e.g., `runkids/feature-radar`) + +## Steps + +### Step 1: Verify targets.yaml universal path + +```bash +grep -A4 'global_name: universal' /workspace/internal/config/targets.yaml +``` + +**Expected:** +- `global_path` is `~/.agents/skills` +- `project_path` is `.agents/skills` + +### Step 2: Install skills globally via npx skills + +```bash +npx -y skills@latest add runkids/feature-radar -g --all +``` + +**Expected:** +- Command succeeds (exit 0) +- Output mentions installing to `~/.agents/skills/` (not `~/.config/agents/skills/`) + +### Step 3: Verify skills installed to ~/.agents/skills + +```bash +ls -la ~/.agents/skills/ +``` + +**Expected:** +- Directory exists and contains installed skill directories +- Each skill has a `SKILL.md` file + +### Step 4: Verify ~/.config/agents/skills was NOT created + +```bash +ls ~/.config/agents/skills/ 2>&1 +``` + +**Expected:** +- Directory does not exist or is empty +- Error message like "No such file or directory" + +### Step 5: Verify npx skills list sees the skills + +```bash +npx -y skills@latest list -g +``` + +**Expected:** +- Lists all installed skills +- Shows path as `~/.agents/skills/` +- Output includes "universal:" line listing covered agents (Amp, Cline, Codex, Cursor, etc.) + +### Step 6: Verify symlinks to agent-specific directories + +```bash +ls -la ~/.claude/skills/ 2>/dev/null +ls -la ~/.cursor/skills/ 2>/dev/null +``` + +**Expected:** +- Agent-specific directories contain symlinks pointing back to `../../.agents/skills/` +- Symlinks are valid (not broken) + +### Step 7: Verify skillshare init auto-includes universal + +Note: `ssenv create --init` already ran init. Remove existing config to test fresh init. + +```bash +rm -rf ~/.config/skillshare +ss init --no-copy --all-targets --no-git --no-skill +cat ~/.config/skillshare/config.yaml +``` + +**Expected:** +- Config contains `universal:` target entry +- Universal target path resolves to `~/.agents/skills` + +### Step 8: Verify skillshare sync creates universal target directory + +```bash +mkdir -p ~/.config/skillshare/skills/test-skill +echo '---' > ~/.config/skillshare/skills/test-skill/SKILL.md +echo 'name: test-skill' >> ~/.config/skillshare/skills/test-skill/SKILL.md +echo '---' >> ~/.config/skillshare/skills/test-skill/SKILL.md +echo '# Test' >> ~/.config/skillshare/skills/test-skill/SKILL.md +ss sync +ls -la ~/.agents/skills/ +``` + +**Expected:** +- `~/.agents/skills/` directory created by sync +- Contains symlink `test-skill` → source directory + +### Step 9: Verify agent CLI can read skillshare-synced skill + +`npx skills list -g` uses a lock file (`~/.agents/.skill-lock.json`), not directory scanning. So it will NOT show skills placed by skillshare. Instead, verify the agent directories directly. + +```bash +cat ~/.claude/skills/test-skill/SKILL.md +cat ~/.agents/skills/test-skill/SKILL.md +``` + +**Expected:** +- Both paths resolve to the SKILL.md content ("# Test Skill") +- Confirms round-trip: skillshare sync → universal path + agent path → readable by agent CLI + +## Pass Criteria + +- All 9 steps pass +- Confirmed: `~/.agents/skills` is the canonical global path for universal target +- Confirmed: `~/.config/agents/skills` is NOT used by runtime `npx skills` +- Confirmed: skillshare sync to universal target is readable by agent CLIs via symlinks + +## Notes + +- vercel-labs/skills source code references `{configHome}/agents/skills` which suggests `~/.config/agents/skills`, but actual runtime behavior uses `~/.agents/skills`. This discrepancy was the root cause of Issue #54. +- The `npx skills add -g` command also creates symlinks from agent-specific directories (claude, cursor, etc.) back to `~/.agents/skills/`, which is the "universal" shared directory. +- `npx skills list -g` only shows skills tracked in `~/.agents/.skill-lock.json` (installed via `npx skills add`). Skills placed by external tools (like skillshare) won't appear in `npx skills list` but ARE visible to agent CLIs that read the directory. diff --git a/cmd/skillshare/init.go b/cmd/skillshare/init.go index cdccadc50..bffa0e71a 100644 --- a/cmd/skillshare/init.go +++ b/cmd/skillshare/init.go @@ -629,7 +629,7 @@ func detectCLIDirectories(home string) []detectedDir { detected = append(detected, detectedDir{ name: "universal", path: target.Path, }) - ui.Info("Found: %-12s %s (recommended)", "universal", target.Path) + ui.Info("Found: %-12s %s (shared agent directory)", "universal", target.Path) } } } @@ -804,7 +804,9 @@ func buildTargetsList(detected []detectedDir, copyFrom, copyFromName, targetsArg items := make([]checklistItemData, len(detected)) for i, d := range detected { status := "" - if d.exists { + if d.name == "universal" { + status = "(shared agent directory)" + } else if d.exists { if d.skillCount > 0 { status = fmt.Sprintf("(%d skills)", d.skillCount) } else { @@ -1362,7 +1364,7 @@ func detectNewAgents(existingCfg *config.Config) []agentInfo { newAgents = append(newAgents, agentInfo{ name: "universal", path: target.Path, - description: "(recommended)", + description: "(shared agent directory)", }) } } diff --git a/tests/integration/init_test.go b/tests/integration/init_test.go index 1d94c94d0..33f0363b8 100644 --- a/tests/integration/init_test.go +++ b/tests/integration/init_test.go @@ -521,6 +521,7 @@ func TestInit_UniversalAutoDetected(t *testing.T) { result := sb.RunCLI("init", "--no-copy", "--all-targets", "--no-git", "--no-skill") result.AssertSuccess(t) + result.AssertAnyOutputContains(t, "shared agent directory") // Verify config includes universal pointing to ~/.agents/skills configContent := sb.ReadFile(sb.ConfigPath) diff --git a/website/docs/reference/targets/supported-targets.md b/website/docs/reference/targets/supported-targets.md index c9eeb7c7a..7c4b68218 100644 --- a/website/docs/reference/targets/supported-targets.md +++ b/website/docs/reference/targets/supported-targets.md @@ -129,6 +129,12 @@ These are auto-detected during `skillshare init`: +:::info Universal target +The **universal** target (`~/.agents/skills`) is a shared agent directory that multiple AI CLIs can read from. It is auto-detected during `skillshare init` when any other agent is found. In project mode, `amp`, `codex`, `kimi`, and `replit` share the same `.agents/skills` path and are grouped under `universal` automatically. + +This is the same path used by the [npx skills CLI](https://github.com/vercel-labs/skills). See [FAQ: Using universal alongside npx skills](/docs/troubleshooting/faq#using-universal-alongside-npx-skills) for coexistence details. +::: + ## Aliases Some targets have alternative names for backward compatibility or convenience: diff --git a/website/docs/troubleshooting/faq.md b/website/docs/troubleshooting/faq.md index af5e57c7f..fc6a1e758 100644 --- a/website/docs/troubleshooting/faq.md +++ b/website/docs/troubleshooting/faq.md @@ -182,6 +182,35 @@ Both approaches can be combined — config filters are applied first, then the s ## Targets +### Using universal alongside npx skills + +The `universal` target points to `~/.agents/skills`, the same directory used by the [npx skills CLI](https://github.com/vercel-labs/skills). Both tools can manage this directory simultaneously with some caveats: + +**What works:** +- In merge mode (default), skillshare creates **symlinks** in `~/.agents/skills/`; npx skills creates **real directories**. They coexist as long as skill names don't collide. +- skillshare's prune logic only removes entries it manages — it won't delete files installed by npx skills. +- Agent CLIs (Claude Code, Cursor, etc.) read directories directly, so they see skills from both tools. + +**What to watch out for:** +- **Name collision** — If both tools install a skill with the same name, the last sync/install wins. Avoid installing the same skill through both tools. +- **Copy mode is more aggressive** — In copy mode (`skillshare target universal --mode copy`), skillshare overwrites managed directories on every sync. If npx skills modifies a same-named skill between syncs, skillshare will replace it. Merge mode (default) only creates symlinks, which is safer for coexistence. +- **`npx skills list` won't show skillshare skills** — The npx skills CLI tracks installs via a lock file (`~/.agents/.skill-lock.json`), not by scanning the directory. Skills synced by skillshare won't appear in `npx skills list -g`, but they **are** visible to agent CLIs. +- **Other agent-specific targets still useful** — `universal` and `claude` point to different paths (`~/.agents/skills` vs `~/.claude/skills`). Selecting both is safe and not redundant. + +**Recommended workflow:** +```bash +# Use skillshare as your primary skill manager +skillshare install github.com/user/skills --track +skillshare sync + +# Use npx skills only for one-off community installs you don't need to sync +npx skills add someone/skill -g +``` + +:::tip +Keep the universal target in **merge mode** (default) for the safest coexistence with npx skills. Avoid switching to copy mode unless you don't use npx skills at all. +::: + ### I used `claude-code` (or `gemini-cli`, etc.) as a project target — is that still valid? Yes. Old project target names like `claude-code`, `gemini-cli`, `github-copilot` still resolve via aliases. However, the canonical name is now the same as the global name (e.g., `claude`, `gemini`, `copilot`). We recommend updating your `.skillshare/config.yaml` to use the short name: diff --git a/website/src/pages/changelog.md b/website/src/pages/changelog.md index eae2bf8cc..60b3503b4 100644 --- a/website/src/pages/changelog.md +++ b/website/src/pages/changelog.md @@ -30,8 +30,9 @@ All notable changes to skillshare are documented here. For the full commit histo ### Fixed -- **`universal` target path** — corrected global path from `~/.config/agents/skills` to `~/.agents/skills` so that `npx skills list` picks up synced skills -- **`init` auto-includes `universal`** — `init` and `init --discover` now automatically recommend the `universal` target whenever any AI CLI is detected, since `~/.agents/` doesn't exist on disk until skillshare creates it +- **`universal` target path** — corrected global path from `~/.config/agents/skills` to `~/.agents/skills` (the shared agent directory used by multiple AI CLIs) +- **`init` auto-includes `universal`** — `init` and `init --discover` now automatically include the `universal` target whenever any AI CLI is detected; labeled as "shared agent directory" so users understand what it is +- **`universal` coexistence docs** — added FAQ section explaining how skillshare and `npx skills` coexist on the same `~/.agents/skills` path, including sync mode differences and name collision caveats - **`--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 (`"."`)