Skip to main content
Your library is one directory, ~/.agents/skills, that holds every skill agentx manages. agentx installs a skill there once and links it into each agent client. Every client sees the same files, and one update reaches all of them. This page uses the terms placement, universal client, configuration, managed skill and base version; see the glossary.

Install a skill

Each row is one client’s placement. For a universal client, the placement is the library entry itself. See Clients that see every skill. If you have not added the source yet, skill add adds it first, as agentx source add does. The source stays added even if the install fails. Name a new source by its URL or as owner/repo. A source id works only for a source you already added. For a source you already added, agentx installs from its last fetch. agentx source list shows when that was. To install the latest version, add --fetch, or run agentx source fetch first:
A source follows one branch, tag or commit, its pin. To install from another ref, change the pin first with agentx source add <url>#<ref>. If you give skill add a different ref, it stops with exit code 1. When the source holds more than one skill, name the one you want with --name. --name and --except match the name in the skill’s SKILL.md, or the directory name if there is no name. Case does not matter. If the path points at one skill, leave --name out:

Install several at once

Give --name once for each skill you want:
Or take the whole source and leave out what you do not want:
You cannot use --all with --name, and --except works only with --all. --all also works with a source you have not added yet. If one skill cannot be installed, the rest still land. agentx names the one it skipped and why, and exits non-zero:
To keep the skill that holds the name, fork it under a new name first:
If the skill that holds the name is one of your own skills, rename it instead with agentx skill rename xlsx my-xlsx, then install again. agentx also refuses a skill whose directory name in the source holds a control character, or starts or ends with a space. Ask the source to rename the directory, or install another skill. If a source has two skills with the same name, agentx installs the first and skips the other with a warning. The skip does not make the install fail:

Clients that see every skill

Some clients, such as Codex and Gemini CLI, read the library directly. These are universal clients. They see every skill in the library, so they get no link of their own. A client also becomes universal when its skills directory and the library are one directory through a symlink. For example, if ~/.claude/skills is a symlink to the library, Claude Code reads the library, and so does Cursor, which also reads ~/.claude/skills. Every other client gets a symlink in its own skills directory, pointing at the library. A universal client sees every skill in your library, even if you disabled that client with agentx config disable or left it out of --to. The install output ends with a line that names them:
The line is left out when no universal client is installed. To take a skill away from the universal clients, remove it from the library. See Clients that read the library.

Choose where it goes

By default a skill is placed in every enabled configuration. To choose, name the configurations with --to:
--to names the configurations for this install, in place of every enabled one. You can name a configuration you disabled. Universal clients see the skill whatever --to names.
Use --copy for a client that cannot follow a symlink. agentx remembers the choice. Later installs and placements give that client a copy without --copy.

If something is already there

An install never overwrites your files. agentx installs only regular files and directories. It leaves out a symlink or a git submodule inside a skill and warns about each one.

A copy that differs from the library

A copy agentx placed stops matching the library when you edit the copy or when the skill in the library changes. agentx skill place and agentx config enable --place-all keep that copy exactly as it is and skip it, with a warning:
To replace the copy with the library version, run the command on the second line of the warning. This deletes what the copy holds, so save what you want to keep first.

Install your skills on another machine

Your own skills, the ones you create or fork and then publish to your account remote, install on another machine from that remote. Add the same remote there with agentx source add <url> --account, then list the skills it holds that this machine has not installed:
  • --remote fetches the remote first. A remote Git cannot reach stops with exit code 3.
  • Each installable row shows the skill’s source column as agentx skill list does. See List your skills.
  • A branch on the remote that agentx cannot install is left out with a warning: one whose name is not a valid skill name, or whose history records no fork id.
Run agentx skill add with no source to install from the account remote. Name a skill with --name, once for each:
Or install every skill the account remote holds that this machine lacks, and leave out what you do not want with --except:
  • It is the same skill, with its history. Publish your edits here, and they go to the same branch.
  • agentx fetches the account remote every time, so leave out --fetch: with no source it stops with exit code 1. --name and --except match the name exactly. --to and --copy work as for a source.
  • If you forked the skill from a source this machine has not added, agentx adds that source, so agentx skill check-updates finds its updates.

