Start with the version and the command's own help:
skl --version
skl <command> --help
Command not found
Open a new terminal so your shell picks up skl. Then check where it is with which skl, or where.exe skl on Windows. If it isn't there, run the installer again.
Update fails or leaves a broken binary
Install over it. Your login and settings stay.
curl -fsSL https://install.skillsync.com/install.sh | sh
irm https://install.skillsync.com/install.ps1 | iex
A tool's sessions are missing
skl list
skl list --from <agent>
Check the tool is in Session compatibility, and that it has sessions on this machine. Claude Chat, ChatGPT and Cloud Cowork only show up with --from.
On macOS, a terminal without Full Disk Access can't read some session folders. Turn it on in System Settings and restart the terminal.
Session not found
Get the id back with skl list or skl query "part of the title". If two tools have ids that look alike, add --from <agent>.
Query misses something
Drop --cwd and --from first. skl query matches the text exactly as typed, spaces included. To ask in your own words, use skl search.
Search doesn't answer
skl whoami
skl keys
Search needs you signed in, and a Skillsync plan or your own keys. skl keys shows which one it's running on. With your own keys and no answers key, it finds sessions and writes no answer.
skl search isn't on Windows yet.
The plugin does nothing
skl plugin status
This shows which tools have the plugin, and whether it's skl's or the Skillsync app's. The plugin needs what search needs. It skips short replies and slash commands, and gives up after 30 seconds.
Continue doesn't open anything
The tool you're continuing into has to be installed and on your PATH. Check the session converts on its own:
skl continue <id> --with <agent> --no-resume
Some tools can't be continued into. See Session compatibility.
Can't sign in
skl whoami
skl login
skl login --device
Use --device over SSH or when the browser sign-in doesn't finish. If SKL_TOKEN is set, skl uses it instead of your saved login, and skl logout can't clear it.
A session won't sync
skl sync <id> --dry-run
This says why. The usual reasons are in What won't sync.
If the shares look wrong, a re-sync without --workspace or --private keeps the old ones. Pass the flag you mean.
A synced session can't be found
A local id only works on the machine that synced it. Anywhere else, use the slug:
skl remote list
skl remote open <slug>
A skill won't install
skl whoami
skl skills show <ref>
If the skill is already installed, skl won't replace it without asking. Pass --force when you mean to.
A skill won't publish
skl skills upload <skill> --dry-run
The skill needs a SKILL.md with a description in its frontmatter and a body. Add --project for a skill in the current project.
An MCP client can't connect
A command is missing
Run skl update, then skl --help. skl memory, skl bookmark and skl remote set-default were removed in 0.36. skl upload, skl auto and skl watch don't exist.