35 lines
3.3 KiB
Markdown
35 lines
3.3 KiB
Markdown
---
|
|
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.
|