When the library already holds the name

  • The same skill installed from its source, without edits: the skill from the account remote replaces it. Symlink placements lead to the new skill. A copy placement keeps the old version until you run agentx skill place <name>.
  • A managed skill with an update merge pending: agentx stops with exit code 4. Finish the merge, or give it up with agentx skill update <name> --abort, then install again.
  • A managed copy with your edits, or any other folder: agentx stops with exit code 6 and changes nothing. Move the folder aside, or remove the skill with agentx skill remove <name>, then install again.
  • A symlink: agentx stops with exit code 6. Remove the link, then install again.

Place a skill

agentx skill place puts a skill the library already holds into more clients, and puts back the placements agentx skill list flags.

Place a skill you already have

Put a skill the library already holds into another client:
The first line counts the configurations you placed the skill in, and any placements agentx skipped. Each client you named gets one row. A client whose placement was skipped gets a row only if it sees the skill through another client’s skills directory, as Cursor reads Claude Code’s. Name each client with --to, once for each. Without --to, agentx places the skill into every enabled client and puts back what agentx skill list flags there; see Put back placements. Add --copy for a client that cannot follow a symlink; agentx remembers the choice, as it does for agentx skill add --copy. To turn a recorded copy back into a symlink, take it away with agentx skill remove pdf --from cursor, then place the skill again with agentx skill place pdf --to cursor. What is already at the path decides what happens, as for an install (see If something is already there), with one difference: a directory that holds other content stops the command, unless you add --force. See When the directory differs from the library. agentx lists every directory it adopted. An adopted directory becomes an agentx placement, so agentx skill remove deletes it later. To place a skill that is already in your library, use skill place. skill add installs from a source. If you give it the name of a library skill, it stops with exit code 1 and shows the command to run:
The hint keeps the --to and --copy you gave. If the argument is a source URL, owner/repo or a source id, skill add installs from that source, even if a library skill has the same name.

Put back placements

Put back the placements agentx skill list shows as missing or displaced, in every enabled client:
  • A missing placement is made again: a copy if you placed a copy there before, a link otherwise.
  • A link to the library where you placed a copy is replaced with a copy.
  • A real directory where the link belongs is replaced with the link when it holds exactly what the library holds, and named as adopted: nothing is lost.
Add --to to put back only the clients you name. agentx leaves your own links, copies you edited and disabled clients as they are.

When the directory differs from the library

If a real directory where the link belongs holds anything else, for example because another installer copied a different version there or you edited the skill there, replacing it would delete what it holds. skill place stops with exit code 6 and changes nothing:
To replace it with the library version, add --force. The directory is deleted and replaced with the link:
To keep that content, move the directory out of the client’s skills directory, for example to use it as a skill of your own. Then run skill place again to put the link back. --force never changes the library. --force works with --to and --copy: it replaces only the directories of the clients --to names, and with --copy the client gets a copy of the library version. If a directory changes while skill place runs, agentx stops with exit code 6 and changes nothing. Run it again.

When skill place stops

One of your own skills is placed as skill add places it. skill place also puts back its worktree and library symlink: see Recover a skill of your own. For a managed skill whose library directory is gone, skill place stops with exit code 6: see A skill whose library directory is gone. skill place stops with exit code 6 and changes nothing when symlinks join the paths it would change, for example a client’s skills directory that links into the library or into another client’s directory. The error names the paths. Remove the symlink that joins them, then run the command again.

List your skills

Each row shows the skill, its kind, whether it holds edits you have not published, its source and how many placements it has, one per client that sees it. The source column shows where the skill is published to:
  • A skill of a shared source shows the source’s URL and the folder in it, as pdf does above. Its updates come from there.
  • One of your own skills shows your account remote, marked (account), or account remote not set until you add one. A skill you forked from an installed skill also shows its upstream after from, as my-pdf does above, and takes the updates of its upstream.
  • An unmanaged skill shows (none).
The state column shows: A skill can be in more than one state at once, so the row names each of them: modified, source removed is a skill you edited whose source you then removed. displaced and missing are information only, so they do not make a command fail. Add --remote to also list the skills on your account remote that this machine has not installed. See Install your skills on another machine.

