Start by checking the installed version and command-specific help:
skl --version
skl <command> --help
Command not found
Open a new terminal after installation so your shell reloads PATH. Then locate the binary:
which skl
On Windows PowerShell:
where.exe skl
If needed, run the installer again or use skl update from a shell where the command is already available.
Session source is missing
First check whether the source appears without filters:
skl list
skl list --from <agent>
Confirm that the agent's session store exists and is readable by the current user. Common locations are listed in /docs/transcript-support.
On macOS, terminals without Full Disk Access may be unable to read session files under protected directories. Grant access to the terminal application in System Settings, then restart it.
Session ID or title is not found
Use skl list or skl query to recover the ID. Commands accept a full ID, an unambiguous ID prefix, or an exact title.
skl query "part of the title"
skl view <id>
If multiple agents use similar IDs, add --from <agent>.
Search misses expected content
Remove --cwd and --from filters first. skl query searches all known sources and directories by default.
The persistent search cache is rebuilt when sessions change. If results appear stale, update the CLI and retry:
skl update
skl query "expected text"
Continue does not launch an agent
Confirm the target agent's CLI is installed and on PATH. To test conversion without launching it:
skl continue <id> --with <agent> --no-resume
Not every source can be a continuation target. Amp and Hermes are source-only in the current CLI. See /docs/transcript-support and the txcript compatibility matrix.
Login fails or expires
Check the active account:
skl whoami
Sign in again if the credentials are expired:
skl login
Use device login on SSH, headless machines, or when the local browser callback cannot complete:
skl login --device
If SKL_TOKEN is set, it overrides stored browser credentials. skl logout removes the credentials file but cannot unset the environment variable.
A skill cannot be installed
Inspect the remote skill and verify authentication:
skl whoami
skl skills show <reference>
An existing destination is not replaced automatically in non-interactive use. Inspect it, then use --force only when replacement is intentional:
skl skills install <reference> --force
A local skill cannot be published
Validate it without network access:
skl skills upload <skill-or-path> --dry-run
The skill needs a SKILL.md with a non-empty Markdown body and a description frontmatter field. Add --project when resolving a project-local skill by name.
MCP client cannot connect
Run skl mcp directly only as a protocol process; it waits for JSON-RPC on stdin and normally prints nothing for a human. Check the MCP client's logs and use an absolute binary path if it cannot resolve skl.
See /docs/mcp-server for configuration examples and the exact tools.
A documented command is missing
Older Skillsync docs described session commands named upload, auto, and watch. They are not part of the current CLI. Update skl, use skl --help as the installed command contract, and use list, query, view, or continue for local sessions.