build-agent installer: npx skills add reports symlink → Claude Code on success but never creates .claude/skills/

[bekossy]

Summary

npx skills add Agenta-AI/agenta-skills reports symlink → Claude Code as part of a successful install, but the .claude/skills/ directory is never actually created. Claude Code sessions cannot find the skill until the symlink is created manually.

Tested against: Agenta host https://bighetzner.agenta.dev, workspace mahmoud/Default.

---

Repro

1. Run npx skills add Agenta-AI/agenta-skills in a fresh project directory.
2. Installer output reports symlink → Claude Code as part of a successful install (exit 0).
3. Inspect the target directory — no .claude/ directory exists (confirmed via ls and readlink).
4. Start a Claude Code session and attempt to use the skill:

   "There's no 'build-agent' skill available in this session"

5. Manually run the workaround:

   mkdir -p .claude/skills
   ln -s ../../.agents/skills/build-agent .claude/skills/build-agent

6. After this, the skill loads correctly in Claude Code.

---

Manual workaround

mkdir -p .claude/skills
ln -s ../../.agents/skills/build-agent .claude/skills/build-agent

---

Required fix

The installer must verify the symlink was actually created (e.g. via readlink -f or ls -la) before reporting success. If creation fails, it should either retry, fall back, or surface a clear actionable error — not silently report success with a false status line.

---

Environment

Agenta host	https://bighetzner.agenta.dev
Workspace	mahmoud/Default
Skill version	build-agent from Agenta-AI/agenta-skills (current main)

[bekossy]

Root cause found — this is not a bug in agenta-skills at all. It's an upstream bug in the npx skills installer itself (vercel-labs/skills), already tracked there as #1138 (open since 2026-06-10, with several duplicates: #1355, #851, #744, #693).

What's actually happening: for a project-local install, if the target agent's config directory doesn't already exist in the project (e.g. no .claude/ yet), the installer intentionally skips creating that agent's symlink — to avoid cluttering fresh projects with config dirs for agents not in use. But the pre-install confirmation still shows symlink → Claude Code, and the post-install result summary silently drops the skipped agent with no warning. So the CLI reports a clean success while Claude Code (or any similarly-configured agent) never actually gets the skill.

Status: there's already a ready, tested fix sitting unreviewed upstream — PR #1405 — which makes the skip visible in both summaries without changing the underlying skip decision. We added an independent reproduction as a comment on #1138 to help get it prioritized.

Workaround until it merges: mkdir .claude before running npx skills add, or manually symlink afterward:

mkdir -p .claude/skills && ln -s ../../.agents/skills/<skill-name> .claude/skills/<skill-name>

Recommend closing this as "upstream, tracked" rather than carrying it as an open agenta-skills bug — nothing to fix on our side, it's a matter of vercel-labs merging their own pending PR.