What

hyperframes skills, skills update and init stop passing --copy to npx skills add on macOS and Linux. The global install then uses upstream's symlink mode:

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

Windows keeps --copy.

Why

With --copy, every HyperFrames skill is written twice as real files, to ~/.claude/skills and to ~/.agents/skills.

• Drift between agents. Claude Code reads the first store; Codex and Pi read the second. A local edit or fix to one copy changes behavior in one agent only. Nothing reports the mismatch until the next skills update overwrites both.
• Double storage for every installed skill.
• Mixed layouts. Users who manage other skills with the upstream default get two layouts in the same directory, and each update replaces their links with copies.

--copy was added in #1744 because the symlink layout then rewrote each SKILL.md's frontmatter, so skills check reported a fresh install as outdated. Current upstream skills (1.7.2, which npx skills resolves to today) only rewrites SKILL.md for its eve agent. Symlink-mode installs now byte-match the published bundle.

Related work

Fixes #5704.

Refs #1744, which introduced --copy.

The issue also suggests sourcing mirrorGlobalSkills from ~/.agents/skills rather than ~/.claude/skills. This PR leaves that for a follow-up (see How).

How

• packages/cli/src/commands/skills.ts: the constant GLOBAL_INSTALL_ARGS_TAIL becomes globalInstallArgsTail(platform), which adds --copy only on win32. Windows symlinks need admin or Developer Mode, the same reason skillsMirror.ts copies there.
• packages/cli/src/utils/skillsMirror.ts: comments only. The mirror still reads from the Claude store. In symlink mode each entry there is a link, and the mirror's symlink checks compare realpaths, so they work through the links unchanged. Sourcing the mirror from ~/.agents/skills directly would avoid chained links; I left that out to keep this change small.
• Migration needs no code. Upstream's createSymlink removes a real directory at the link path before linking, so an existing copy-mode skill turns into a link the next time it's reinstalled.

Test plan

• Unit tests added/updated: packages/cli/src/commands/skills.test.ts builds the expected arguments per platform. linux and darwin omit --copy and win32 keeps it, and the skills update test asserts no --copy on Linux. npx vitest run src/commands/skills.test.ts src/utils/skillsMirror.test.ts: 59 passed.
• Manual testing performed, with the patched CLI (bun src/cli.ts) and HOME set to a scratch directory:
  • skills update cloned from GitHub and installed 10 skills as real files in ~/.agents/skills, with relative symlinks in ~/.claude/skills. skills check then reported "10 current".
  • Bare skills installed the remaining 11; skills check reported "21 current".
  • Migration: I replaced ~/.claude/skills/hyperframes-core with a real copy and changed one byte so it read as outdated. skills update reinstalled it as a symlink, and skills check reported "21 current".
  • On a real machine, skills check also reported 13 hand-symlinked skills as current, since hashSkillBundle reads through the links.
• oxfmt --check, oxlint, scripts/check-comment-citations.mjs and scripts/comment-ratchet.mjs pass on the changed files.
• Documentation updated: no docs describe the install layout beyond the changelog entry for fix(cli): install skills with --copy so check sees a faithful, correctly-placed set #1744.
• Comments follow CONTRIBUTING.md "Comments"