feat(cli): skills freshness — version check, manifest, global install + multi-agent mirror

[WaterrrForever]

Summary

Makes HyperFrames' bundled agent skills self-updating and verifiable. Adds a content-hash freshness manifest, a hyperframes skills check/update command group, automatic refresh on init, a single global install that mirrors to every other installed agent, and a one-line staleness nudge on common commands. Workflow docs are updated so newly scaffolded projects pull the latest skills by default.

What's included

Freshness manifest (source of truth)

• skills-manifest.json at the repo root — a per-skill content fingerprint (hashes the whole skill bundle: SKILL.md + references/ + scripts/ + …), no version/timestamp so it only changes on real content change.
• Generator packages/cli/scripts/gen-skills-manifest.ts (bun run gen:skills-manifest).
• Kept in sync automatically: a lefthook pre-commit hook regenerates + re-stages it on any skills/** change, and a CI job (“Skills: manifest in sync”) fails the build if it drifts.

hyperframes skills command group

• skills check — compares the installed skills against the latest manifest on GitHub; --json for a machine-readable verdict; exits non-zero when anything is outdated or missing.
• skills update — pulls the full set to the latest, installing any not yet present.
• bare skills — installs the full set.

init integration

• init checks installed skills against GitHub and installs/refreshes only when stale or missing (no-op when current; never hard-fails on a network hiccup — falls back to installing after a short timeout).
• Opt out with init --skip-skills.

Global install + multi-agent mirror

• Installs the full set once globally (~/.claude/skills + the universal ~/.agents/skills) with --copy --full-depth — --full-depth clones main HEAD so a fresh install reads as current instead of lagging the skills.sh registry blob.
• skillsMirror then symlink-mirrors that canonical store into every other installed agent's global dir (Codex, Cursor, Gemini, Hermes, Goose, … — 71 agents), but only for agents actually present on the machine. Unix uses relative symlinks (one source of truth, auto-fresh on update); Windows copies.
• Agent dir table is generated: packages/cli/scripts/sync-agent-dirs.ts → agentDirs.generated.ts (honors XDG_CONFIG_HOME, CODEX_HOME, CLAUDE_CONFIG_DIR, …).

Staleness nudge

• render / lint / validate print a one-line reminder when skills are stale — cached 24h, best-effort, never blocks or fails the command, suppressed under --json.

Workflow docs

• Dropped --skip-skills from the workflow init commands (product-launch / faceless / pr-to-video / music-to-video / motion-graphics / embedded-captions) so each new project refreshes skills, with a one-line note in each and in hyperframes-cli / the entry hyperframes skill.

Also

• CI path-filter + telemetry config for the new flow; CodeQL file-system race fix; Windows npx test de-flake; manifest review-feedback follow-ups.

How precedence works (why check is global-first)

Per Claude Code's documented order — personal (~/.claude/skills) overrides project (.claude/skills) — so a fresh global install silently supersedes a stale project copy. skills check reports on the global copy because that's the one the agent actually loads.

Test plan

• bun run test (adds coverage for manifest hashing/diff, mirror fan-out incl. XDG/Codex bases, and the init check path).
• bun packages/cli/scripts/gen-skills-manifest.ts --check passes (manifest in sync).
• Verified init refreshes the global store and mirrors into other installed agents; skills check --json exit codes for current / outdated / missing.

🤖 Generated with Claude Code

[miga-heygen]

Skills Freshness — Version Check, Manifest, Global Install + Multi-Agent Mirror

Reviewed: 3904420 (merge commit)

Thorough and well-structured PR. The shift from per-project scoped installs to a single global install + symlink mirror is a clean architectural improvement — one source of truth, one install, n symlinks. The generated agent-dir table, the content-hash manifest, and the global-first check order all hang together consistently. Test coverage is solid, CI is fully green (all 35 checks pass), and the deleted skillsTargets.ts was cleanly superseded.

I have a few observations, none blocking:

---

Nits

1. Typo in mirror log message (skills.ts L155): "Linked skills into ${mirrored.length} other agent director(ies)." — "director(ies)" is not a word. Since mirrored.length > 0 is always true at this point, just use "directories". Or if you want singular/plural: ${mirrored.length} other agent ${mirrored.length === 1 ? "directory" : "directories"}.

2. Marker-dir detection granularity for deep sub-paths: The marker check !existsSync(dirname(targetDir)) works well for single-segment agents like .cursor/skills (checks ~/.cursor), but for deeper paths like .gemini/antigravity/skills it checks ~/.gemini/antigravity instead of ~/.gemini. This means if Gemini creates ~/.gemini/ on install but only populates ~/.gemini/antigravity/ on first use, the mirror would skip that agent even though it's installed. Probably fine in practice — agents tend to create their full dir tree — but worth a note if you want the marker to be the top-level agent dir consistently. Not blocking.

Observations (informational, not action items)

3. resolveBases env-var asymmetry: configHome validates isAbsolute(xdg) before using XDG_CONFIG_HOME (matching the XDG spec), but CODEX_HOME, VIBE_HOME, etc. are used as-is without the absolute-path check. Intentional difference (XDG is spec'd, the others aren't), but worth noting for symmetry. If an operator sets CODEX_HOME=./relative, it would produce an unexpected path. Low risk, just calling it out.

4. sync-agent-dirs.ts pin management: The SKILLS_REF = "v1.5.13" pin is the right call for determinism. Might be worth adding a comment about when/how to discover that a bump is needed (e.g. a dependabot-style check, or a CI job that runs --check against latest). Currently bumping is purely manual discovery.

5. Silent catch in installAllSkills (skills.ts L158): The catch {} after mirrorGlobalSkills() is intentionally best-effort, which is good — a mirror failure should not block the install. The empty catch body is fine given the "best-effort" contract is documented in the comment above it.

What I liked

• The global-first check order matching the agent's actual load order is a smart alignment — it eliminates the confusing "check says outdated but the agent is using the fresh global copy" scenario.
• The --full-depth fix for the skills.sh registry lag is a solid catch. The death-loop diagnosis (install → check → "still outdated" → install → ...) is well documented in the commit messages.
• The generated agentDirs.generated.ts with a pinned upstream ref is the right balance between tracking upstream and runtime determinism.
• Excellent commit history — each commit tells a clear story of the evolution, and the review-feedback commit shows good iteration.

Verdict: LGTM with one cosmetic nit (the "director(ies)" typo).

— Miga

[jrusso1020]

Additive review on top of <https://github.com/heygen-com/hyperframes/pull/1753#pullrequestreview-4583368434|Miga's pass>. Miga's review covers the priority code surface + nits cleanly. My additive lane: the supersession question — does this PR cleanly replace #1748's targeting logic, or accidentally regress it? Plus a coverage check on #1738/#1744.

Supersession verdict — DELIBERATE clean replacement, not accidental revert ✓

The architectural shift is the key — #1753 doesn't replace #1748's resolveAgentTargets with an equivalent targeting function. It replaces the question itself:

• #1748's question: "we're installing PER-PROJECT — which agents in this project should get the skills?"
• #1753's answer: "install once GLOBALLY; the agent's documented load order makes global override project, so per-project targeting is no longer needed."

This sidesteps the targeting problem rather than re-solving it. The four cases #1748's resolveAgentTargets handled all map cleanly to the new model:

#1748 case	#1753 coverage
1. Existing project skill folder honoring (.claude/skills, .hermes/skills exist → install only to those)	Effectively preserved by override semantics. Global ~/.claude/skills shadows project .claude/skills per Claude Code's documented load order. The project folder is untouched but the agent reads from global.
2. CLAUDECODE env → install to claude-code only	Effectively preserved + extended. GLOBAL_INSTALL_ARGS hardcodes --agent claude-code universal, so claude-code gets skills regardless of whether the env var is set. More complete than #1748.
3. PATH-probe (gstack: claude/hermes/droid/cursor/codex/opencode/gemini binaries)	Replaced with marker-dir detection (existsSync(dirname(targetDir))). Different heuristic — Miga's nit #2 flags one edge case where deep sub-paths (.gemini/antigravity/skills) check the parent (.gemini/antigravity) instead of .gemini. For most agents the marker-dir test works; the Gemini-antigravity case is the only one I'd flag for follow-up.
4. Floor (claude-code + universal .agents)	Built-in structural — hardcoded in GLOBAL_INSTALL_ARGS. Used to be a fallback heuristic; now it's an invariant.

Net: this is a deliberate architectural improvement, not a regression. The new model is stronger on cases 2 and 4 (no longer heuristic — structural), equivalent on case 1 (different mechanism, same observable behavior), and slightly different on case 3 (marker-dir vs PATH-binary detection).

Preservation of already-merged behavior

#1738 (freshness manifest) — preserved + extended. The manifest is regenerated via lefthook pre-commit + the CI Skills: manifest in sync gate (carried forward from #1745). skills-manifest.json is in the PR diff with the manifest re-pinned to the consolidated skill set. ✓

#1744 (--copy real-file install) — preserved + extended. --copy is still in GLOBAL_INSTALL_ARGS (line 80, packages/cli/src/commands/skills.ts), now paired with --full-depth to bypass the skills.sh registry blob lag (the documented "death-loop" diagnosis in the commit history). The --full-depth rationale is well-explained — verified as a real flag at vercel-labs/skills@v1.5.13 (grep "--full-depth" src/cli.ts → --full-depth Search all subdirectories even when a root SKILL.md exists). ✓

Additive nit — customized-project-skills shadowing

Per the override semantics, if a user has customized their project's .claude/skills/ with project-specific skills not in the global set, the global install doesn't touch the project folder — but skills with the same name in both would be shadowed by global. No data loss (project skills remain on disk), but a user expecting their customized project skill to "win" would see global override it. The PR body's "Per Claude Code's documented order — personal overrides project — so a fresh global install silently supersedes a stale project copy" is the right framing; just worth noting that "stale project copy" could occasionally mean "intentionally customized project copy." Not a blocker — Claude Code's load order is the upstream contract this PR conforms to.

Concur with Miga's findings

• Typo (director(ies) → directories or pluralized) — cosmetic.
• Marker-dir granularity on deep sub-paths (e.g. .gemini/antigravity/skills) — the Gemini-antigravity edge case is the one I'd flag for a tiny follow-up; reasonable to ship as-is.
• resolveBases env-var asymmetry (XDG validated absolute; CODEX_HOME / VIBE_HOME / etc. used as-is) — informational, not blocking.
• SKILLS_REF = "v1.5.13" pin — right call for determinism; bump discovery is manual today (worth a future automation).
• Silent catch in installAllSkills mirror block — best-effort by design, correctly documented inline.

Verdict

COMMENT — external author, routing through <@U08E7PV788Z> for any stamp/merge call per protocol. Supersession is deliberate + clean; #1738/#1744 behavior preserved; CI fully green. No additional blockers from me on top of Miga's "LGTM with cosmetic nit" verdict.

— Jerrai

[miguel-heygen]

Thanks Miga/Rames — I agree with the high-level architecture, but I found one blocker before stamping.

mirrorGlobalSkills currently mirrors every */SKILL.md directory present in the Claude global store, not just the HyperFrames skills this command just installed. Concretely, listSkillDirs(source) reads all of ~/.claude/skills, and then mirrorInto removes/replaces the same skill-name entry under every installed agent global dir.

