Skill linking (LINKING)

pocock-skills

Upstream skills repo (fork of mattpocock/skills). Each top-level dir = one skill (contains SKILL.md).

Skill linking

Skills deploy via symlinks declared in a per-machine manifest.

• links.example.toml — gitignored; local bootstrap scaffold copied to links.local.toml when absent.
• links.local.toml — gitignored; source of truth for intent on this host.

Entry: { skill, target } → symlink <target>/<skill> → first existing of <repo>/<skill> or <repo>/skills/*/<skill> (any bucket). Expand ~ in target. If a skill resolves under multiple buckets, prefer non-deprecated; if still ambiguous, fail loudly and require the manifest entry to disambiguate via <bucket>/<skill>.

Protocol

• Bootstrap: if links.local.toml absent, copy from links.example.toml, notify user.
• Link X→Y: append entry; ln -s <repo>/X <Y>/X (ensure <Y> exists; refuse if <Y>/X exists).
• Unlink X from Y: remove entry; rm <Y>/X only if it is a symlink into this repo.
• Reconcile/drift: for each entry, verify <target>/<skill> is a symlink to <repo>/<skill> — create if missing, report if mismatched or a real file/dir. Scan known targets for orphan symlinks into this repo not in manifest; report. Report before mutating unless user said apply.

Report

On request (“status”, “what’s linked”), print every skill in the repo, one line each, column-aligned: <skill> → <target> [status]. Status: [ok], [missing], [drift]. For unlinked skills (no manifest entry), use — as target and omit the status tag. Sort alphabetically. Append orphan symlinks (into repo but not in manifest) below, labelled [orphan].

Safety

Never delete non-symlinks. Never overwrite existing paths. Always expand ~. When unsure, dry-run and ask.