autosync-ic-skills

What this skill does

# Set up self-updating Internet Computer skills

This skill installs a small amount of project configuration so that **every new
Claude Code session automatically downloads the latest Internet Computer skills**
into `.claude/skills/`, where Claude discovers and triggers them natively.

It is a **one-time installer**. After you complete the steps below, the user never
needs this link again — the installed `SessionStart` hook does the work from then on.

## What you will create

1. `.claude/sync-ic-skills.sh` — a **differential** sync script that mirrors the live
   skill index into `.claude/skills/`.
2. A `SessionStart` hook in `.claude/settings.json` that runs that script.
3. An immediate first run, so skills are present right away.

The script is a **differential mirror**. It fetches the discovery index once and
compares each skill's published `hash` against a stored manifest, re-downloading only
the skills that actually changed (and pruning ones removed upstream). Unchanged skills
are skipped with no per-file downloads, and the script stays silent unless something
changed. If the server does not publish a `hash` for a skill, the script falls back to
re-downloading it every run, so it remains correct either way.

## Important: tell the user what to expect

Adding a hook means a shell script will run automatically at the start of future
sessions. Claude Code will ask the user to **review and trust** the new hook before
it activates — this is expected and correct. Let the user know:

> "I'm adding a `SessionStart` hook that runs `.claude/sync-ic-skills.sh`. Claude Code
> will ask you to approve/trust it before it runs automatically. After that, your IC
> skills stay current on every session."

Do **not** attempt to bypass that approval.

## Step 0 — Check prerequisites (`curl`, `jq`)

The sync script needs `curl` (virtually always present) and `jq` (often not).
Before writing anything, check for them:

```bash
command -v curl >/dev/null 2>&1 && echo "curl: ok" || echo "curl: MISSING"
command -v jq   >/dev/null 2>&1 && echo "jq: ok"   || echo "jq: MISSING"
```

- If `jq` is **missing**, offer to install it (ask the user before running an install
  command). Pick the right one for their platform:
  - macOS (Homebrew): `brew install jq`
  - Debian/Ubuntu: `sudo apt-get update && sudo apt-get install -y jq`
  - Fedora/RHEL: `sudo dnf install -y jq`
  - Alpine: `apk add jq`
  - Arch: `sudo pacman -S --noconfirm jq`
  - Windows (winget): `winget install jqlang.jq`
- If the user declines, still proceed — the script is written to degrade gracefully
  (it exits cleanly with a warning when `jq` is absent), and they can install `jq`
  later and the next session will sync.

## Step 1 — Download the sync script

The script is published as a file alongside this skill, so you fetch it verbatim rather
than transcribing it (this guarantees byte-exact content). Create the `.claude` directory
and download it:

```bash
mkdir -p .claude
curl -fsSL https://skills.internetcomputer.org/.well-known/skills/autosync-ic-skills/scripts/sync-ic-skills.sh \
  -o .claude/sync-ic-skills.sh
```

Do **not** hand-write or paraphrase the script — always fetch the published copy so the
sync logic stays correct as it is updated upstream.

**What the script does** (for the user's awareness):

- Fetches `https://skills.internetcomputer.org/.well-known/skills/index.json` once.
- For each skill, compares the published `hash` against `.claude/skills/.ic-managed.json`
  (a `{ "<skill>": "<hash>" }` manifest of skills it manages) and re-downloads only the
  skills whose hash changed or are new.
- Prunes skills it previously installed that are no longer in the index.
- Prints a one-line `added / updated / removed` summary only when something changed;
  otherwise it is silent.
- Degrades gracefully: exits cleanly (keeping cached skills) if the network is down or
  `jq` is missing, and falls back to re-downloading skills the server publishes no
  `hash` for.

## Step 2 — Register the SessionStart hook (idempotently)

Add a `SessionStart` hook to `.claude/settings.json` that runs the script.

- If `.claude/settings.json` does **not** exist, create it with the content below.
- If it **does** exist, **merge** — preserve all existing keys, hooks, and
  permissions. Only add the `SessionStart` entry, and **only if an equivalent
  `bash .claude/sync-ic-skills.sh` command is not already present** (do not create a
  duplicate). Parse the existing JSON, insert into the `hooks.SessionStart` array,
  and write it back; never blindly overwrite the file.

The entry to ensure is present:

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "bash .claude/sync-ic-skills.sh" }
        ]
      }
    ]
  }
}
```

## Step 3 — Run it once now

Run the script immediately so the skills are available in this session without
waiting for the next session start:

```bash
bash .claude/sync-ic-skills.sh
```

## Step 4 — Verify and report

- Confirm `.claude/skills/` now contains skill directories (e.g. `motoko`,
  `asset-canister`, `internet-identity`, …) each with a `SKILL.md`.
- Confirm `.claude/skills/.ic-managed.json` maps each synced skill name to its hash.
- Tell the user: how many skills were installed, that the `SessionStart` hook is in
  place, and that they'll be prompted to trust the hook before it auto-runs next
  session. From then on, their IC skills refresh automatically every session.

## Notes

- **Safe to re-run.** Re-invoking this skill or the script is idempotent: the hook is
  not duplicated, and only skills tracked in `.ic-managed.json` are ever pruned.
- **Differential by hash.** The script keys off the per-skill `hash` field in the
  discovery index, so a normal session that touches nothing downloads only `index.json`
  and exits silently. Skills are re-downloaded only when their hash changes. Migrating
  from an older version of this script (whose manifest was a bare name array) is handled
  automatically on the next run.
- **Optional mid-session refresh.** For very long-running sessions, the user can also
  run `bash .claude/sync-ic-skills.sh` manually, or schedule it (e.g. via `/loop` or a
  cron routine) — but the SessionStart hook covers the normal case.