---
name: skills-sync
description: Bootstrap ~/.claude/skills/* symlinks on a new machine, or bring existing ones up to date with their P4 depot source. Use whenever setting up Claude Code on a new machine for this project, or when a skill might be stale relative to its depot.
---

# Skills Sync / Bootstrap

Every skill used across the SDP development effort is a real, version-controlled directory
in a P4 depot -- never a loose, unversioned file under `~/.claude/skills/`. That directory
is just a folder of symlinks pointing at locally-synced copies of the real thing. The
manifest of what exists and where is `ai_dev_support/SKILLS_INDEX.md` (sibling to this
skill's own directory, in `//p4-sdp/dev`).

## Keeping already-set-up skills current

If `~/.claude/skills/<name>` already exists as a symlink into a real P4 client workspace,
just re-sync it:

```bash
bash <path-to-this-skill>/sync_skills.sh
```

This reads the manifest, and for each skill that's already symlinked on this machine, `cd`s
into the resolved target and runs `p4 sync .`. It deliberately skips anything not yet set
up here -- see below for that.

## Bootstrapping a new machine (e.g. a colleague getting set up for the first time)

This is a guided procedure, not a single script -- picking where a new P4 client's `Root`
lives, and whether to reuse an existing workspace vs. create a new one, are judgment calls
specific to that person's machine and existing setup, not safe to automate unattended.

For each skill in `SKILLS_INDEX.md` you want on this machine:

1. **Check for an existing local workspace already syncing that skill's stream.** Someone
   doing real development on that depot likely already has one:
   ```bash
   p4 -p <server-from-manifest> clients -u <your-p4-user> | grep -i <depot-name>
   ```
   If one exists and is rooted somewhere sensible, reuse it -- just `cd` there, `p4 sync`
   the skill's path if needed, and skip to step 4.

2. **If no workspace exists yet, create one.** Follow this project's convention: root it
   under `~/pub/<depot>` for anything on the Public Depot (`public.perforce.com:1666`), or
   `~/ppn/<workspace>` for anything on PPN (`ssl:ppn.perforce.com:1670`) -- see how the
   existing skills' workspaces are rooted for a concrete example
   (`p4 client -o <existing-client-name>` on any machine that already has one). A minimal
   stream client for just the skill's own depot path:
   ```bash
   p4 -p <server> --field "Root=<chosen-root>" client -S <stream> -o <new-client-name> | p4 -p <server> client -i
   ```

3. **Sync the skill's path:**
   ```bash
   cd <chosen-root> && p4 sync <depot-path-under-the-stream>/...
   ```

4. **Symlink it into place:**
   ```bash
   ln -s <chosen-root>/<path-to-skill-dir> ~/.claude/skills/<skill-name>
   ```

5. **Verify Claude Code picks it up** -- it should appear in the available-skills listing
   on the next turn (live change detection, no restart needed).

## Adding a new skill to the manifest

When you create a new skill anywhere in this effort, add a row to `SKILLS_INDEX.md`'s
table (`| name | server | depot path | purpose |`) so `sync_skills.sh` and future
bootstraps pick it up automatically -- don't let a skill exist only as an undocumented
symlink on one machine.