harness-tools/skills/tools/manage-pi-links/SKILL.md

name, description

name	description
manage-pi-links	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 as the source of truth and 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.