Problem

hyperframes skills update (and init and bare skills) runs npx skills add … --global --agent claude-code universal --copy --full-depth --yes. With --copy, every HyperFrames skill is written twice as real files: once to ~/.claude/skills and once to ~/.agents/skills.

The two copies cause practical problems:

• Drift between agents. Claude Code reads ~/.claude/skills, while Codex and Pi read ~/.agents/skills. A local fix or experiment applied to one copy changes behavior in one agent only. Nothing reports the mismatch until the next skills update overwrites both.
• Double storage. On my machine that's 13 skills and about 450 files (hyperframes-animation, hyperframes-creative and media-use are the large ones), stored twice.
• Mixed layouts. Users who manage other skills with the upstream default (a real copy in ~/.agents/skills plus a symlink in ~/.claude/skills) end up with two layouts in the same directory, and each skills update turns their symlinks back into copies.

--copy was added in #1744 (51f8231eb) because the symlink layout then re-serialized each SKILL.md's frontmatter, so skills check reported a fresh install as outdated. It also didn't reliably land in .claude/skills. Neither problem shows up with the current upstream CLI.

Proposed solution

Drop --copy from GLOBAL_INSTALL_ARGS_TAIL in packages/cli/src/commands/skills.ts on macOS and Linux, and keep it on Windows. With the current upstream skills CLI (1.7.2, which npx skills resolves to today), symlink mode gives the layout skills check and the mirror already expect:

• real files in ~/.agents/skills/<skill>;
• a relative symlink ~/.claude/skills/<skill> -> ../../.agents/skills/<skill>.

What I checked:

1. Byte-identical install. On a scratch HOME, I ran skills add <hyperframes checkout> --skill hyperframes --skill media-use --global --agent claude-code universal --full-depth --yes without --copy. It wrote real files to ~/.agents/skills and relative symlinks to ~/.claude/skills, and diff -r against skills/<skill> in the repo was empty for both skills. The frontmatter was not rewritten: upstream's copyDirectory only rewrites SKILL.md for the eve agent.
2. skills check passes through symlinks. On a real machine I replaced the 13 copies in ~/.claude/skills with relative symlinks to ~/.agents/skills. npx hyperframes@latest skills check reported them current. hashSkillBundle reads through the links, and listSubdirs/listSkillDirs already accept isSymbolicLink() entries.
3. Migration is automatic. Upstream's createSymlink removes an existing real directory at the link path before linking, so the first update after this change converts copy-mode installs in place.

Points to settle in the PR:

• mirrorGlobalSkills uses ~/.claude/skills as its source. In symlink mode each entry there is a link, so per-agent mirrors would chain one link onto another. Sourcing the mirror from ~/.agents/skills (the canonical store) avoids that. It also matches how UNIVERSAL_STORE_READERS already treats that store as authoritative.
• Windows: keep --copy, or rely on upstream's own junction fallback to a copy. skillsMirror.ts already copies instead of linking on win32 for the same reason.
• The test in packages/cli/src/commands/skills.test.ts that asserts --copy needs a platform-aware update.

Alternatives considered

• Keep --copy and document that local edits need applying to both stores. This is today's behavior, and it leaves the drift problem in place.
• Pin an older upstream version and keep --copy. This doesn't solve the duplication.
• Users symlink the stores by hand. This works until the next skills update, which removes the links and writes copies again. Every HyperFrames workflow runs that command when it starts, so a manual fix lasts one run.

Additional context

macOS 26 (Darwin 25.6), skills 1.7.2, hyperframes 0.8.164. Commands used for the scratch-HOME check:

HOME=$PWD/h npx skills add /path/to/hyperframes --skill hyperframes --skill media-use --global --agent claude-code universal --full-depth --yes
ls -la h/.claude/skills h/.agents/skills
diff -r h/.agents/skills/media-use /path/to/hyperframes/skills/media-use