Global skill-mirroring step deletes unrelated user-authored skills, then erases evidence of doing so

[MASTERGROOT]

Summary

hyperframes init/skills update deleted two unrelated, pre-existing, user-authored skills from ~/.claude/skills/ while linking into global agent directories. Root cause looks like the "link into N other agent directories" step writes lock entries in ~/.agents/.skill-lock.json for every skill folder already present in a target directory — not just the ones it just installed — attributing them to heygen-com/hyperframes. The very next removed-skill check then finds those names absent from HyperFrames' own manifest and deletes them as "no longer published," then prunes the now-orphaned lock entries — which erases the evidence of the false attribution.

Environment

• hyperframes CLI via npx (cached at ~/.npm/_npx/2d24f54ded6cd194/node_modules/hyperframes)
• macOS, Node via Homebrew
• Multiple AI-tool skill directories present on the machine (~/.claude/skills, ~/.codex/skills, ~/.cursor/skills, ~/.copilot/skills, ~/.gemini/skills, ~/.continue/skills, ~/.agents/skills, etc.) — some pre-populated with unrelated, hand-authored skills unconnected to HyperFrames.

Steps to reproduce

1. Have at least one unrelated skill already present in a global skills directory HyperFrames will target, e.g. ~/.claude/skills/my-own-skill/SKILL.md, authored independently and never installed via HyperFrames.
2. In a project, run npx hyperframes skills update <workflow-name> (project-scoped) or npx hyperframes init <dir> --skill=<workflow-name> (which links into every detected global agent directory).
3. Observe the CLI's own output: Linked skills into N other agent directories, followed on a subsequent check/update pass by Removing M skill(s) no longer published: ... — where the removed list can include names that were never HyperFrames skills.
4. Check ~/.claude/skills/my-own-skill/ — deleted from disk.
5. Check ~/.agents/.skill-lock.json — no trace of my-own-skill (pruned as an "orphaned lock entry" in the same pass), making the false attribution hard to spot after the fact.

What actually happened to me

Running npx hyperframes skills update general-video (project-scoped) followed shortly by npx hyperframes init "Video/.../hyperframes-final" --skill=general-video (which reported Linked skills into 9 other agent directories) resulted in two of my own, user-authored skills being deleted from ~/.claude/skills/ — both git-tracked in my personal skills repo and completely unrelated to HyperFrames, no shared name, no shared source. I was able to restore them with git checkout since that directory happens to be under version control; on a machine without that safety net this would be permanent, silent data loss.

Expected behavior

The "link into other agent directories" step should only ever write/attribute lock entries for skills it is actually installing in this operation. It should never treat a target directory's pre-existing, unrelated contents as something it now owns and is therefore responsible for pruning.

Suggested fix direction

In the compiled CLI (dist/cli.js), the relevant functions are detectRemoved, skillsAttributedToSource, and whatever performs the initial "link into N other agent directories" step (upstream of detectRemoved, since by the time detectRemoved/pruneOrphanedLockEntries run, ~/.agents/.skill-lock.json already (incorrectly) attributed the unrelated skills to heygen-com/hyperframes). The link step should record only skills it created/copied in that run, not enumerate and claim everything already on disk in the target directory.

Happy to provide more detail or test a fix — this cost real (recoverable, in my case) data loss and I'd guess it's silent for most users since the orphan-prune step deletes the evidence.

[jrusso1020]

Thanks for this — the report was detailed enough to reproduce from, and it surfaced a real data-loss bug. Fix is up in #3118. Two parts to the answer, because what I found is not the mechanism you proposed, and I want to be straight about that rather than quietly ship a fix under your explanation.

The bug I confirmed

skills update deletes skills that skills add just installed, and reports them as "no longer published."

1. skills add --skill '*' installs every skill in the repo — including repo-native ones under .claude/skills/ and .agents/skills/, not just the ones under skills/.
2. The lock attributes all of them to heygen-com/hyperframes. Every entry's source is identical.
3. Our published manifest is generated from skills/ only, so it never lists the repo-native ones.
4. Removed-detection read "absent from the manifest" as "removed upstream" and pruned them.

Reproduced against the real CLI in a sandboxed HOME: add installed 25 skills, then update printed

Removing 6 skill(s) no longer published: captions-overlay, changelog-video,
cut-the-curve, motion-doctrine, oversized-cursor, seam-craft

and deleted all six — every one currently published. check || update therefore never converged: add reinstalls them, the next update deletes them again.

The fix scopes the prune to skills the manifest is actually authoritative for, using the lock's skillPath (the only field distinguishing skills/general-video/… from .agents/skills/seam-craft/…). Entries with no skillPath are left alone — for a delete, unknown provenance should fail safe. You were right that detectRemoved is the surface.

Where your root-cause read doesn't hold

I tested the specific mechanism you proposed — that the link step writes lock entries for every folder already present in a target directory — and it does not happen:

• The mirror step writes no lock entries at all. It only symlinks (copies on Windows), and it selects by lock attribution rather than by listing the directory.
• The upstream installer writes entries only for skills it selected and successfully installed, not for what it finds on disk.
• Empirically: I put two hand-authored skills in ~/.claude/skills in the sandbox, ran the exact install, and checked the lock. Neither ever appeared in it, and both survived every run including the one that deleted the six above.

So I could not reproduce deletion of skills that were never HyperFrames', and the fix in #3118 does not explain your loss on its own. That gap is still open, and it's the part I care most about.

What would close it

If you still have the machine state, any of these would help:

1. The two skill names, exactly as the directories were spelled.
2. Whether a skills-manifest.json existed anywhere in or above the directory you ran the command from (we search up to 16 parent directories, and fix(cli): stop skills update deleting skills the manifest never covered #3118 also stops that file from driving deletions).
3. Your hyperframes version — npx hyperframes --version, or the version in ~/.npm/_npx/2d24f54ded6cd194/node_modules/hyperframes/package.json, since npx pins that cache.
4. git log -1 --stat in your personal skills repo for the restoring git checkout, which dates the deletion.

One concrete hypothesis for your case that I have not confirmed: removal resolves names through a sanitizeName normalisation (lowercased, runs of non-[a-z0-9._] collapsed to -). Two names that differ can normalise to the same string — My Skill and my-skill both become my-skill. If either of your skills normalised to one of the six above, it would have been deleted by name. That is why the exact spellings would settle it.

Taking you up on the offer to test: #3118 is the branch, and if you can reproduce your original loss on it I'd rather find that now than close this as fixed when only half of it is.

[jrusso1020]

Reopening — this auto-closed when #3118 merged (ed3ff98ce), which was my mistake: I put Fixes #3111 in the commit message when it should have been a plain reference. Sorry for the noise if you got a "closed as completed" notification.

#3118 does fix a real data-loss bug your report surfaced, but not the one you reported. It stops skills update deleting skills that skills add had just installed — the six repo-native ones the published manifest doesn't cover. Your case, unrelated hand-authored skills being deleted, is still unexplained, and I could not reproduce it.

So this stays open until either:

• you can share the details from my earlier comment — most usefully the exact directory spellings of the two skills, since the leading unconfirmed hypothesis is a name-normalisation collision (My Skill and my-skill both normalise to my-skill, and removal resolves by the normalised name); or
• we establish the cause another way; or
• you tell us you'd rather not chase it, and we close it as "different bug fixed, original cause not established" — which is honest, and better than leaving it looking diagnosed when it isn't.

The fix is on main now if you want to try reproducing your original loss against it. If it still happens there, that's the most useful possible datapoint and I'd want to know.