A skill whose library directory is gone

If a managed skill’s directory is deleted from the library outside agentx, the skill has no row. skill list names it in a warning instead, with two ways out:
  • Install it again with agentx skill add. This works while the source still holds the version you installed. If the skill changed in the source since you last fetched it, skill add refuses and tells you to run agentx skill remove first.
  • Stop managing it with agentx skill remove <name>. This always works. It removes the skill’s record and the placements agentx made, and clears the warning. --from <client> stops with exit code 6 for such a skill.
If the directory is still there but has lost its SKILL.md, the warning names it. Move it aside before you install the skill again, since skill add does not write over it.

Bring back a removed source

A managed skill whose source you removed shows source removed until you add that source again:
This clears the state. Your skill and its placements stay as they are. See Remove a source.

See what you changed

See the edits you made to a managed skill. agentx compares it with its base version: the version you installed or updated to, or last published to its source.
There is one diff per file, and paths are relative to the skill’s directory. A moved file shows as one deleted and one added. A skill with no edits prints pdf matches its base version at 3f2a9c1. The diff changes nothing. Files that do not count never show. A repository nested in the skill, or anything else git cannot record, such as a named pipe, is left out with a warning naming it. Such a skill never matches its base version:
  • skill list shows it as modified;
  • the first line of the diff counts the paths git cannot record, as in pdf differs from its base version at 3f2a9c1 only in 1 path git cannot record;
  • skill update refuses to apply an update to it until you move the path out of the skill.
A skill agentx did not install has no base version to compare with, so skill diff stops with exit code 6. For one of your own skills, skill diff shows its unpublished edits, against what you last published: see See what changed.

Files that do not count

agentx skips the files git ignores. They do not make a skill modified, they do not show in skill diff, and skill update keeps them. This covers:
  • files the skill’s own .gitignore names, such as a node_modules directory;
  • files your global git ignore file names, ~/.config/git/ignore or the file your core.excludesFile setting points to;
  • files your operating system or editor leaves behind, such as .DS_Store, Thumbs.db, *.swp and *~ backups, while the ignore_system_files setting is on, which it is by default.
A file that was part of the version you installed always counts, even when an ignore rule names it. The skill’s own .gitattributes applies too: a file that differs only in line endings the skill asks git to normalise is not a change.

Get the original back

agentx does not undo edits for you. To discard your edits, remove the skill and add it again:
Removing deletes the skill and all your edits, so run agentx skill diff pdf first and save what you want to keep. Adding it again installs the version from the source’s last fetch, which may be newer than yours. Pass --copy or --to again if you used them: removing the skill forgets them.

Read a skill’s files

See every file of a skill as it is on this machine, with its size and line count:
The desktop app uses this command to show a skill’s files. It reads every file and changes nothing. With --json, each file is one event that also carries the file’s content, as text with U+FFFD for a byte that is not valid UTF-8. A binary file, one with a NUL byte among its first 8000, and a file over 256 KiB are described, never printed: the event says binary or truncated and carries no content.
  • Name a skill of your library by its name, and a plugin’s skill as for agentx skill fork: by its name, or as <plugin>:<name> when several plugins provide one of that name.
  • To read a skill directory that one client holds on its own, which is neither in your library nor a plugin’s, name the client with --configuration: agentx skill files commit --configuration claude-code.
  • A file git ignores in a library skill, such as a node_modules directory, is marked ignored. These are the files that do not count, which skill diff leaves out.
  • A symlink to a file is read as the file an agent reads through it. A symlink to a directory, a .git directory and anything that is not a file are left out with a warning.
  • A skill, a plugin’s skill or a configuration you name that does not exist stops the command with exit code 5.

Check for updates

