---
name: manage-pi-links
description: Reconcile harness-tools' repository-managed Pi resources. Use in this repository when asked to check, sync, repair, install, or prune skill links, extension links, or local-path Pi package entries.
---

# Manage Pi Links

Treat [`config/pi-links.json`](../../../config/pi-links.json) as the source of truth and [`scripts/pi-links.mjs`](../../../scripts/pi-links.mjs) as the only mutation interface. Keep this skill repository-local; its own exposure is the relative `.pi/skills/manage-pi-links` link.

## Classify the request

- For inspection, status, or troubleshooting, run `./scripts/pi-links.mjs check` and report every drift or conflict.
- For sync, repair, or installation, run `./scripts/pi-links.mjs sync --dry-run` first. Apply with `./scripts/pi-links.mjs sync` only when the request authorizes global changes.
- For pruning, run `./scripts/pi-links.mjs prune --dry-run`, show every removal, and obtain explicit confirmation before running `./scripts/pi-links.mjs prune`.
- For a new resource, update the manifest classification before synchronization. Skills are discovered automatically; list repository-only skills under `skills.projectOnly` and intentionally unavailable skills under `skills.excluded`. List global instruction files under `instructions.globalSymlinks`. List global extension directories under `extensions.globalSymlinks` or extension files under `extensions.globalLocalPackages`.

## Reconcile

1. Run commands from the repository root.
2. Read the manifest entry and the resource's `SKILL.md` or `index.ts` when diagnosing a mismatch.
3. Resolve manifest validation errors before applying changes. Require unique skill names and existing entry points.
4. Preserve collisions. The manager refuses regular files, directories, and links whose targets are outside this repository; report these for a human decision instead of replacing them manually. For an explicitly approved repository relocation, use `sync --dry-run --migrate-from /absolute/old/root`, inspect the repairs, then `sync --migrate-from /absolute/old/root`. This only repairs manifest-declared destinations whose old target exactly matches the same repository-relative source under that old root. It does not migrate stale/unlisted links or local packages, and cannot be used with `prune`. Finish with a normal `check` without the migration option.
5. Apply the authorized operation through `scripts/pi-links.mjs`.
6. Run `./scripts/pi-links.mjs check` again. Completion requires exit code zero.
7. Tell the user to run `/reload` when skill or extension exposure changed in the active Pi session.

## Exposure conventions

- Link shared global instructions into Pi's `AGENTS.md`, Codex's `AGENTS.md`, and Claude's `CLAUDE.md`; use a Claude import file when Claude should reference the shared instructions rather than link to them directly.
- Link globally shared skills into `~/.agents/skills/` for cross-harness discovery.
- Link repository-only skills into `.pi/skills/` with relative targets.
- Link live-development Pi extensions into `~/.pi/agent/extensions/` with absolute targets.
- Register manifest-declared local package files through `pi install`; let the manager invoke Pi rather than editing `~/.pi/agent/settings.json` directly.
- Prune only repository-owned exposure discovered by the manager. Leave unrelated global resources untouched.