Skip to main content
The Vercel skills CLI and Skillshare both record where each skill they installed came from. agentx adopt reads those records and installs each skill from its source, the way agentx skill add does. Afterwards agentx manages the skill: it knows the source and can update it. agentx only reads the other tool’s files. They stay as they are.

See what can be adopted

With no flags, the command only shows what it found. It writes nothing and makes no network calls. The skills are grouped by what adopting would do with them: The tool column shows only when both tools installed skills on this machine. When agentx already manages every skill, the preview ends with Nothing to adopt: agentx already manages every one. To look at the skills of one tool only, name it: skills-cli for the Vercel skills CLI, or skillshare. This works with --all and --skill too:

Adopt skills

Adopt every skill that is ready:
Or name skills with --skill, once for each:
For each skill, agentx:
  1. Adds its source if you do not have it yet, as agentx source add does, pinned to the ref the record names. This also brings back a source you removed.
  2. Installs the skill from that source at the version the source holds now, and places it in every enabled client, as agentx skill add does.
If a skill fails, agentx still adopts the others and lists the failures at the end. Afterwards the skills are ordinary managed skills:

What happens to the directory

Adopting replaces what the other tool left in the library with the version it installs. That covers the directory the Vercel skills CLI copied, the symlink Skillshare puts in ~/.agents/skills, and any edit you made in there. To keep an edit, fork the skill first. A fork keeps your files and their history, under a name of your choice:
Skillshare keeps its own copy of each skill in its folder, ~/.config/skillshare/skills by default. agentx never touches that folder, so your edits there stay.

After adopting from the Vercel skills CLI

The Vercel skills CLI installs into ~/.agents/skills, the library itself, and links your clients’ folders to it, so after adopting nothing else moves: the library directory is agentx’s, and the links are the placements. Stop using that CLI for the adopted skills. Good to know: skills update rewrites the library directory with the newest upstream version, which agentx then shows as modified against the version it installed; skills remove deletes the directory and its lock entry, and agentx skill list then names the agentx skill add command that installs the skill again.

After adopting from Skillshare

Adopting moves a skill to agentx completely: the library gets a real directory, and Skillshare’s links in your clients’ folders, such as ~/.claude/skills/pdf, become links to the library. You are done with Skillshare for that skill. Uninstall Skillshare, or stop running it, and leave its folder as it is or delete it. Good to know: Skillshare does not know about the adoption. If you run skillshare sync afterwards, it puts its own links back, or removes the adopted directory once you uninstalled the skill there, and your clients read Skillshare’s copy again. Running agentx adopt --all again repairs that: agentx installs each such skill again and the adoption is whole. A skill you also uninstalled from Skillshare is no longer in its records, so agentx adopt cannot see it; agentx skill list then names the agentx skill add command that installs it again.

Skills from one source at different refs

agentx keeps one ref for each source, its pin. The records name a ref for each skill, so skills from the same source can have different refs. When a run adds a source, agentx pins it to the ref of the first skill the run adopts from it, in alphabetical order. If those skills have different refs, agentx warns you:
A source you already have keeps its pin. To choose the pin yourself, add the source at that ref before you adopt. If you already have the source, this changes its pin:

Grouped Skillshare skills

Skillshare can install a skill into a group, such as frontend/ui. In every tool’s skills folder it names that skill frontend__ui, with two underscores. agentx adopts it under that name. To shorten it, rename the skill afterwards:

Refused skills

A refused skill stays in your library as it is and keeps working in every client. agentx skill list shows it as unmanaged.

Where agentx reads the records

For the Vercel skills CLI, agentx reads both lock files:
  • $XDG_STATE_HOME/skills/.skill-lock.json, or ~/.local/state/skills/.skill-lock.json when that variable is unset
  • ~/.agents/.skill-lock.json
If both files list a skill differently, agentx warns you and uses the file the Vercel skills CLI writes to now: the $XDG_STATE_HOME one when that variable is set, and ~/.agents/.skill-lock.json otherwise. For Skillshare, agentx reads .metadata.json in the folder Skillshare installs into:
  • ~/.config/skillshare/skills by default, or under $XDG_CONFIG_HOME when that variable is set
  • the folder sources.skills names in ~/.config/skillshare/config.yaml, or the older source key, when either is set
Skillshare migrates its older registry.yaml and the .skillshare-meta.json files beside each skill into .metadata.json the next time it runs. If agentx finds nothing to adopt, run a Skillshare command such as skillshare list first. If a record file is unreadable JSON, or a configuration file is unreadable YAML, agentx stops. Fix the file or move it aside. agentx skips an entry that is not an object or names no source. If one field has the wrong type of value, agentx warns you, drops that field and reads the rest of the entry. A skill both tools recorded is adopted from the Vercel skills CLI’s record, with a warning.