Look for newer versions of the skills you installed, including the ones you forked:
agentx fetches the source of each managed skill and the upstream of each skill you forked. It uses your git setup, so your credentials work. It then lists each skill that has a newer version, with the files that version changes. For a forked skill, see Take a new upstream version. Nothing is applied. Your library, your clients and your edits stay exactly as they were. agentx records the newer upstream version it found so that you can read it, apply it with agentx skill update, and so that agentx skill list shows update available for the skill:
Each check lists every update available, including the ones an earlier check found. With an account remote set, the check also fetches it and lists each of your own skills placed on this machine that another machine published changes to. Take those changes in with agentx skill update <name>:
What another machine published is not recorded, so agentx skill list does not show it and agentx skill diff --update cannot read it: run the check again to see it, or agentx skill update <name> to take it in. If the account remote cannot be reached, the check warns, still checks your other sources, and exits with code 3. The desktop app runs this check once when it starts. See Update checks.

Read an update

Show what an update changes, file by file:
The diff compares the version you installed with the version the last check found. It leaves out your own edits, which agentx skill diff pdf shows, and it needs no network. If no check has found an update for the skill, the command stops with exit code 6 and tells you to run agentx skill check-updates.

A skill its source no longer holds

If a skill’s directory is deleted from its source, or loses its SKILL.md, the check says so:
The skill stays in your library as it is, shows upstream removed in agentx skill list, and agentx does not update it. If the source brings it back, the next check clears the state.

When a source cannot be reached

A source that cannot be fetched is one warning that names it, the reason and the skills it left unchecked:
The check goes on with every other source and records what it finds, then exits with the code for that failure, 3 for a source it cannot reach. Updates found earlier for the skills of that source are kept.

Sources you removed

The check skips the skills of a source you removed with agentx source remove: it does not fetch the source and keeps what an earlier check found for them. Add the source again to check them.

Update a skill

Apply the update a check found:
agentx replaces the skill’s library directory with the newer version and records it as the version you have. Every client that links to the library sees the new version at once. agentx skill list shows the skill as current again, and its update available is gone. For a skill of a source, the update applies the version the last check found, the one agentx skill diff pdf --update shows, and needs no network. agentx updates a skill only when you run this command. If you edited the skill, agentx keeps your edits. See A skill you edited. Files your ignore rules name stay: a .DS_Store, an editor’s backup file or an ignored build folder (see Files that do not count). If the newer version ships a file at the same path, its file replaces yours. Update every skill that has an update:
If no check has found an update for the skill, the command says it is up to date as of the last check and changes nothing. Run agentx skill check-updates to look again. A copy placement is handled on its own:
  • A copy that holds the version you are replacing gets the new version, and keeps the files your ignore rules name in it.
  • A copy you edited in place is kept exactly as it is and skipped, with the warning for a copy that differs from the library.
  • A copy agentx cannot read is kept as it is and skipped, with a warning that says why.
If a newer version gives the skill another name, the skill keeps the name you installed it under, and the update says so. If the skill changes while the update runs, for example because your editor saves a file, agentx stops with exit code 6. Run the command again. An interrupted update finishes on the next agentx command. If a file of the skill changes while the update writes it, agentx stops with exit code 6 and says that recovery is required. To finish the update, restore the file the error names. To keep your change, move the journal file in ~/.agentx/mutations aside.

Update to what another machine published

Your own skills travel between your machines through the account remote: the ones you created with agentx skill new, forked with agentx skill fork, or installed from the account remote. Update them to the latest version you published from another machine the way you take an update:
  • agentx skill check-updates lists what the account remote holds that this machine lacks as published from another machine. Checking first is optional: agentx skill update <name> fetches the account remote itself.
  • agentx skill update <name> updates one skill to the latest published version and shows the message it was published with. agentx skill update --all does so for every one of your own skills on this machine.
  • If both machines changed the skill, agentx merges the two and prints ✓ merged the latest published version of notes with your local edits. The skill then shows as modified until you publish it.
  • A skill you forked from a source is first updated to the latest published version, then to its new upstream version, as two commits.
  • Edits you have not published are recorded on the skill first, and what the account remote holds is merged with them. They stay unpublished until you publish them. Publish with -m to publish them under your own message.
  • Update before you publish: agentx skill publish never merges, and stops with exit code 6 when another machine published changes and this machine has changes of its own.
  • When both machines changed the same lines, the merge waits for you: see Resolve a conflict. Resolve it, then run agentx skill update <name> again.
  • A skill with no upstream (one you created with agentx skill new, or forked from an unmanaged or a plugin’s skill) that has nothing new on the account remote is up to date with the account remote. One you never published, or one another machine removed, has no branch there, and the update tells you to run agentx skill publish <name>.
  • If Git cannot reach the account remote, the update of a skill with no upstream stops with exit code 3. A skill you forked from a source gets a warning and still takes its new upstream version.