That means a user with unrelated Claude Code skills already installed, e.g. gstack or personal/company skills in ~/.claude/skills, can run npx hyperframes skills update and have those unrelated skills symlinked/copied into Cursor/Codex/Goose/etc. Worse, if another agent already has a same-named skill from a different source, linkOrCopy removes it before linking to the Claude copy.

This PR should keep the mirror scoped to the HyperFrames skill set/source only. The clean fix is to pass the manifest-listed HyperFrames skill names into mirrorGlobalSkills (or derive them from skills-manifest.json / the install source lock) and add a regression test seeding ~/.claude/skills/gstack/SKILL.md plus a target agent marker, asserting gstack is not mirrored or replaced.

The cosmetic director(ies) typo Miga flagged is still non-blocking. CI is green; the blocker is the cross-source mirror scope.

[jrusso1020]

R2 verification at 402fbfae — clean fix for the store-sharing scoping issue. The change is exactly the right shape:

What R1 had wrong + what R2 fixes

R1's mirrorGlobalSkills called listSkillDirs(source) against ~/.claude/skills — the entire shared store. So a user with gstack / personal / company / other-source skills installed alongside HyperFrames in their Claude store would have had ALL of them fanned out to every other installed agent's global dir. Not a HyperFrames-scoped mirror; a "your entire Claude library spread to Cursor/Codex/Goose/etc."

