Skip to main content

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):

brew install skillshare
note

Homebrew releases can lag behind by a few days. For the latest, use the install script.

Install script (macOS / Linux):

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:

curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | INSTALL_DIR=/usr/local/bin sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/runkids/skillshare/main/install.ps1 | iex
Updating later

skillshare upgrade detects how you installed (Homebrew, script, manual) and updates the CLI in place.

2. Initialize​

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.
  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 <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​

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​

skillshare sync

Every configured target now points at your source.

5. Verify​

skillshare status
$ 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

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:

skillshare target <name> --mode copy
skillshare sync

See 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:

# 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:

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
FlagEffect
--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 mergeDefault sync mode for new targets
--no-copySkip the "copy existing target skills?" prompt; start empty
--no-skillSkip the built-in skill prompt

--targets, --all-targets, and --no-targets are mutually exclusive — pick one.

What's next​