A skill you edited

A skill you changed since you installed it keeps your changes: agentx merges them into the newer version, the way git merges two branches, with the version you installed as their common base. When your changes and the update change different lines, the merge is clean and the update applies at once:
The skill is then at the new version with your changes on top of it, so agentx skill list still shows it as modified, and agentx skill diff docx shows your changes against the new version. Files your ignore rules name are not part of your edits and are kept as for any update. A file you added inside a folder the update renamed stays where you put it. A copy that still held the version you installed, or your edited version, gets the merged one. Git merges line by line, and changes to lines next to each other conflict, so a short file conflicts more often than you might expect. Read the update with agentx skill diff docx --update before you apply it.

When your edits conflict

When your changes and the update change the same lines, agentx leaves your library as it is. Your agents keep using the skill as you left it. The merge waits in a separate Git folder, ~/.agentx/merges/<name>. skill update stops with exit code 4 and lists the files that conflict, each with what git status says of it:
As in git status, “us” is your library directory and “them” the update: a file you deleted and the update changed reads deleted by us, and one the update added where you had added a file too reads both added. Files your ignore rules name are not part of your edits, so they never conflict and stay as they are. The folder holds a normal Git merge. Work in the folder the hint names. Conflict markers are longer than any line of the skill that looks like one, such as a ======= rule. The merge stays until you finish it or give it up, and agentx skill list shows the skill as merge pending. Meanwhile:
  • skill fork, and skill remove without --from or with --from universal, stop with exit code 4 and change nothing.
  • Everything else works as usual: placing the skill, skill place --force included, removing it from one client, skill diff, and update checks, which may find a newer version still.
With --all, a skill whose edits conflict is left with its merge pending and the other skills are still updated. The run then exits with code 4, or 6 if other skills were not updated for other reasons.

Finish the merge

Resolve the merge with Git in the folder the hint names:
Edit a file that conflicts to keep what you want from both sides, then git add it. git status, git diff and git commit work there as in any merge; committing is optional. Then run the update again:
agentx applies the merge as it applies a clean one: your library directory takes the merged files, copies are refreshed, and the worktree is removed, so leave it with cd if your shell is still in it.
  • Only what you git added is applied, as git commit would record it. A change you made after git add, or a new file you never added, is removed with the worktree.
  • It applies the version the merge started with, even if a check has found a newer one since. That newer one stays as the skill’s next update.
  • agentx skill update --all applies it too, with the other updates.
  • Until every file is resolved, the update lists the files that are left and stops with exit code 4 again, changing nothing.
If you changed the skill’s library directory while the merge was pending, the update stops with exit code 6. Give the merge up and update again.

Give the merge up

This removes the worktree and whatever you resolved in it. Your library directory, its placements and the update agentx found are left exactly as they were, so agentx skill update docx merges again from scratch.

When a skill is not updated

With --all, agentx updates every skill it can and names each one it could not. It then exits with the code those skills share, or 6 if they differ. A skill whose source you removed is skipped and does not change the exit code.

Publish a skill