The fix:

• mirrorGlobalSkills now requires skills: readonly string[] as a mandatory parameter (no more directory-scan).
• New hyperframesSkillNames({ scope }) reuses the same source-attribution mechanism the prune already uses (skillsAttributedToSource(readSkillLock(...), DEFAULT_REPO_SLUG)) — so the allow-list is derived from the install lock's authoritative attribution, not heuristic.
• The mirror callsite in installAllSkills extracts the lock-attributed names via hyperframesSkillNames({ scope: "global" }) and passes them through — no scan ever happens.
• Empty when lock absent → mirror-none default (safe).

Test coverage on the fix

The new test pins exactly the failure mode that needed locking in:

"only mirrors the allow-listed skills, never other sources' (gstack)"

The test seeds ~/.claude/skills/{hyperframes, gstack} (HyperFrames + a foreign skill in the same shared store), then pre-creates a ~/.cursor/skills/gstack (cursor's own gstack from another source). Three invariants verified after mirrorGlobalSkills({ skills: ["hyperframes"], ... }):

1. HyperFrames was linked into ~/.cursor/skills/hyperframes ✓
2. gstack stayed in ~/.claude/skills (foreign, didn't get pulled into the operation) ✓
3. Cursor's pre-existing ~/.cursor/skills/gstack was NOT replaced with a symlink and NOT removed ✓

That third invariant is the critical one — proves the mirror doesn't clobber any same-named skill in another agent's dir that came from a different source. The rmSync(targetSkill, ...) in linkOrCopy is now scoped to the allow-list, so untouched skills are truly untouched.

Also picked up — typo + log shape

"Linked skills into N other agent director(ies)." → "Linked skills into N other agent ${n === 1 ? "directory" : "directories"}." per Miga's R1 nit #1. Cosmetic but cleaned.

Verdict

R2 cleanly addresses the scoping defect. Architecture is correct (mandatory allow-list, lock-derived attribution, no directory-scan). Test coverage is tight. Still COMMENT (external author, stamp routing through <@U08E7PV788Z>).

— Jerrai

[miga-heygen]

Re-review at 402fbfa (one new commit since 3904420: fix(cli): scope agent mirror to HyperFrames' own skills, not the whole store).

This commit directly addresses Miguel's blocker — the cross-source mirror scope — and looks solid. The approach:

1. New hyperframesSkillNames() in skillsManifest.ts — reads the skill lock and returns only the names attributed to the HyperFrames source (same source-attribution the prune path uses). Clean single-responsibility function, good JSDoc explaining why store-listing is wrong here.

2. mirrorGlobalSkills() now takes a skills: readonly string[] allow-list and filters listSkillDirs() through a Set before mirroring. The type is readonly string[] which correctly signals the function won't mutate the caller's array. All call sites updated.

3. mirrorToInstalledAgents() helper in skills.ts encapsulates the resolve-names → mirror → log flow, replaces the inline try/catch that previously mirrored everything. The director(ies) cosmetic nit is fixed too — now uses a proper ternary for singular/plural.

4. Regression test — seeds gstack in the store + a pre-existing gstack in Cursor's skills dir, mirrors with skills: ["hyperframes"] only, and asserts: (a) hyperframes got linked, (b) gstack was NOT mirrored from the store, (c) Cursor's pre-existing gstack was neither replaced nor removed. This is exactly the scenario Miguel described. Well-structured, reads clearly.

5. All existing mirror tests updated to pass the skills parameter. Mock for hyperframesSkillNames added to the skills command tests.

No concerns. The scoping is correct, the test covers the exact cross-source contamination scenario, and the implementation reuses the existing lock-attribution machinery rather than inventing a parallel concept. CI still running (several checks pending, key ones like SDK/skills/npx-shim already green).

LGTM — addresses the blocker cleanly.

— Miga

[miguel-heygen]

R2 on 402fbfae: blocker resolved.

The mirror is now scoped by lock-attributed HyperFrames skill names via hyperframesSkillNames({ scope: "global" }), and mirrorGlobalSkills requires an explicit allow-list instead of scanning the whole Claude global store. That closes the cross-source contamination/data-replacement issue I requested changes on. The regression test covers the exact failure class: a foreign gstack in ~/.claude/skills is not mirrored, and an existing Cursor-side gstack is not replaced.

CI is green, including Test: skills, Smoke: global install, CodeQL, and Windows render/tests.

Verdict: APPROVE
Reasoning: The prior blocker is fixed with source-attributed scoping plus a targeted regression; no remaining blockers from my pass.

— Magi