Avoid duplicate HEY skills in Codex

Merged
AL
2mo ago
+424-125

Closes #287.

Problem

Current Codex discovers personal skills from ~/.agents/skills, so copying the same HEY skill into ~/.codex/skills creates two indistinguishable entries.

Change

  • Make the shared Agent Skills location the single source used by Codex.
  • Stop creating a second Codex-specific skill copy.
  • Update Codex setup, health checks, refresh behavior, and documentation to use the shared path.
  • During explicit setup and once-per-version refresh, remove an older Codex-specific copy only when hey-cli's ownership marker proves it is managed.
  • Preserve unmarked user-authored copies.
  • Preserve a managed legacy copy until the shared replacement has been installed and verified healthy.

The existing hey setup agents --remove path remains the supported uninstall flow. This PR does not change skill invocation policy; HEY remains available for normal implicit selection.

Verification

  • TMPDIR=/tmp go test ./internal/...
  • TMPDIR=/tmp go test ./internal/cmd ./internal/harness ./skills
  • go vet ./...
  • formatting and tidy checks
  • command-surface check
  • golangci-lint: 0 issues

The short TMPDIR avoids unrelated Unix-domain socket path-length failures in macOS TUI tests.

Summary by cubic

Stops Codex from seeing duplicate HEY skills by making the shared ~/.agents/skills location the single source. Setup, hey skill install, health checks, and version refresh no longer copy the skill into ~/.codex/skills; Codex discovers the shared skill directly.

Migration

  • Removes an existing legacy ~/.codex/skills/hey copy only during explicit setup or once-per-version refresh, and only when the ownership marker proves hey-cli created it and the shared replacement is healthy.
  • Leaves unmarked user-authored copies untouched, and keeps the legacy copy if installing or refreshing the shared skill fails.
  • Skips removal when CODEX_HOME aliases ~/.agents, so the shared skill is never deleted as its own legacy copy.
  • A managed legacy duplicate makes the Codex health check fail with a hint to run hey setup codex.
  • hey setup agents --remove remains the supported uninstall flow.