Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { setCommandExitCode, CliResultSignal } from "../utils/commandResult.js";
import { defineCommand } from "citty";
import { execFileSync, spawn } from "node:child_process";
import * as clack from "@clack/prompts";
import { c } from "../ui/colors.js";
import { diag } from "../ui/diagnostics.js";
import { buildNpxCommand } from "../utils/npxCommand.js";
import { withMeta } from "../utils/updateCheck.js";
import {
checkSkills,
FALLBACK_CORE_SKILLS,
hyperframesSkillNames,
isCoreSkill,
presentSkills,
pruneOrphanedLockEntries,
RETIRED_SKILLS,
retiredSkillNotice,
SKILLS_CLI_LOCK_PATHS_VERIFIED_AT,
type SkillDiff,
type SkillsCheckResult,
} from "../utils/skillsManifest.js";
import { mirrorGlobalSkills } from "../utils/skillsMirror.js";
import { invalidateSkillsCache } from "../utils/skillsUpdateCheck.js";
import { trackSkillsInstallSkipped } from "../telemetry/events.js";
import type { Example } from "./_examples.js";
export const examples: Example[] = [
["Install all HyperFrames skills", "hyperframes skills"],
["Check whether installed skills are up to date", "hyperframes skills check"],
["Check, machine-readable (for agents / CI)", "hyperframes skills check --json"],
["Update the core set + everything already installed", "hyperframes skills update"],
["Also install one on-demand skill", "hyperframes skills update slideshow"],
];
function hasNpx(): boolean {
const npx = buildNpxCommand(["--version"]);
try {
execFileSync(npx.command, npx.args, { stdio: "ignore", timeout: 5000 });
return true;
} catch {
return false;
}
}
// The upstream `skills` CLI clones the repo with `git`. When git is missing
// (common on fresh Windows boxes) the clone aborts mid-run with a noisy,
// multi-line `spawn git ENOENT` / "Installation failed" block, so detect git
// up front and skip cleanly instead of letting that surface. `git` resolves as
// a real executable on every platform, so no cmd.exe wrapping is needed.
function hasGit(): boolean {
try {
execFileSync("git", ["--version"], { stdio: "ignore", timeout: 5000 });
return true;
} catch {
return false;
}
}
function spawnNpx(args: string[], opts: { cwd?: string } = {}): Promise<void> {
const npx = buildNpxCommand(args);
return new Promise((resolve, reject) => {
const child = spawn(npx.command, npx.args, {
// Route the child's stdout to the parent's stderr (fd 2), keeping stdin
// inherited. `skills update --json` runs this installer before printing its
// JSON envelope on stdout; child progress chatter on stdout would corrupt it.
// Diagnostics belong on stderr regardless of mode, so this is safe for the
// interactive path too (the user still sees the output).
stdio: ["inherit", 2, 2],
// We install with --full-depth (a full `git clone` of the repo, the only
// path that bypasses the laggy skills.sh blob — see GLOBAL_INSTALL_ARGS_TAIL),
// which is heavier than the blob fetch, so allow more headroom.
timeout: 300_000,
cwd: opts.cwd,
env: {
...process.env,
// GH #316 — the upstream `skills` CLI shells out to `git clone`. When
// Git's clone-hook protection is active (default in 2.45.1, reverted in
// 2.45.2, still present on many corporate/CI setups), a globally
// registered `git lfs install` post-checkout hook aborts the clone. The
// args reaching this function are hardcoded (no user input), so opting
// out is safe.
GIT_CLONE_PROTECTION_ACTIVE: "0",
// Skills are text; the repo's LFS objects are unrelated binary assets.
// Skip the smudge so --full-depth doesn't drag down (or fail on) large
// LFS blobs the install doesn't need.
GIT_LFS_SKIP_SMUDGE: "1",
},
});
child.on("close", (code, signal) => {
if (code === 0) resolve();
else if (signal === "SIGINT" || code === 130)
reject(new CliResultSignal({ exitCode: 0, kind: "success", presented: true }));
else reject(new Error(`npx ${args.join(" ")} exited with code ${code}`));
});
child.on("error", reject);
});
}
// One faithful global install: --copy lands real files in Claude Code's global
// store (~/.claude/skills, which Claude Code reads at global priority) plus the
// shared universal store (~/.agents/skills). mirrorGlobalSkills then fans that
// store out to every OTHER installed agent's global dir. Skills are
// framework-general knowledge, so installing once globally beats copying a full
// set into every project — and avoids the ~70-agent `--all` spray entirely.
//
// Why --copy: real files (not the upstream symlink default, which re-serialises
// each SKILL.md's frontmatter) so an installed bundle byte-matches the published
// manifest and `skills check` reads it as current. Why --full-depth: it forces a
// full `git clone` of HEAD; without it even a full-URL `skills add` fetches the
// skills.sh registry blob, which lags GitHub main by hours, so a fresh install
// would read as several skills "outdated" (verified: blob → ~9 outdated;
// --full-depth → all current).
const GLOBAL_INSTALL_ARGS_TAIL = [
"--global",
"--agent",
"claude-code",
"universal",
"--copy",
"--full-depth",
"--yes",
];
/** All skills, or an explicit list of skill names to install. */
type SkillSelection = "*" | readonly string[];
// The upstream CLI takes one `--skill` flag per name (`--skill a --skill b`),
// with `'*'` meaning "all skills" — see vercel-labs/skills `add --skill`.
function skillSelectionArgs(selection: SkillSelection): string[] {
const names = selection === "*" ? ["*"] : selection;
return names.flatMap((name) => ["--skill", name]);
}
function runSkillsAdd(
source: string,
selection: SkillSelection,
opts: { cwd?: string } = {},
): Promise<void> {
return spawnNpx(
["skills", "add", source, ...skillSelectionArgs(selection), ...GLOBAL_INSTALL_ARGS_TAIL],
opts,
);
}
// Skill names are kebab-case directory names. Refuse anything that isn't one
// before spreading it into a spawn: a corrupt or crafted lock entry (these
// names originate as lock-file JSON keys) could otherwise smuggle a flag-like
// (`--config=…`) or shell-special token into the command — which matters most
// on the Windows `cmd.exe` spawn path, where arg escaping is fragile.
const PLAIN_SKILL_NAME = /^[a-z0-9][a-z0-9._-]*$/i;
function runSkillsRemove(names: string[], opts: { global: boolean }): Promise<void> {
const safe = names.filter((n) => PLAIN_SKILL_NAME.test(n));
const rejected = names.filter((n) => !PLAIN_SKILL_NAME.test(n));
if (rejected.length) {
clack.log.warn(c.warn(`Skipping unexpected skill name(s): ${rejected.join(", ")}`));
}
if (!safe.length) return Promise.resolve();
// `skills remove --yes` deletes the bundle dir, every agent symlink, and the
// lock entry non-interactively. `-g` targets the global install; without it,
// the project (cwd) install — we pass whichever scope detection attributed
// these names from, so we never reach into a scope we didn't inspect.
return spawnNpx(["skills", "remove", ...safe, ...(opts.global ? ["-g"] : []), "--yes"]);
}
// Use the full GitHub URL (not the `owner/repo` slug) as the clone source. The
// freshness comes from --full-depth (see GLOBAL_INSTALL_ARGS_TAIL), which clones the
// repo at latest `main`; the URL just names what to clone. Our freshness check
// resolves "latest" straight from GitHub too, so install and check agree.
const SOURCES = [{ name: "HyperFrames", url: "https://github.com/heygen-com/hyperframes" }];
// Fan HyperFrames' own skills out to every other installed agent. Scope by the
// lock's source attribution (the same definition prune uses) — NOT by listing
// ~/.claude/skills, which is shared with the user's other Claude skills (gstack,
// personal, company). No-op when nothing is attributed or the global store is
// absent, so it's safe to run unconditionally after any install. Best-effort: a
// mirror failure must not fail the install.
function mirrorToInstalledAgents(): void {
try {
const names = hyperframesSkillNames({ scope: "global" });
if (names.length === 0) return;
const { mirrored, skipped } = mirrorGlobalSkills({ skills: names });
const n = mirrored.length;
if (n > 0) {
// stderr (via diag): reachable from `skills update --json` (via installSkills)
// before the JSON envelope is written to stdout.
diag.notice(
c.dim(`Linked skills into ${n} other agent ${n === 1 ? "directory" : "directories"}.`),
);
}
if (skipped.length > 0) {
const agents = [...new Set(skipped.map((entry) => entry.agent))].join(", ");
diag.warn(
c.warn(
`Skipped unsafe skill mirror target${skipped.length === 1 ? "" : "s"} for ${agents}; canonical skill stores were left unchanged.`,
),
);
}
} catch {
// best-effort
}
}
// The install shells out to `npx skills add`, and that CLI clones the repo with
// git — so both must be on PATH. Each entry pairs a detector with the strict
// error (thrown so the `check || update` recovery contract fails loudly) and a
// best-effort report (one calm line; init carries on and still scaffolds).
const SKILLS_TOOLING: ReadonlyArray<{
has: () => boolean;
error: string;
// Low-cardinality tag for the skip telemetry event (e.g. "git_missing").
reason: string;
report: () => void;
}> = [
{
has: hasNpx,
error: "npx not found. Install Node.js and retry.",
reason: "npx_missing",
report: () => clack.log.error(c.error("npx not found. Install Node.js and retry.")),
},
{
has: hasGit,
error: "git not found. Install git and retry to add AI coding skills.",
reason: "git_missing",
// Skip cleanly rather than letting the upstream clone dump a noisy
// multi-line `spawn git ENOENT` / "Installation failed" abort.
report: () => console.log(c.dim("Skipping AI coding skills: git not available.")),
},
];
/** True if the install can proceed; otherwise reports (or throws, when strict). */
function skillsToolingReady(strict: boolean): boolean {
for (const tool of SKILLS_TOOLING) {
if (tool.has()) continue;
if (strict) throw new Error(tool.error);
tool.report();
// Surface the rare best-effort skip (init on a box missing git/npx); the
// event respects the telemetry opt-out inside trackEvent.
trackSkillsInstallSkipped({ reason: tool.reason });
return false;
}
return true;
}
// Skill names can originate from a fetched manifest or agent argv, and each is
// spread into a spawn as a `--skill` value — apply the same slug guard as
// runSkillsRemove so a flag-like name can't smuggle into the command. Returns
// null when nothing valid is left to install.
function sanitizeSelection(selection: SkillSelection): SkillSelection | null {
if (selection === "*") return selection;
const rejected = selection.filter((n) => !PLAIN_SKILL_NAME.test(n));
if (rejected.length) {
clack.log.warn(c.warn(`Skipping unexpected skill name(s): ${rejected.join(", ")}`));
}
const safe = selection.filter((n) => PLAIN_SKILL_NAME.test(n));
return safe.length > 0 ? safe : null;
}
async function installSkills(
selection: SkillSelection,
opts: { cwd?: string; strict?: boolean } = {},
): Promise<void> {
const safeSelection = sanitizeSelection(selection);
if (safeSelection === null) return;
if (!skillsToolingReady(opts.strict ?? false)) return;
// stderr (via diag): installSkills runs on the `skills update --json` path before
// its JSON envelope is written to stdout — progress here must not corrupt it.
for (const source of SOURCES) {
diag.notice();
diag.notice(c.bold(`Installing ${source.name} skills...`));
diag.notice();
try {
await runSkillsAdd(source.url, safeSelection, opts);
} catch (err) {
if (opts.strict) throw err instanceof Error ? err : new Error(String(err));
// warn, not notice: this is a non-fatal skip after a caught install error.
diag.warn(c.dim(`${source.name} skills skipped`));
}
}
mirrorToInstalledAgents();
}
// ── targeted install engine ───────────────────────────────────────────────────────────────────
/** What an `updateSkills` run guaranteed, and what it had to do to get there. */
export interface UpdateSkillsResult {
/** Every skill this run guaranteed: requested + core (+ installed, when refreshing). */
targets: string[];
/** Targets that were (re)installed by this run. */
installed: string[];
/** Targets that were already current — nothing fetched for them. */
current: string[];
/**
* Requested names the latest manifest doesn't ship (typo, or renamed
* upstream). Only ever non-empty on a non-strict run: a strict run throws on
* unknown names before returning, so strict callers never observe this — a
* future caller reading `unknown` should not expect it under `strict: true`.
*/
unknown: string[];
/** True when freshness couldn't be checked (offline) and only presence was verified. */
presenceOnly: boolean;
/** Requested names that are retired: nothing to install, their knowledge lives in the core set. */
retired: string[];
}
/**
* The targeted install engine behind `init` and `skills update [names...]` —
* the replacement for "anything stale ⇒ re-pull the full skill set". It
* guarantees a small, explicit set is installed and current:
*
* - the requested names (an on-demand skill, e.g. `slideshow`; a retired
* name is reported, not installed),
* - the core set (entry skill + shared skills — see skillsManifest),
* - with `refreshInstalled`, whatever is already installed (refreshed, so an
* update never *expands* a deliberate partial install),
* - with `all`, every skill the manifest publishes. The upstream `*` wildcard
* is not used on any path: it also sweeps up the repo-internal skills under
* `.claude/skills` / `.agents/skills` (26 installed vs 20 published,
* observed 2026-09-04). Offline, where the published set is unknowable, the
* full install warns and degrades to the pinned core set instead.
*
* Only targets that are actually missing or outdated are passed to
* `skills add` (one spawn, one `--skill` flag per name); when everything is
* current the call is a fast no-op with no install. When the manifest is
* unreachable, freshness is unknowable and the run degrades to the presence
* half of the guarantee — see updateSkillsOffline.
*/
export async function updateSkills(
opts: {
requested?: readonly string[];
refreshInstalled?: boolean;
/** Every skill the manifest publishes (bare `hyperframes skills`). */
all?: boolean;
strict?: boolean;
cwd?: string;
} = {},
): Promise<UpdateSkillsResult> {
const named = [...new Set(opts.requested ?? [])];
const retired = named.filter((name) => RETIRED_SKILLS.includes(name));
const requested = named.filter((name) => !retired.includes(name));
const strict = opts.strict ?? false;
let check: SkillsCheckResult | null = null;
try {
// `canonical: true` — target selection must match what `skills add`
// actually installs from (the canonical published repo), never a local
// checkout's `skills-manifest.json`. Without this, running from inside a
// stale hyperframes checkout could resolve "latest" from that stale local
// file, which may still list a skill that's since been retired/renamed
// upstream. `isCoreSkill` would then force it into `targets`/`toInstall`,
// `skills add` would correctly (and silently) decline to install a skill
// that no longer exists, and verifyInstalled would strict-throw on a
// "failure" that was never real. Resolving canonically means a retired
// skill simply never appears as a target in the first place.
check = await checkSkills({ cwd: opts.cwd, canonical: true });
} catch (err) {
// A *malformed* canonical manifest (the server was reached, but served a
// bad shape) is otherwise indistinguishable from being offline — both fall
// through to presence-only mode below. Surface it distinctly so ops can
// tell an upstream/CDN problem apart from a genuine network failure.
if (err instanceof Error && err.message.startsWith("Malformed skills manifest")) {
clack.log.warn(
c.warn(
"Canonical skills manifest was malformed — falling back to presence-only mode (an upstream/CDN issue, not your network).",
),
);
}
check = null; // manifest unreachable (offline / rate-limited) — presence mode below
}
if (!check) {
if (opts.all) {
// The published set is unknowable offline. Say so and degrade to the
// pinned core set — never the upstream wildcard, which would quietly
// reinstate the 26-skill sweep this path exists to avoid.
clack.log.warn(
c.warn(
"Can't resolve the published skill set (manifest unreachable) — installing the pinned core set only. Re-run `hyperframes skills` online for the full set.",
),
);
}
return { ...(await updateSkillsOffline(requested, { strict, cwd: opts.cwd })), retired };
}
// "removed" entries are lock-attributed leftovers, not manifest skills —
// they are `skills update`'s prune concern, never an update target.
const manifestSkills = check.skills.filter((s) => s.status !== "removed");
const manifestNames = new Set(manifestSkills.map((s) => s.name));
const unknown = requested.filter((name) => !manifestNames.has(name));
if (unknown.length) {
const message =
`Unknown skill(s): ${unknown.join(", ")}. ` +
`Available: ${[...manifestNames].sort().join(", ")}`;
if (strict) throw new Error(message);
clack.log.warn(c.warn(message));
}
const targets = manifestSkills.filter(
(s) =>
opts.all === true ||
requested.includes(s.name) ||
isCoreSkill(s.name) ||
(opts.refreshInstalled === true && s.status !== "missing"),
);
const toInstall = targets.filter((s) => s.status === "missing" || s.status === "outdated");
const result: UpdateSkillsResult = {
targets: targets.map((s) => s.name),
installed: toInstall.map((s) => s.name),
current: targets.filter((s) => s.status === "current").map((s) => s.name),
unknown,
presenceOnly: false,
retired,
};
if (toInstall.length > 0) {
await installSkills(result.installed, { cwd: opts.cwd, strict });
verifyInstalled(result.installed, { strict, cwd: opts.cwd });
}
// The install (or the fresh canonical check confirming everything current)
// supersedes whatever the background nudge cached before it — drop the
// cached verdict so the next command re-checks instead of nagging from the
// pre-install snapshot for up to 24h. Deliberately NOT done on the offline
// (presence-only) path above: that run never learned anything about
// freshness, so the cached verdict is the best information we still have.
invalidateSkillsCache();
return result;
}
/**
* The presence half of the guarantee, after an install claims success: every
* name must now exist on disk. Catches the "install exited 0 but delivered
* nothing" failure mode, which would otherwise surface much later as a
* skill reading files that aren't there.
*
* Strictness mirrors the caller's tolerance: a strict run (the `check ||
* update` CI contract) throws so the
* failure is loud; a non-strict run (init) only warns and proceeds, since a
* skills hiccup must never break scaffolding.
*/
function verifyInstalled(names: readonly string[], opts: { strict: boolean; cwd?: string }): void {
const present = new Set(presentSkills(names, { cwd: opts.cwd }));
const absent = names.filter((name) => !present.has(name));
if (absent.length === 0) return;
const message = `Skill(s) still missing after install: ${absent.join(", ")}`;
if (opts.strict) throw new Error(message);
clack.log.warn(c.warn(message));
}
/**
* Offline degradation for updateSkills: the manifest is unreachable, so
* freshness is unknowable. What can still be honored is the PRESENCE half of
* the guarantee, extended to the pinned FALLBACK_CORE_SKILLS list so the
* preamble promise ("this skill plus the core set it depends on")
* doesn't silently shrink to just the named skill on degraded networks —
* raw.githubusercontent.com blocked while `git clone` works is a real
* corporate-proxy shape, which is exactly when the blind install below can
* still succeed.
*
* - Named run (`update <name>`): presence-check requested + fallback
* core, blind-install whatever is absent (a truly dead network fails the
* clone fast, and `strict` decides how loudly). Stale-but-present
* proceeds — blocking a build on a network hiccup is worse than running
* one release behind.
* - Bare run (nothing requested): the whole job was freshness, and presence
* can't prove it. strict — the documented `check || update` CI contract —
* must fail loudly rather than exit 0 while everything stays stale.
* Non-strict (init) still presence-checks the fallback core, so a fresh
* machine gets a best-effort core install instead of nothing.
*/
async function updateSkillsOffline(
requested: readonly string[],
opts: { strict: boolean; cwd?: string },
): Promise<Omit<UpdateSkillsResult, "retired">> {
if (requested.length === 0 && opts.strict) {
throw new Error(
"can't check skills freshness (GitHub manifest unreachable) — refusing to report success. Retry when online.",
);
}
const targets = [...new Set([...requested, ...FALLBACK_CORE_SKILLS])];
const present = new Set(presentSkills(targets, { cwd: opts.cwd }));
const absent = targets.filter((name) => !present.has(name));
console.log(
c.dim(
absent.length === 0
? "Skills freshness check unavailable (offline?) — installed skills found, continuing without a refresh."
: `Skills freshness check unavailable (offline?) — attempting a blind install of: ${absent.join(", ")}`,
),
);
if (absent.length > 0) {
await installSkills(absent, { cwd: opts.cwd, strict: opts.strict });
verifyInstalled(absent, opts);
}
return {
targets,
installed: absent,
current: [...present],
unknown: [],
presenceOnly: true,
};
}
// ── check ────────────────────────────────────────────────────────────────────
/** Print a labelled list of skills (nothing if empty), each line uniformly coloured. */
function printSkillSection(
result: SkillsCheckResult,
status: SkillDiff["status"],
title: string,
mark: string,
color: (s: string) => string,
filter: (s: SkillDiff) => boolean = () => true,
): void {
const items = result.skills.filter((s) => s.status === status && filter(s));
if (!items.length) return;
console.log();
console.log(` ${color(title)}`);
for (const s of items) console.log(` ${color(`${mark} ${s.name}`)}`);
}
function renderCheck(result: SkillsCheckResult): void {
const { summary } = result;
console.log();
console.log(c.bold("hyperframes skills"));
console.log();
if (!result.location) {
console.log(` ${c.dim("No HyperFrames skills found in the usual locations.")}`);
console.log(` ${c.accent("Install: npx hyperframes skills")}`);
console.log();
return;
}
console.log(` ${c.bold("Location")} ${c.dim(result.location)} ${c.dim(`(${result.agent})`)}`);
console.log();
const onDemandMissing = summary.missing - summary.coreMissing;
const parts = [c.success(`✓ ${summary.current} current`)];
if (summary.outdated) parts.push(c.warn(`↑ ${summary.outdated} outdated`));
if (summary.coreMissing) parts.push(c.warn(`◦ ${summary.coreMissing} core not installed`));
if (onDemandMissing) parts.push(c.dim(`◦ ${onDemandMissing} available on demand`));
if (summary.removed) parts.push(c.warn(`✗ ${summary.removed} removed upstream`));
console.log(` ${parts.join(" ")}`);
printSkillSection(result, "outdated", "Outdated:", "↑", c.warn);
printSkillSection(
result,
"missing",
"Core not installed (skills update installs these):",
"◦",
c.warn,
(s) => isCoreSkill(s.name),
);
printSkillSection(
result,
"missing",
"Available on demand (install with `hyperframes skills update <name>`):",
"◦",
c.dim,
(s) => !isCoreSkill(s.name),
);
printSkillSection(
result,
"removed",
"Removed upstream (renamed or dropped — no longer published):",
"✗",
c.warn,
);
// Removed-detection cross-references the upstream skills lock. If that lock is
// absent where we expect it (e.g. upstream moved its path), removed-detection
// silently reports zero — so warn rather than imply a clean "up to date".
if (result.lockMissing) {
console.log();
console.log(
` ${c.warn(`! Skills lock not found — can't check for skills removed upstream.`)}`,
);
console.log(
` ${c.dim(` (lock paths verified against ${SKILLS_CLI_LOCK_PATHS_VERIFIED_AT})`)}`,
);
}
console.log();
if (result.updateAvailable) {
console.log(` ${c.accent("Update: npx hyperframes skills update")}`);
} else {
console.log(` ${c.success("◇")} ${c.success("Installed skills are up to date")}`);
}
console.log();
}
const checkCommand = defineCommand({
meta: { name: "check", description: "Check whether installed skills are the latest version" },
args: {
json: { type: "boolean", description: "Output as JSON", default: false },
dir: { type: "string", description: "Skills directory to check (default: auto-detect)" },
source: {
type: "string",
description: "Where 'latest' comes from: local path, owner/repo, or URL",
},
},
async run({ args }) {
const result = await checkSkills({
dir: args.dir,
source: args.source,
});
if (args.json) console.log(JSON.stringify(withMeta(result), null, 2));
else renderCheck(result);
// This check just displayed a fresh verdict, superseding whatever the
// background nudge cached — invalidate so the next command's nudge agrees
// with what the user was just shown instead of a pre-check snapshot.
invalidateSkillsCache();
// Exit non-zero when installed skills are stale, so agents and CI can gate:
// hyperframes skills check || npx hyperframes skills update
if (result.updateAvailable) setCommandExitCode(1);
},
});
// ── externally managed installs ────────────────────────────────────────────────
/**
* `HYPERFRAMES_SKIP_SKILLS=1` means something other than this CLI owns the skills
* install: CI, tests, or a team that pins the skills to one commit. `init` and the
* background nudge already stand down for it; the install commands must too, or
* the router's trigger-time `skills update <workflow>` replaces a pinned install
* with the latest upstream skills (GH #5695).
*/
function skillsManagedExternally(): boolean {
return process.env["HYPERFRAMES_SKIP_SKILLS"] === "1";
}
const SKILLS_MANAGED_EXTERNALLY_NOTICE =
"HYPERFRAMES_SKIP_SKILLS=1: skills are managed externally, so the installed skills were left unchanged.";
/** The skip line for an externally managed install: JSON for agents, one dim line for humans. */
function reportSkillsManagedExternally(requested: readonly string[], json: boolean): void {
if (json) {
console.log(
JSON.stringify(
withMeta({ skipped: true, reason: SKILLS_MANAGED_EXTERNALLY_NOTICE, requested }),
null,
2,
),
);
return;
}
console.log(c.dim(SKILLS_MANAGED_EXTERNALLY_NOTICE));
}
// ── update ───────────────────────────────────────────────────────────────────
/**
* Positional skill names from argv, split into plain-slug names and rejected
* tokens — each name is spread into a spawn as a `--skill` value, so
* flag-like tokens are refused up front (the caller reports and exits).
*/
function requestedNamesFrom(positionals: readonly unknown[]): {
requested: string[];
rejected: string[];
} {
const names = positionals.map(String).filter((n) => n.length > 0);
return {
requested: names.filter((n) => PLAIN_SKILL_NAME.test(n)),
rejected: names.filter((n) => !PLAIN_SKILL_NAME.test(n)),
};
}
/** Result line(s) for `skills update` — JSON for agents, one calm line for humans. */
function reportUpdate(
result: UpdateSkillsResult,
requested: readonly string[],
json: boolean,
): void {
if (json) {
console.log(JSON.stringify(withMeta(result), null, 2));
return;
}
for (const name of result.retired) console.log(c.warn(retiredSkillNotice(name)));
if (result.installed.length > 0) {
console.log(
c.success(
`Installed/updated ${result.installed.length} skill(s): ${result.installed.join(", ")}`,
),
);
} else if (result.presenceOnly) {
// Freshness was never checked (offline degrade) — "up to date" would be a
// claim we can't back. Presence is all that was verified.
console.log(c.warn("Freshness unknown (GitHub unreachable) — verified presence only."));
} else {
console.log(c.success("Installed skills are already up to date."));
}
// The named skills are the caller's actual question ("is my skill ready?")
// — answer it explicitly, whatever the install had to do.
const ready = requested.filter((name) => !result.retired.includes(name));
if (ready.length) console.log(c.success(`◇ Ready: ${ready.join(", ")}`));
}
/**
* Failure line for `skills update`. In --json mode the failure must land on
* stdout as JSON (an agent piping to a parser gets structure, not clack
* prose); the human path keeps the clack error.
*/
function reportUpdateFailure(message: string, json: boolean): void {
if (json) {
console.log(JSON.stringify(withMeta({ error: message }), null, 2));
return;
}
clack.log.error(c.error(message));
}
const updateCommand = defineCommand({
meta: {
name: "update",
description:
"Update the core set plus every installed HyperFrames skill to the latest, and remove any no longer published. Pass skill names to also install those (how on-demand skills install) — without names it never expands a partial install",
},
// Mirror `check`'s flags: the prune step runs the same removed-detection, so it
// must respect the same overrides. Without these, `update`'s internal
// checkSkills() fell back to defaults — pruning the auto-detected install
// against the default manifest even when the user pointed `check` elsewhere.
args: {
json: { type: "boolean", description: "Output as JSON", default: false },
dir: {
type: "string",
description:
"Skills dir for removed-detection only — scopes the prune, not the install (default: auto-detect)",
},
source: {
type: "string",
description:
"Where 'latest' comes from for removed-detection (local path, owner/repo, or URL) — does not change the install source",
},
},
async run({ args }) {
const dir = args.dir;
const source = args.source;
// Positional skill names (e.g. `hyperframes skills update slideshow`) are
// the ONLY way update expands an install: each named skill is guaranteed
// present and current. A retired name installs nothing; the run says where
// its knowledge went and still refreshes the core set that carries it.
const { requested, rejected } = requestedNamesFrom(args._ ?? []);
if (rejected.length) {
reportUpdateFailure(`Invalid skill name(s): ${rejected.join(", ")}`, args.json === true);
setCommandExitCode(1);
return;
}
// Exit 0 without installing, pruning or touching the nudge cache: the pinned
// install is the one the caller wants, so the skill's step keeps working.
if (skillsManagedExternally()) {
reportSkillsManagedExternally(requested, args.json === true);
return;
}
// Targeted, not full-set: refresh the core set (entry skill + shared
// domain skills) plus whatever is already installed, plus anything named
// above. Without names a deliberate partial install stays partial
// (refreshed, but never expanded) — the on-demand skills install when
// named. This is where `init` and the stale-skills nudge both lead;
// pulling the complete skill set here is exactly what users complained
// about. Explicit full set: `hyperframes skills` or `npx skills add
// heygen-com/hyperframes --all`.
//
// Note: the upstream `skills add` CLI has no `--dir` flag (it installs into
// the resolved agent dirs), so `--dir` here scopes only the *prune* detection
// below, not the install. `--source` likewise drives where the prune's
// "latest" manifest comes from; the install always targets the canonical
// HyperFrames repo so `update` reliably refreshes the published skills.
//
// strict: this is the documented recovery path for the agent/CI contract
// `hyperframes skills check || hyperframes skills update`. If the install fails (no npx, `skills add` exits
// non-zero, a named skill still absent afterwards) it must exit non-zero
// too — otherwise the `||` chain passes while nothing actually changed.
try {
const result = await updateSkills({ requested, refreshInstalled: true, strict: true });
reportUpdate(result, requested, args.json === true);
} catch (err) {
reportUpdateFailure(`Update failed: ${(err as Error).message}`, args.json === true);
setCommandExitCode(1);
return;
}
// `skills add` never deletes, so a skill renamed or dropped upstream
// (e.g. a retired workflow skill) would linger forever. Prune
// skills the lock attributes to our source that the manifest no longer
// ships, so `check || update` fully reconciles the install to the manifest.
//
// Safety: `removed` only ever contains skills the lock records as installed
// from our source (see detectRemoved) — never a user's own or another
// source's skills. We remove in the exact scope detection attributed from,
// so we never reach into a scope we didn't inspect. Best-effort: cleanup
// failure doesn't fail the update — the install the CI contract gates on
// already succeeded.
try {
// `canonical: true` for the same reason the install's target selection
// uses it (see updateSkills) — and more urgently, because this branch
// DELETES. Without it, resolveLatestManifest takes the findRepoManifest
// shortcut: any `skills-manifest.json` within 16 parent dirs of cwd
// becomes "latest". HyperFrames' own repo manifest declares
// `source: heygen-com/hyperframes`, so a checkout (or any project
// carrying a copy) matches attribution and every published skill absent
// from that local file is deleted globally as "no longer published".
// An explicit `--source` still wins — canonical only decides what
// "latest" means when no source was given. GH #3111.
const { skills, scope } = await checkSkills({ dir, source, canonical: true });
const removed = skills.filter((s) => s.status === "removed").map((s) => s.name);
if (removed.length) {
console.log();
console.log(
c.dim(`Removing ${removed.length} skill(s) no longer published: ${removed.join(", ")}`),
);
await runSkillsRemove(removed, { global: scope === "global" });
// Self-heal: `skills remove` only clears a lock entry for a name it
// found an on-disk bundle for (see pruneOrphanedLockEntries). A skill
// retired before it ever shipped a bundle to this machine has none, so
// the call above is a silent no-op for it — the lock entry lingers and
// would be re-flagged "removed" on every future run. Prune whatever is
// still attributed after the call so `check || update` converges
// instead of looping forever. Best-effort and scoped to exactly the
// lock the remove above targeted (same `scope`); a write failure here
// must not fail the update — the install already succeeded.
const scopeForPrune = scope ?? "global";
const stillOrphaned = pruneOrphanedLockEntries(removed, scopeForPrune);
if (stillOrphaned.length) {
console.log(
c.dim(
`Reconciled ${stillOrphaned.length} orphaned lock entr${stillOrphaned.length === 1 ? "y" : "ies"} with no on-disk bundle: ${stillOrphaned.join(", ")}`,
),
);
}
}
} catch (err) {
clack.log.warn(c.warn(`Skipped removed-skill cleanup: ${(err as Error).message}`));
}
},
});
export default defineCommand({
meta: {
name: "skills",
description: "Install, check, and update HyperFrames skills for AI coding tools",
},
subCommands: {
check: checkCommand,
update: updateCommand,
},
args: {},
async run({ args }) {
// citty runs this parent handler even when a subcommand matches; guard on
// the positional so bare `hyperframes skills` installs, while
// `hyperframes skills check|update` does not also re-install.
if (!args._?.[0]) {
if (skillsManagedExternally()) {
reportSkillsManagedExternally([], false);
return;
}
await updateSkills({ all: true });
// Same as updateSkills: a full install supersedes the background
// nudge's cached pre-install verdict.
invalidateSkillsCache();
}
},
});