--- 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 ```

skillshare init: answered questions, the summary, and the first sync

`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 Esc to cancel. After you confirm, `init` offers to sync right away. ### Choosing a sync mode `init` accepts `--mode ` 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 --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 ` reverts. Need a different mode for one target only? Override per target: ```bash skillshare target --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:/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//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//skills \ --targets codex \ --mode merge \ --no-copy \ --no-skill skillshare install https://github.com//skills --track --force skillshare sync ``` | Flag | Effect | |---|---| | `--source ` | Skip the source-path prompt | | `--remote ` | Skip the remote prompt; clone if remote has content | | `--targets ` | 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