Files
skillshare/ai_docs/tests/universal_target_path_runbook.md
T
Willie fe244e8289 refactor(sync): simplify shouldUseRelative and hoist extras computation
- Use utils.PathHasPrefix/PathsEqual for Windows case-insensitivity
- Eliminate redundant filepath.Clean call
- Hoist shouldUseRelative in syncExtraPerFile (compute once, pass bool)
- Add invariant comment in SyncTargetMergeWithSkills
2026-04-07 17:26:37 +08:00

3.7 KiB

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)
  • Setup hook handles ss init -g
  • 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

grep -A4 'name: universal' /workspace/internal/config/targets.yaml

Expected:

  • exit_code: 0
  • ~/.agents/skills
  • .agents/skills

Step 2: Install skills globally via npx skills

npx -y skills@latest add runkids/feature-radar -g --all

Expected:

  • exit_code: 0
  • .agents/skills
  • Not .config/agents/skills

Step 3: Verify skills installed to ~/.agents/skills

ls -la ~/.agents/skills/

Expected:

  • exit_code: 0
  • feature-radar

Step 4: Verify ~/.config/agents/skills was NOT created

CMD_EXIT=0; ls ~/.config/agents/skills/ 2>&1 || CMD_EXIT=$?; echo "EXIT=$CMD_EXIT"

Expected:

  • EXIT=2

Step 5: Verify npx skills list sees the skills

npx -y skills@latest list -g

Expected:

  • exit_code: 0
  • .agents/skills
ls -la ~/.claude/skills/ 2>/dev/null || true

Expected:

  • exit_code: 0
  • .agents/skills

Step 7: Verify skillshare init auto-includes universal

Note: Setup hook already ran init. Remove existing config to test fresh init.

rm -rf ~/.config/skillshare
ss init --no-copy --all-targets --no-git --no-skill
cat ~/.config/skillshare/config.yaml

Expected:

  • exit_code: 0
  • universal
  • .agents/skills

Step 8: Verify skillshare sync creates universal target directory

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:

  • exit_code: 0
  • test-skill

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.

cat ~/.claude/skills/test-skill/SKILL.md
cat ~/.agents/skills/test-skill/SKILL.md

Expected:

  • exit_code: 0
  • Test

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.