Publish one of your own skills, one you created with agentx skill new or forked with agentx skill fork, to your account remote so your other machines can install it and get what you change:
  • Your edits stay on this machine until you publish them. Publishing records them as one commit on the skill’s history, then pushes it. There is no separate commit step.
  • Give the commit a message with -m. Its first line is the subject. Without -m, agentx writes one that names the skill, the files you changed and this machine, such as release-notes: edit SKILL.md (laptop).
  • With -m, agentx publishes all your unpublished changes as one commit under your message. A rename or an upstream update keeps its own commit.
  • Publish a skill the first time by name. Its push creates the skill’s branch on the account remote.
  • Run agentx skill publish with no name to publish every skill of your own that the account remote already holds. -m then gives the message of each commit it records. A bare publish never creates a branch: it skips each skill shown as not published, one you never published or one another machine removed, and names the command that publishes it:
    A bare publish never covers a skill you installed from a shared source either: name it to publish it to its source.
  • Files that stay local, such as a .DS_Store, are never published.
  • Each skill goes to its own branch, skills/<name>. Publishing one skill leaves your other skills where they are.
  • If another machine published changes first, publishing stops with exit code 6 and changes nothing. Run agentx skill update <name>, then publish again. agentx never forces a push.
  • When the remote’s host declines the push, for example a hook or a protected branch, publishing stops with exit code 6 and names the host’s reason, with up to three lines the host wrote:
    There is nothing to update: fix what the host says, then publish again.
  • When the remote does not let this machine push, publishing stops with exit code 3. The hint says what to fix:
    • Credentials that only allow reading, or none: check the git credential helper or SSH key you use for the remote.
    • A host SSH does not trust yet: connect to it once with ssh to add its key to known_hosts.
    • An organisation that requires single sign-on or an IP allow list: authorise your token or key for the organisation, or allow this machine’s IP address.
  • Publishing needs an account remote. Without one, it stops with exit code 6 and names agentx source add <url> --account.
  • A skill agentx does not manage has no source to publish to: fork it with agentx skill fork <name> to make it one of your own.
  • To delete a skill’s branch from the remote, remove the skill with agentx skill remove <name> --remote.

Publish edits to a shared source

Push the edits of a skill you installed from a shared source back to that source, for example a fix to a skill of your team’s repository:
  • Name the skill. A bare agentx skill publish never pushes to a shared source.
  • No account remote is needed. Publishing to a shared source does not read or fetch yours.
  • agentx writes one commit on the branch the skill is installed from: the source’s default branch, or the branch you pinned it to. The commit changes the skill’s folder alone, and everything else on the branch stays as it is.
  • The commit carries your own Git identity. Set it first with git config --global user.name "Your Name" and git config --global user.email you@example.com: without it, publishing stops with exit code 6. The commit carries no agentx data.
  • Give the commit a message with -m. Without -m, the message is Update <folder>, such as Update skills/pdf, or Update <directory name> for a skill at the root of its repository.
  • Afterwards the skill stays managed and shows as current: the version you published is the one it compares with.
  • A skill with no edits has nothing to publish. agentx says so without fetching anything.
  • When the source changed the skill since you installed it, publishing stops with exit code 6 and pushes nothing. Your edits stay where they are. Take the change in with agentx skill update <name>, then publish again:
  • While a merge with an update is pending, publishing stops with exit code 4: finish the merge or give it up first.
  • When you removed the skill’s source from this machine, publishing stops with exit code 5: add it again with agentx source add <url>.
  • When the source’s host declines the push, for example a hook or a protected branch, publishing stops with exit code 6 and names the host’s reason. Fix what the host says, then publish again.
  • When the source does not let this machine push, publishing stops with exit code 3. Check the git credential helper or SSH key you use for it, as for your account remote.
  • A skill installed from a tag or a commit has no branch to publish to: publishing stops with exit code 6. Add the source at a branch with agentx source add <url>#<branch>, update the skill, then publish again.
  • A symlink you add to the skill is never pushed: publishing stops with exit code 6. Replace it with the file it leads to, or remove it.
  • When the skill holds a file agentx would not install, or something Git cannot record, publishing stops with exit code 6. Move it out of the skill, then publish again.
  • When the source no longer holds the skill, publishing stops with exit code 6. Run agentx skill check-updates once the source holds it again, or remove the skill.
  • If publishing stops with exit code 3 or 6 for another reason, or succeeds with a warning, follow the hint, then publish again if it says so.

Two skills with one name

Every skill of your own has a permanent id. A skill you create on two machines under the same name is two skills, with two ids. agentx keeps them apart: once one is published, publishing or updating the other stops with exit code 6:
Rename yours, then publish it under its new name. Publishing the renamed skill keeps the other skill’s branch, since it has another id. A remote branch whose history records no id stops the same way, since nothing tells that it holds the same skill.

