fix(skills): skip mirror fan-out to agents that read the universal store

[santhiprakash]

What

The global skills mirror no longer fans out into agent directories whose agent already discovers the universal ~/.agents/skills store globally. Currently that set is { pi }.

Why

Pi discovers skills from both ~/.pi/agent/skills/ and ~/.agents/skills/ as global locations (see pi's packages/coding-agent/docs/skills.md → Locations). The global install already writes real files into the universal store, so mirroring an additional per-agent copy into ~/.pi/agent/skills makes Pi discover every HyperFrames skill twice. Pi then reports a name collision, keeps the ~/.pi/agent/skills entry, and skips the universal entry:

"hyperframes" collision:
  ✓ auto (user) ~/.pi/agent/skills/hyperframes/SKILL.md
  ✗ ~/.agents/skills/hyperframes/SKILL.md (skipped)

Fixes #3294 (the deterministic duplicate-discovery half; the broader target-control surface proposed there is left for maintainers to design).

How

• Added a UNIVERSAL_STORE_READERS capability set in packages/cli/src/utils/skillsMirror.ts (currently pi) and skip those agents in the fan-out loop, before the installed-marker check.
• The set deliberately lives in the mirror module, not in agentDirs.generated.ts: that file is @generated from vercel-labs/skills and a plain (agent, base, sub) list — it cannot carry per-agent capabilities, and any hand edit would be clobbered by the next gen:agent-dirs sync.
• Minimal by design: no cleanup of pre-existing ~/.pi/agent/skills entries from earlier runs. Removing entries in a directory we no longer manage would risk deleting user-placed content (the mirror's replace-on-refresh precedent only applies to dirs it still mirrors). A one-time stale-link cleanup can be a follow-up if maintainers want it.

Test plan

• New test in skillsMirror.test.ts: with both Pi (~/.pi/agent) and cursor markers present, mirrored contains cursor and not pi, and no ~/.pi/agent/skills/hyperframes entry is created.
• Full skills-related suites pass: skillsMirror, skillsManifest, skillsUpdateCheck, commands/skills — 116/116.
• oxlint / oxfmt --check clean on changed files; repo check-skill-mirror invariant still passes; lefthook pre-commit gates (format, fallow against synced main, typecheck after generating core runtime artifacts) pass.
• Manual testing performed (not applicable here — reproduction requires a Pi + HyperFrames co-install; covered by the deterministic unit test above)

[miga-heygen]

LGTM — clean, minimal fix.

The problem is well-defined: Pi discovers ~/.agents/skills natively, so the mirror's per-agent fan-out created a duplicate that Pi resolved by keeping the per-agent copy and skipping the universal one — the wrong winner.

The fix is a single continue in the fan-out loop gated on a UNIVERSAL_STORE_READERS set. Good design choices:

• Set lives in skillsMirror.ts, not in agentDirs.generated.ts. The generated file is a plain (agent, base, sub) list synced from vercel-labs/skills — it can't carry per-agent capabilities, and a hand edit would be clobbered. Correct placement.
• No stale-entry cleanup. Removing entries in a directory the mirror no longer manages risks deleting user-placed content. The replace-on-refresh precedent only applies to dirs still mirrored. Right call.
• Test is specific. Seeds both Pi and Cursor markers, asserts Pi is excluded and Cursor included, verifies no ~/.pi/agent/skills/hyperframes entry was created. Covers both the positive and negative cases.

No SSOT concerns — the skip check is one line, one source of truth for which agents are universal-store readers, and the comment explains the invariant it protects.

Review by Miga

[miguel-heygen]

@santhiprakash sign the commit pls

[santhiprakash]

Done — commits are now signed. You should see the Verified badge on the latest commit.