Link installed skills into Claude Code and fix the post-install command hint

[vshulman]

Reported and scoped in internal discussion; opened from a fork (no write access to this repo).

Problem

Wrong folder. parallel-cli skills install writes to ~/.agents/skills — the emerging cross-agent location, read by Gemini CLI, Copilot, Codex and Amp. Claude Code only scans ~/.claude/skills (and <project>/.claude/skills) and never looks there. The install reports success and nothing shows up in Claude Code.

Wrong command. The post-install output echoed raw skill names without saying how to invoke them, and users following the plugin docs reach for /parallel:parallel-web-search, which only exists via the marketplace plugin. The CLI ships loose skills, so the real command is the un-namespaced folder name, e.g. /parallel-web-search.

Fix

~/.agents/skills stays the canonical install location — it isn't a mistake, it's a bet on the cross-agent convention, and Claude Code is the holdout. No spec mandates a shared directory (the Agent Skills standard covers the file format only), so the installer now bridges the gap:

• After installing, link_into_claude_code() symlinks each skill into ~/.claude/skills (or <project>/.claude/skills) when a .claude directory is present. Claude Code follows symlinks, so one canonical copy serves every agent — nothing to keep in sync.
• Falls back to copying the folder where os.symlink raises (Windows without the symlink privilege).
• Never clobbers. A pre-existing real file/dir of the same name is left alone and reported. A correct existing link is a no-op, so re-running is idempotent. If ~/.claude/skills is itself already a symlink to the install dir (the manual workaround some of us applied), it's detected and left as-is rather than nesting links inside it.
• Best-effort. The whole step is wrapped so any failure only warns — it can never break the primary .agents/skills install.
• uninstall removes the links it created, and install prunes links whose target a narrower --skill set removed, so no dead slash commands linger. Only dangling symlinks pointing into the install dir are pruned; foreign links and hand-written skills are untouched.

Install/reinstall output now prints Skill commands: /parallel-web-search, … plus a restart hint, and --json gains a claude_code block reporting what was linked, copied, skipped or pruned.

Docs: new Agent Skills README section covering install locations, the Claude Code linking behavior, and the loose-skill vs. plugin command distinction (/parallel-web-search vs /parallel:parallel-web-search). The CLI overview tree was also missing the skills group entirely — added.

Verification

• uv run pytest -q → 798 passed. 20 new tests: symlink creation, home vs. project root, idempotency, stale-link refresh, don't-clobber, whole-dir-symlink detection, copy fallback, copy-fallback failure, prune vs. foreign-link safety, and uninstall cleanup.
• ruff check / ruff format / tach check / ty check all clean.
• Manual end-to-end against the live skills.parallel.ai index in a sandboxed HOME: global install links all 10 skills; a hand-written parallel-findall skill and an unrelated file survive untouched; narrowing to --skill parallel-web-search prunes the other 9 links; uninstall leaves only the user's own files; --project links into the project .claude/skills; and a pre-existing whole-dir symlink is detected and skipped.

Note for a follow-up

The live index currently advertises two skills named result and status, which install as /result and /status — very generic commands to inject into a user's agent. Looks like index pollution rather than intended skills; not touched here.