Remove a skill

From one client:
From the machine altogether:
Without --from, agentx takes away every placement, the library directory, the record of where the skill came from and what the settings remembered about it. With --from <client>, only those clients’ placements go; the library keeps the skill. While a skill has a merge pending, removing it from the machine stops with exit code 4 and removes nothing. Removing it from one client works as usual. If the skill’s library directory is gone, agentx skill remove <name> still works. It removes the record and the placements agentx made. --from <client> stops with exit code 6. See A skill whose library directory is gone. From every client, by name:
--from universal does the same as leaving --from out. Use it on its own: next to a client that is not universal, it stops with exit code 1.

What agentx deletes

agentx deletes a placement only when it made it:
  • a symlink pointing at the library directory, and
  • a copy agentx placed and recorded.
Everything else is left exactly where it is and named in the output:
  • a directory you made by hand,
  • a link of yours pointing somewhere else, even when following it ends up in the library,
  • a directory holding the same version that agentx never recorded as a copy,
  • a file.
agentx deletes only a link that points straight at the library entry. A link of yours stays, even if it leads to the library through another link:
Here ~/mylinks/pdf points at the library entry. The removal deletes that entry, so your link stays but leads nowhere. A link of yours that leads somewhere else keeps working, and the warning names the client that still sees the skill. agentx removes a copy it placed even if you changed it, and warns you:
Take a copy of anything you want to keep before removing it.

Clients that read the library

A universal client reads the library directly, so it has no placement of its own to remove. A skill leaves every universal client at once or none of them:
agentx changes nothing. To take the skill off the machine, run the command in the hint. It lists every client that loses the skill.

After a removal

After a removal, agentx checks each client again. If a client still sees the skill, for example through a directory agentx did not place, agentx warns and names the path:

Your own skills

Removing one of your own skills from the machine also deletes its local history. Add --remote to delete it from your account remote too. See Remove a skill of your own. --remote applies only to your own skills, the ones on your account remote. For a skill of another source, or one with no source, agentx refuses it with exit code 6 and changes nothing. Remove the skill from this machine with agentx skill remove <name>.

Turn skills on for your cloud agents

Every agent you run in the cloud, such as Claude Code on the web, is one cloud machine. It has no disk that lasts, so its skills live in its snapshot on your account remote, on the branch machines/cloud. Each cloud session reads that snapshot when it starts. To apply it yourself, for example in a cloud environment’s setup script, run agentx import --machine cloud --yes, see Restore from the account remote. Turn a skill on and off there with the same commands you use on this machine, adding --machine cloud. Nothing on this machine changes. Place a skill on the cloud machine:
Without --to, agentx places the skill in every configuration this machine enables. Name configurations with --to, once for each:
Add --copy to give those configurations a copy instead of a symlink, as on this machine. The snapshot’s settings remember the choice. When you remove the skill from a configuration with --from, that configuration no longer gets a copy:
The cloud machine always takes the latest version of the skill: the account remote’s for one of your own skills, and the source’s for a skill of a source. Publish your own skills first. If the account remote does not hold one yet, agentx warns that the cloud machine cannot install it until you run agentx skill publish <name>. A skill that agentx does not manage has no source, so agentx refuses to place it on the cloud machine. Take a skill away from some configurations, or off the cloud machine:
Without --from, or with --from universal, agentx deletes the skill from the cloud machine’s snapshot. A universal client sees every skill the snapshot lists, so --from naming one is refused with exit code 6. Each command writes one commit to machines/cloud and pushes it. agentx never forces the push. If another machine or the web app changed the snapshot since agentx read it, the command stops with exit code 6 and pushes nothing. Run it again: it reads the snapshot again first.
  • --machine accepts only cloud. A computer’s skills live on its own disk, so run the command on that computer.
  • --force replaces a directory on this machine’s disk, and --remote deletes a skill’s branch, so agentx refuses each of them with --machine.
  • To copy every skill of this machine to the cloud machine at once, export a snapshot to it: see Seed another machine.

Exit codes

For what each code means, and for codes 2 and 9, see Exit codes. These causes are special to agentx skill: