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
This commit is contained in:
Willie
2026-02-28 03:44:02 +08:00
parent 1a207e6d2c
commit 5d9a77372d
7 changed files with 183 additions and 7 deletions
+3 -2
View File
@@ -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 (`"."`)
@@ -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.
+5 -3
View File
@@ -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)",
})
}
}
+1
View File
@@ -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)
@@ -129,6 +129,12 @@ These are auto-detected during `skillshare init`:
</tbody>
</table>
:::info Universal target
The **universal** target (`&#126;/.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:
+29
View File
@@ -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:
+3 -2
View File
@@ -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 (`"."`)