#2571

feat(agents): opt-in env overrides to target Pi's native skill directories

DraftTuxikwants to merge intofrom

Summary

Adds opt-in environment variables so the pi target can install skills into Pi's native skill directories (.pi/skills per project, ~/.pi/agent/skills globally) instead of the universal .agents/skills store, while keeping the current universal behavior as the untouched default.

  • PI_SKILLS_DIR — project-level skills dir for the pi target (default: .agents/skills)
  • PI_GLOBAL_SKILLS_DIR — global skills dir for the pi target (default: ~/.agents/skills)

Why not change the default?

#2316 deliberately reclassified Pi as a universal (.agents/skills) agent, and that fix is correct: Pi reads both ~/.agents/skills/ and ~/.pi/agent/skills/, so writing directly to the canonical store is the only arrangement that guarantees a single copy per skill. Flipping the default would reintroduce the double-listing problem that #2316 removed.

But some users (see #1024, which documents that Pi and Codex support the universal locations in addition to their native ones) want installs to land in the agent's own directories — e.g. to keep Pi's skill set self-contained under ~/.pi/agent/skills for backup, syncing, or pi-managed workflows.

Behavior

With the overrides unset (default), nothing changes: Pi stays universal and installs write to the canonical store.

When the overrides are set, pi becomes a non-universal target, so the existing install machinery takes over naturally:

  • the skill content is written once to the canonical store,
  • Pi's native directories receive symlinks into the canonical store (PI_SKILLS_DIR=.pi/skills PI_GLOBAL_SKILLS_DIR="$HOME/.pi/agent/skills" skills add <pkg> --agent pi -g).

This follows the existing per-agent env convention in src/agents.ts (CODEX_HOME, CLAUDE_CONFIG_DIR, HERMES_HOME, …). It is complementary to #1887, which relocates Pi's agent home (detection), while this PR redirects Pi's skill directories.

Note: with the overrides set, Pi may discover an installed skill through both the canonical dir and its native dir; the canonical store remains the single source of truth (native dirs are symlinks), so the copies can never diverge.

Tests

Extended tests/pi-agent.test.ts (the file added by #2316):

  • default paths and universal classification unchanged,
  • PI_SKILLS_DIR / PI_GLOBAL_SKILLS_DIR repoint the target and flip Pi to non-universal,
  • blank/whitespace values fall back to the defaults.

All 4 pass. pnpm exec tsc --noEmit and prettier are clean on the touched files.

3 pre-existing failures in src/detect-agent.test.ts occur on unmodified main as well when the suite is run from inside a Pi session (detectAgent() picks up the PI_* environment of the host session); they are unrelated to this change.

Activity

1

This pull request is a draft

Merging is unavailable until it is marked ready for review.