Running `npx skills add` at the repo root replaces the tracked skills/ source tree with symlinks and breaks lint

[jliu-ts]

Summary

Running the public installer inside this repo destroys its own source tree and then breaks bun run lint. npx skills add heygen-com/hyperframes at the repo root replaces all 20 tracked skills/<name>/ directories with symlinks into .agents/skills/<name>/, and fills .agents/skills/ with 20 skills that do not belong there. Git reports 914 tracked files as deleted.

Separate from #3861, which is about the metadata.internal gate: same command, different failure.

Reproduction

git clone https://github.com/heygen-com/hyperframes && cd hyperframes
git status --porcelain | wc -l          # 0
bun run lint                            # exit 0
npx skills add heygen-com/hyperframes --all
git status --porcelain | wc -l          # 935
bun run lint                            # exit 1

Observed

$ git status --porcelain | awk '{print $1}' | sort | uniq -c
  21 ??
 914 D

$ ls -ld skills/embedded-captions
lrwxr-xr-x  1 user  staff  35 skills/embedded-captions -> ../.agents/skills/embedded-captions

The six repo-native skills under .claude/skills/ survive as real directories, so the damage is confined to the marketplace source under skills/ and to the mirror. Three distinct effects:

1. The marketplace source is replaced by symlinks. All 20 entries under skills/ become links into ../.agents/skills/<same-name>: embedded-captions, faceless-explainer, figma, general-video, hyperframes, hyperframes-animation, hyperframes-audio, hyperframes-cli, hyperframes-core, hyperframes-creative, hyperframes-keyframes, hyperframes-registry, media-use, motion-graphics, music-to-video, pr-to-video, product-launch-video, remotion-to-hyperframes, slideshow, talking-head-recut.

2. The skill mirror check fails, so the build gate fails. .agents/skills/ is meant to be a byte-identical copy of .claude/skills/, which is the six repo-native skills plus a README, and scripts/check-skill-mirror.mjs enforces that. After the install it holds 27 entries. bun run lint exits 1:

only in .agents/skills/: talking-head-recut/references/styles/whiteboard.html
only in .agents/skills/: talking-head-recut/references/styles/xhs.html
Rebuild the mirror: cp -r .claude/skills/. .agents/skills/  (or vice-versa)
error: script "lint" exited with code 1

Note that oxlint itself reports Found 0 warnings and 0 errors on stdout while the mirror failure goes to stderr. Anything that surfaces only the tail of stdout will report this as a clean pass.

3. Stray paths. 20 shadowing symlinks land in .claude/skills/ beside the six real repo-native directories, and a agent/skills/ directory appears at the repo root.

Expected

The installer's symlink strategy assumes the target is a consumer project. When the destination already contains the source of the skills being installed, linking a source path at its own output location is not safe. Either:

1. Detect that the target is the skills' own repo and refuse, the way a package manager refuses to install a package over its own working copy, or
2. Never write into a path tracked by the target's git index, or
3. At minimum warn and require a confirmation flag before replacing a tracked directory with a symlink.
4. Treat .agents/skills/ as off-limits in this repo, since scripts/check-skill-mirror.mjs owns its contents.

Recovery

For anyone who hits this, before anything is committed:

for n in skills/*; do [ -L "$n" ] && rm "$n"; done
git checkout -- skills/
for n in .claude/skills/*; do [ -L "$n" ] && rm "$n"; done
rm -rf agent/
# restore the mirror: keep only README.md and the six repo-native skills
KEEP="README.md captions-overlay changelog-video cut-the-curve motion-doctrine oversized-cursor seam-craft"
for e in .agents/skills/*; do
  n=$(basename "$e")
  case " $KEEP " in *" $n "*) continue;; esac
  git ls-files --error-unmatch "$e" >/dev/null 2>&1 || rm -rf "$e"
done
git status --porcelain | wc -l   # 0
bun run lint                     # exit 0

Verified on a repo that hit this: 915 tracked files restored, all six repo-native skills intact, mirror identical to .claude/skills/, lint back to exit 0, working tree clean. Nothing is lost as long as the deletions were never committed.

Impact

Anyone who clones this repo to contribute a skill, then follows the README's own install instructions to try the skills locally, silently deletes the source they came to edit and breaks their build gate. The deletion is invisible until git status, and the lint failure reads as a mirror problem rather than as installer fallout.

Environment

macOS 15.6, repo at 14b9e2039, installer npx skills add resolved fresh.