skl migrate

Rewrite a project's layout. skl use never runs these commands for you.

Synopsis

skl migrate targets
skl migrate targets --prune-old
skl migrate targets --project <dir>
skl migrate projections --materialize
skl migrate projections --materialize --project <dir>

Subcommands

targets

Move a project from the old .claude/skills and .cursor/skills links onto .agents/skills.

• --project <dir>. Project root. Default is the current directory.
• --prune-old. Delete the old .claude, .cursor, and .codex links after .agents/skills exists.

It creates or refreshes .agents/skills/<name> for every project skill, from the library copy, and rewrites skills.toml to list agents as the target. Without --prune-old, the old links stay and the command prints extras ... (opt-in; old links kept unless --prune-old).

projections

Replace symlinks with copies.

• --project <dir>. Project root. Default is the current directory.
• --materialize. Required. Write a copy for every skill listed in skills.toml and set each entry to mode = "copy".

This has the same effect as skl use --all when the default mode is copy. It overwrites managed copies and replaces managed symlinks. It does not overwrite a real directory that skl does not manage.

Output

rematerializing 2 skill(s) as copy
  copy     writing-tests  copy
  copy*    agents   /path/to/project/.agents/skills/writing-tests
  updated  /path/to/project/skills.toml

Errors

• local state: no project skills to migrate under <dir> (expected M0 links in .claude/.cursor)
• local state: skill <name> is linked in the project but not found in the personal library
• local state: <path> exists and is not a managed projection; refusing to overwrite (pass --force to clobber a real directory)
• local state: specify --materialize to convert link projections to copies (or skl use --all)