mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-18 18:04:17 +00:00
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:
+3
-2
@@ -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.
|
||||
@@ -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)",
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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 (`~/.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:
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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 (`"."`)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user