Files
Charitarth ChughandClaude Opus 5.5 64c8a3f34e feat: add Nix flake and handle Nix-store installs in upgrade (#764)
* feat: add Nix flake and stop self-upgrade of Nix-store installs

Add flake.nix with packages, overlays.default, checks and a formatter,
building nix/package.nix with the unit tests in the Nix sandbox. The
version comes from the Release Please manifest, so releases need no Nix
edit. A Nix workflow runs `nix flake check` on non-docs changes.

`skillshare upgrade` now detects binaries under /nix/store/ and prints
`nix profile upgrade skillshare` instead of replacing a read-only store
path; update notices and doctor suggest the same command.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(upgrade): give Nix installs the right update path everywhere

The first flake commit sent every /nix/store binary to `nix profile
upgrade`, failed a plain `skillshare upgrade` with exit 1 even when the
CLI was current, and left the dashboard with a generic 500.

- Tell `nix profile` installs (the profile manifest lists the store path)
  from NixOS, Home Manager and overlay installs, which are told to update
  their configuration and rebuild. Detection lives in one helper shared by
  the update notice, doctor, upgrade and the dashboard.
- `upgrade` on Nix reports "already up to date" or prints the hint and
  exits 0; the built-in skill still updates.
- The dashboard runs the upgrade so the skill updates, then answers
  409 `upgrade.nix` with the command when a newer CLI waits on Nix. The
  UI shows localized text for it in all 11 locales.
- Installs skip the unit tests; the flake's checks enable them. postPatch
  lowers only the go directive's patch version and fails evaluation with
  a clear message when go.mod needs a newer Go minor. CI also builds the
  package on macOS.
- Docs, translations, the built-in skill reference and the release topic
  describe the new behaviour.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 15:53:57 +08:00

223 lines
8.1 KiB
Markdown

---
sidebar_position: 2
---
# First Sync
A complete first-time setup, in order. Roughly five minutes from install to a working sync. Two variations — restoring on another machine, and running unattended on a headless box — are documented at the end of this page.
## Prerequisites
- macOS, Linux, or Windows
- At least one AI CLI installed (Claude Code, Pi, Codex, etc.)
## 1. Install the CLI
**Homebrew (macOS / Linux):**
```bash
brew install skillshare
```
:::note
Homebrew releases can lag behind by a few days. For the latest, use the install script.
:::
**Install script (macOS / Linux):**
```bash
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh
```
The script installs to `~/.local/bin` by default, so normal installs and updates do not need `sudo`. If the installer prints PATH setup instructions, follow them before running `skillshare`. Add the suggested line to your shell config (such as `~/.zshrc` or `~/.bashrc`) for future terminals. Set `INSTALL_DIR` to use another location.
Existing installations are not moved or removed. If an older binary takes precedence in PATH, the installer reports its location; put the new installation first in PATH to use it. A protected custom directory can still require `sudo`.
For a system-wide installation:
```bash
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | INSTALL_DIR=/usr/local/bin sh
```
**Windows (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/runkids/skillshare/main/install.ps1 | iex
```
**Nix (Linux / Apple Silicon macOS):**
```bash
nix profile add github:runkids/skillshare
```
Update with `nix profile upgrade skillshare`. Requires Nix 2.30+ with flakes enabled; on older Nix or Lix, use `nix profile install`. For NixOS or Home Manager, add the flake as an input and use its overlay:
```nix
# flake.nix
inputs.skillshare.url = "github:runkids/skillshare";
# NixOS or Home Manager module
nixpkgs.overlays = [ inputs.skillshare.overlays.default ];
environment.systemPackages = [ pkgs.skillshare ]; # or home.packages
```
:::tip Updating later
`skillshare upgrade` detects how you installed (Homebrew, script, manual) and updates the CLI in place. For a Nix install, it leaves the CLI to Nix and says how to update it: `nix profile upgrade skillshare` for a `nix profile` install, or a rebuild of your NixOS or Home Manager configuration.
:::
## 2. Initialize
```bash
skillshare init
```
<p>
<img src="/img/init-demo.png" alt="skillshare init: answered questions, the summary, and the first sync" width="720" />
</p>
`init` asks a few short questions, shows a summary, and writes nothing until you confirm:
1. **How to start** — a new setup on this machine, or [connect your existing skillshare repo](/docs/how-to/sharing/cross-machine-sync#second-machine-setup).
2. **Targets** — every detected AI CLI is checked. Press Space to leave one out.
3. **Import** — skills already in those tools are copied into source.
4. **Git** — on by default, so you can push your skills to a repo later.
5. **Remote** — paste the URL of your skills repo (e.g. `git@github.com:you/skills.git`), or press Enter to skip and add one later.
The summary also shows the source directory (`~/.config/skillshare/skills/`), the sync mode, and the built-in skill, which adds a `/skillshare` command to your AI CLIs. Choose **Change settings** to edit them, or press <kbd>Esc</kbd> to cancel. After you confirm, `init` offers to sync right away.
### Choosing a sync mode
`init` accepts `--mode <merge|copy|symlink>` to set the default for newly-added targets:
- `merge` (default) — per-skill symlinks; pre-existing target-local skills are preserved
- `symlink` — the whole target directory becomes one symlink (fastest, replaces the directory)
- `copy` — real files; changes apply on the next `sync`
Per-target overrides are available later via `skillshare target <name> --mode <mode>`.
## 3. Install a skill
```bash
skillshare install anthropics/skills/skills/pdf
```
Every install runs a security audit. Critical findings block the install; pass `--force` only when you've reviewed and accept the risk.
## 4. Sync
```bash
skillshare sync
```
Every configured target now points at your source.
## 5. Verify
```bash
skillshare status
```
```text
$ skillshare status
Source
skills ~/.config/skillshare/skills 43 skills
agents ~/.config/skillshare/agents 2 agents
Targets skills agents
claude ~/.claude/skills ✓ 43 linked ✓ 2
cursor ~/.cursor/skills ✓ 43 linked ✓ 2
gemini ~/.gemini/skills ✓ 43 linked —
all use merge
```
The output shows the source path and every target. A synced target shows `✓` and how many skills it links, including the one you just installed.
The dashboard (`skillshare ui`) shows the same state at a glance:
![Dashboard after the first sync: one source connected to every target, all in sync](/img/web-dashboard-demo.png)
---
## What just happened
1. **`init`** created `~/.config/skillshare/config.yaml` and `~/.config/skillshare/skills/`, auto-detected your AI CLIs, and — if you supplied a remote — cloned any pre-existing skills from it.
2. **`install`** cloned the skill into the source directory and ran a security audit. `.metadata.json` records the upstream URL and commit so `skillshare update` can pull future changes.
3. **`sync`** applied each target's configured mode. For example, in `merge` mode:
```
~/.claude/skills/pdf → ~/.config/skillshare/skills/pdf (symlink)
```
In `merge` and `symlink` modes, edits to source appear instantly in every target. In `copy` mode they apply on the next `sync`. Pre-existing target-local skills are preserved in `merge` and `copy`; `skillshare backup` snapshots before destructive operations and `skillshare restore <target>` reverts.
Need a different mode for one target only? Override per target:
```bash
skillshare target <name> --mode copy
skillshare sync
```
See [Sync Modes](/docs/understand/sync-modes) for the full decision matrix.
---
## Variation: restoring on another machine
You already use skillshare elsewhere and have a personal skills repo on GitHub. On a new laptop, devcontainer, or VM, four commands restore everything — no prompts, no choices, idempotent on re-run:
```bash
# 1. Install the CLI (Homebrew or curl|sh — same as Step 1 above)
brew install skillshare
# 2. Clone your skills repo and add detected targets
skillshare init \
--remote git@github.com:<you>/skills.git \
--all-targets \
--no-skill
# 3. Re-install tracked dependencies
# (the _-prefixed dirs are gitignored, so they aren't in the cloned repo)
skillshare install https://github.com/<your-company>/skills --track --force
# 4. Sync
skillshare sync
```
`--no-skill` leaves out the built-in skill; add it later with `skillshare upgrade --skill` if you want it on this machine.
---
## Variation: headless setup (no TTY)
For CI jobs, devcontainer post-create hooks, or cloud-VM provisioners, every prompt has a non-interactive flag:
```bash
skillshare init \
--source ~/.config/skillshare/skills \
--remote https://github.com/<you>/skills \
--targets codex \
--mode merge \
--no-copy \
--no-skill
skillshare install https://github.com/<your-company>/skills --track --force
skillshare sync
```
| Flag | Effect |
|---|---|
| `--source <path>` | Skip the source-path prompt |
| `--remote <url>` | Skip the remote prompt; clone if remote has content |
| `--targets <name>` | Add only the listed targets (use `--all-targets` to add every detected one) |
| `--mode merge` | Default sync mode for new targets |
| `--no-copy` | Skip the "copy existing target skills?" prompt; start empty |
| `--no-skill` | Skip the built-in skill prompt |
`--targets`, `--all-targets`, and `--no-targets` are mutually exclusive — pick one.
---
## What's next
- [Create your own skill](/docs/how-to/daily-tasks/creating-skills)
- [Sync across machines](/docs/how-to/sharing/cross-machine-sync)
- [Organization-wide skills](/docs/how-to/sharing/organization-sharing)
- [Agents](/docs/understand/agents) — manage single-file `.md` agents alongside skills
- [Sync modes](/docs/understand/sync-modes) — decision matrix and trade-offs