Files
skillshare/website/docs/getting-started/quick-reference.md
T
Willie 5d269e8e4c feat(push): add --pull for two-way sync in one command (#354)
* feat(push): add --pull for two-way sync in one command

Users editing skills on several machines have to remember push on one and pull on the other, and a push from a machine that is behind fails until they pull first. push --pull commits local changes, merges the remote with the same merge semantics pull uses, pushes, and syncs the git root scope.

A conflict stops before anything is pushed and keeps the local commit; a target sync failure after a successful push is reported separately so the user knows the remote is already updated. It never rebases or force-pushes. commit rejects --pull instead of silently ignoring it, since both commands share the argument parser.

* docs(push): document push --pull across guides and translations

Cover the new flag on the push reference, the cross-machine sync guide, the quick reference, the daily workflow and the cross-machine recipe, in English and the ja, ko, zh-Hans and zh-Hant translations, plus the built-in skill's sync reference.

* fix(push): print the scope's sync command when --pull sync fails

A bare 'skillshare sync' retry hint defaults to skills and may pick project mode, so it does not redo an agents, extras, or root sync. Derive both the sync and the hint from one per-scope list.

* fix(pull): sync extras for the root git scope

The root scope versions skills, agents and extras, but pull and push --pull only synced skills and agents, so merged extras changes never reached their targets.

* fix(server): sync extras after a root-scope pull

The root scope versions extras too, but the dashboard pull only synced skills and agents, so merged extras never reached their targets. Matches the CLI fix.

* feat(ui): add a Sync both ways action to Git Sync

Mirrors skillshare push --pull: commit local changes, merge the remote and sync targets, then push, in one click. A pull conflict stops at the existing review before anything is pushed.

* feat(ui): confirm Sync both ways and list what it will do

Sync both ways commits, merges and pushes in one click, so ask first and show the concrete outcome (files to commit, remote commits to merge, scope, push target, conflict behavior) before changing anything.

* fix(ui): make Sync both ways match push --pull

It skipped target sync when the pull was already up to date, stopped on an empty remote instead of pushing, and the pull dropped extras warnings. Add alwaysSync and a remote_empty code to /api/pull and surface all extras warnings.
2026-10-03 18:53:08 +08:00

8.3 KiB

sidebar_position
sidebar_position
4

Quick Reference

Command cheat sheet for skillshare.

Core Commands

Command Description
init First-time setup
install <source> Add a skill
uninstall <name>... Remove one or more skills
list List all skills
search <query> Search for skills
sync Push to all targets
status Show sync state

Skill Management

Command Description
new <name> Create a new skill
update <name> Update a skill (git pull)
update --all Update all tracked repos
check Check for skill updates
check --json Check for updates (JSON output)
upgrade Upgrade CLI and built-in skill
hub list List configured skill hubs
hub add <url> Add a skill hub

Target Management

Command Description
target list List all targets
target <name> Show target details
target <name> --mode <mode> Change sync mode
target add <name> <path> Add custom target
target remove <name> Remove target safely
diff [target] Show differences

Extras Management

Command Description
extras init <name> --target <path> Add an extras entry to config
extras init <name> --file <file> --target <path> Add an extra that syncs one file (--as renames it at targets)
extras list List configured extras with sync status
extras remove <name> Remove an extras entry from config
extras <name> --add-target <path> Add a target to an existing extras entry
extras <name> --remove-target <path> Remove a target (add --prune to delete synced files)
extras collect <name> Collect local files from extras target into source

Agent Management

Command Description
list agents List installed agents
install <source> --kind agent Install only agents from a repo
install <source> -a <name> Install specific agent(s) by name
uninstall --kind agent <name> Remove an agent
sync agents Sync only agents to targets
check agents Check agents for updates
audit agents Security scan agents
enable --kind agent <name> Re-enable a disabled agent
disable --kind agent <name> Disable an agent via .agentignore

Plugin Management

Command Description
plugin Open the interactive plugin manager
plugin list Show managed plugins and native installation state
plugin discover <source> Inspect a directory or Git repository
plugin add [source] Install a complete native plugin
plugin import [plugin@market] --from claude Adopt an existing native installation
plugin inspect <name> Inspect a managed package
plugin check [name] Check source changes without applying
plugin update [name] --target claude Update a supported target from a reviewed source
plugin enable [name] --target codex Select a target for the next sync
plugin disable [name] --target codex Deselect a target for the next sync
plugin remove [name] Uninstall managed bindings and remove definitions
sync plugins [name] Apply plugin sync selection; alias for plugin sync

Targets: Claude Code, Codex, Cursor, Antigravity (agy), Pi, and OpenCode. Project mode supports Claude, Antigravity, Pi, and OpenCode.

Enable/disable only saves the selection. The next plugin sync installs selected bindings or uninstalls deselected bindings while retaining their definitions. Plugins are excluded from sync --all. Use --dry-run --json to preview mutations; use --no-tui with explicit inputs for automation. See plugin for native client requirements and supported targets.

Sync Operations

Command Description
sync extras Sync non-skill resources (rules, commands, etc.)
sync mcp Sync MCP connection settings
hooks list List managed native hooks
sync hooks Sync native hooks without executing them
sync --all Sync skills + agents + extras + MCP + hooks (excludes plugins)
collect <target> Collect skills from target to source
collect --all Collect from all targets
backup [target] Create backup
backup --list List backups
restore <target> Restore from backup
commit [-m "msg"] Create a local git commit without pushing
push [-m "msg"] [--pull] Commit and push to git remote; --pull merges remote changes first, then syncs
pull Pull from git and sync
trash list List soft-deleted skills
trash restore <name> Restore a soft-deleted skill

Utilities

Command Description
analyze Analyze context window usage (interactive TUI)
analyze --filter <text> Filter skills by name/path substring
analyze --json Context usage as JSON
doctor Diagnose issues
doctor --json Diagnose issues (JSON output for CI)
log View operations and audit logs
ui Launch web dashboard on localhost:19420
ui -p Launch web dashboard in project mode
completion <shell> --install Install shell tab-completion (bash/zsh/fish/powershell/nushell)
version Show CLI version
make test-docker Run offline Docker sandbox tests
make playground Start playground + enter shell (one step)
make playground-down Stop and remove playground
./scripts/sandbox.sh <cmd> Advanced sandbox management (up/down/shell/reset/status/logs/bare)
make ui-build Build frontend
make build-all Full binary with frontend

Common Workflows

Install and sync a skill

skillshare install anthropics/skills/skills/pdf
skillshare sync

Create and deploy a skill

skillshare new my-skill
# Edit ~/.config/skillshare/skills/my-skill/SKILL.md
skillshare sync

Cross-machine sync

# Setup (pick one)
# Interactive (guided prompts)
skillshare init --remote git@github.com:you/my-skills.git

# Non-interactive (no prompts, auto-detect installed targets)
skillshare init --remote git@github.com:you/my-skills.git --no-copy --all-targets --no-skill

# Optional local checkpoint without pushing
skillshare commit -m "Save local skill edits"

# Machine A: push changes
skillshare push -m "Add new skill"

# Machine B: pull and sync
skillshare pull

# Editing on several machines: both ways in one command
skillshare push --pull -m "Update skills"

Optional later (only if you install additional AI CLIs after setup):

skillshare init --discover

With mode override during discover, only newly added targets are affected:

skillshare init --discover --select cursor --mode copy

Team skill sharing

# Install team repo
skillshare install github.com/team/skills --track

# Install from specific branch (works with or without --track)
skillshare install github.com/team/skills --branch develop --all
skillshare install github.com/team/skills --track --branch develop

# Pin to a tag or commit SHA (regular install only)
skillshare install github.com/team/skills --branch v1.2.0 --all

# Update from team
skillshare update --all
skillshare sync

Sandbox playground session

make playground          # start + enter shell
skillshare --help
ss status
exit                     # leave shell
make playground-down     # stop container

Key Paths

Path Description
~/.config/skillshare/config.yaml Configuration file
~/.config/skillshare/skills/.metadata.json Installed skill metadata (auto-managed)
~/.config/skillshare/skills/ Skill source directory
~/.config/skillshare/agents/ Agent source directory
~/.config/skillshare/extras/<name>/ Extras source directories
~/.local/state/skillshare/logs/ Operation and audit logs
~/.local/share/skillshare/backups/ Backup directory

Flags Available on Most Commands

Flag Description
--dry-run, -n Preview without making changes
--help, -h Show help

See Also