Skip to main content

skl use

Copy a library skill into the project, list the skills the project uses, or rewrite every listed skill with --all.

Synopsis​

skl use
skl use <skill>...
skl use --all
skl use <skill> --link
skl use <skill> --force
skl use <skill> --project <dir> -a <id>

Arguments and flags​

  • <skill>.... Library skill names. With none, list the skills in skills.toml.
  • --all. Rewrite every skill listed in skills.toml from this machine's library. Cannot be combined with names.
  • --link. Write a symlink into the library instead of a copy. Remote checkouts such as Cursor Cloud cannot follow it. When the symlink cannot be created, skl falls back to a copy and records mode = "copy".
  • --force. Overwrite a real directory at the target path that skl does not manage.
  • --project <dir>. Project root. Default is the current directory.
  • -a, --agent <id>. Also write the project directory of the agent <id>, such as claude-code. Repeatable. claude is accepted as claude-code. cursor and codex are rejected because they already read .agents/skills.

The default mode is copy. projection = "link" under [project] in config.toml makes symlink the default. --link wins over the config.

Output​

using writing-tests  (agents  /home/you/.local/share/skl/skills/writing-tests)
  copy     agents   /path/to/project/.agents/skills/writing-tests
  updated  /path/to/project/skills.toml

The first column of each directory line is the action. copy and link mean a new directory or symlink. copy* means an existing symlink or stale copy was replaced with a fresh copy. replace means an existing symlink was replaced. ok means the directory already matched.

With no names:

name                     source     mode
writing-tests            library    copy

What it writes​

  • .agents/skills/<name> as a directory copy, or as a symlink with --link.
  • The project directory of each extra from -a, from [targets].extra in the project's skills.toml, and from [targets].extra in config.toml.
  • skills.toml: the skill entry with source = "library" and mode = "copy" or mode = "symlink", plus any new extras under [targets].extra.
  • A background sync may run afterwards.

skl use does not run skl migrate and does not run git add.

Errors​

  • local state: use either skl use --all or skl use <skill>
  • local state: skill <name> is not in the personal library on this machine. Run skl init or skl capture to import it, or skl sync to pull the library, then skl use --all.
  • local state: skill <name> listed in <skills.toml> but not found in the personal library on this machine. Run skl sync to pull it, then skl use --all.
  • local state: <path> exists and is not a managed projection; refusing to overwrite (pass --force to clobber a real directory)
  • local state: invalid skill name <name> for a name that is empty, starts with ., or contains / or \.