Skip to main content
Your library is one directory, ~/.agents/skills, that holds every skill agentx manages for you. Installing a skill puts it there once and links it into each agent client, so every client sees the same files and an update reaches all of them at once.

​
Install a skill

Each row is one client’s placement: the link or copy in its own skills directory, or the library entry itself for a client that reads the library. Cursor also reads Claude Code’s skills directory, so it sees the skill there too; that path is Claude Code’s row. --json lists every path each client sees the skill through. If the source is not on this machine yet, skill add adds it first, as agentx source add would, and the source stays added even if the install then fails. Name the source by its URL for this: a source id only works for a source you already added. If you removed the source and a skill installed from it is still in your library, installing by its id tells you the command that adds it again:
A source you already added is not fetched again. The install reads what that source last fetched, whether you fetched it or the desktop app’s background process did, and the result says when that fetch was. Add --fetch to fetch the source again first, or run agentx source fetch:
To install from another branch or tag than the one the source is pinned to, change the pin with agentx source add <url>#<ref> first. Name the skill with --skill when the source holds more than one. --skill and --except match the name in the skill’s SKILL.md frontmatter in any case, or its directory name when the frontmatter has no name, as the vercel skills CLI does. If a path already narrows it to a single skill, leave --skill out:

​
Install several at once

Give --skill once for each skill you want:
Or take the whole source and leave out what you do not want:
--all and --skill do not mix, and --except needs --all. Skills install in the order the source lists them, whatever order you name them in. --all works with a source you have not added yet too: it is added once, and then every skill of it installs. One command installs them all: the files come down in one fetch, the versions are recorded in one write to the account repo, and the whole run is one change agentx can finish after an interruption. Thirty skills cost the same git work as one; the time they take is the time their files take. If one skill cannot be installed, the rest still land. agentx names the one it skipped and why, and exits non-zero:
agentx also refuses a skill whose directory in the source carries a control character, or opens or closes with a space:
agentx records where a skill came from on one line of its commit. A directory name that does not fit on one line would be read back as a different directory, or as none at all, leaving a skill you could never update or revert. Ask the source to rename the directory, or install a different skill.

​
Clients that see every skill

Some clients, such as Codex and Gemini CLI, read the library directly. They are universal clients: they get no link of their own, because the library entry is what they see. So is any client whose skills directory you made a symlink to the library, or the library a symlink to it: both are one directory. A client that reads such a directory is universal too: Cursor reads Claude Code’s skills directory, so once ~/.claude/skills is a symlink to the library, Cursor reads the library as well. 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 when you disabled it with agentx config disable or left it out of --to. Each install ends with a line naming every universal client installed on this machine, since the skill is always available to them whatever you chose:
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. Name the ones you want instead:
--to replaces the default targets for that install, including configurations you have disabled with agentx config disable. It decides which clients get a placement; the universal clients see the skill whatever it names.
Use --copy for a client that cannot follow a symlink. agentx remembers which configurations hold a copy and keeps them that way: installing the skill again, agentx skill place and agentx config enable --place-all give those configurations a copy even without --copy.

​
What happens to what is already there

  • A library directory holding exactly this version is adopted: agentx records where it came from and changes nothing on disk.
  • A library directory holding anything else stops that skill with exit code 6. Remove it, or keep it and install under another name later. In a run of several skills only that skill is stopped.
  • A placement that already points at the library is left alone.
  • A placement that is a real directory holding exactly this version is replaced by a link and reported as adopted. A copy agentx placed there itself stays a copy and is not reported as adopted.
  • If the library entry is itself a link to that client’s directory, for example ~/.agents/skills/pdf linked to ~/.claude/skills/pdf, the client already reads the library there: agentx leaves it as it is, reports it as placed, adopts nothing, and with --copy records no copy.
  • A copy agentx placed that is different from the library is kept exactly as it is and skipped, with a warning. See A copy that differs from the library.
  • A placement that is a link somewhere else is left alone, even if what it points at holds the same files: where your skill lives is your choice.
  • Anything else in the way is left untouched, with a warning naming the path.
  • A client skills directory agentx cannot write – one owned by somebody else, one on a read-only mount, or one macOS has not granted access to – is skipped with a warning. The rest of the install still happens, and the summary counts the placements it skipped.
Your files are never overwritten by an install. If two commands try to install the same name at once, one of them wins and the other is refused. The one that loses leaves nothing behind: no half-written directory, and nothing for the next command to clean up.

​
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:
Installing the skill again keeps and skips a copy you edited the same way, with the same warning. When the skill in the library changed, the install stops with exit code 6 before it reaches the copy, as described in What happens to what is already there. The summary counts the copy as a skipped placement. agentx does not record what a copy held when it placed it, so the warning does not say which side changed. To replace the copy with the library version, run the commands on the second line of the warning. Removing the copy deletes what it holds, so save anything you want to keep first. --copy makes the new placement a copy again, as agentx had recorded for that client. For a skill whose name starts with -, the commands put the name last, after --, for example agentx skill remove --from cursor -- -pdf. With --json, the warning is one log event whose message holds both lines, joined by ; .

​
What is left out of the import

A skill directory holds regular files and directories. Anything else – a symlink or a git submodule inside the skill – is left out, with a warning naming it. The library directory then differs from the upstream one, and what agentx records as the installed version is what it actually installed.

​
Place a skill you already have

Put a skill the library already holds into another client:
The first line counts the configurations you placed into. Each client you named gets one row, its own placement, as after an install. If agentx left a client’s path alone and that client still sees the skill through another client’s skills directory, its row shows that path instead, so the output still tells you the client has the skill. 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: a link that already points at the library is left alone, a directory holding exactly this version is adopted, a directory holding anything else stops the command unless you add --force, which deletes what it holds (see When the directory differs from the library), and anything else, such as a link of your own, is left where it is with a warning. If the library entry is itself a link to that client’s directory, for example ~/.agents/skills/pdf linked to ~/.claude/skills/pdf, the client already reads the library there: agentx leaves it as it is, reports it as placed, adopts nothing, and with --copy records no copy. An adopted directory becomes one agentx will delete when you remove the skill, so the run names every path it adopted. This holds with --copy too. A universal client, such as Codex or Gemini CLI, reads the library directly. Placing into one makes no second entry: it already sees the skill, and the last line names every universal client whichever clients you place into. Use skill place, not skill add, for a skill that is already in your library. skill add installs from a source, so given the name of a library skill it stops with exit code 1 and names the command to run instead:
The hint keeps the --to and --copy you gave. Without --to, it places the skill into every enabled client. A source always comes first: a source URL, owner/repo or a source id installs from that source, even when a skill in your library has the same name.

​
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. From every client, by name:
This is the same removal as leaving --from out, with the same output. A universal client reads the library entry itself, so removing a skill from the universal clients means removing it from the library, which takes it from every client. Give --from universal on its own. Next to a client that is not universal it stops with exit code 1 and removes nothing; next to a universal client it is refused as that client is, see Clients that read the library.

​
What agentx will and will not delete

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 decides by the name a link holds, never by where following it leads, so a link of yours is yours whatever it resolves to:
Here ~/mylinks/pdf points at the library entry, so once the removal deletes that entry your link stays but no longer leads to the skill, and the warning says so. A link of yours that does not lead through anything the removal deletes keeps working, and the warning says which client still sees the skill. A copy agentx recorded is removed as you asked, even when it no longer holds the library’s version of the skill. agentx warns, naming whose copy it was and its path, rather than letting the content go quietly:
Take a copy of anything you want to keep before removing it.

​
Clients that read the library

Universal clients, such as Codex and Gemini CLI, read ~/.agents/skills directly, so there is no placement of their own to remove. A skill leaves every universal client at once or none of them:
agentx refuses before it changes anything, also when --from names other clients as well, universal included, and also when the universal client is disabled. The hint lists every client that sees the skill through the library or through a link or copy agentx would delete, including one that reads another client’s skills directory, as Cursor reads Claude Code’s. It also lists a client whose link of yours ends up in the library: the removal leaves your link, but the link no longer leads anywhere. A directory of your own is not counted: the removal leaves it. Run the command in the hint to remove the skill everywhere, or keep the skill. A client that is universal because it reads a skills directory linked to the library is refused the same way, even when a link in its own skills directory is still there. With ~/.claude/skills a symlink to the library, Cursor reads the library through it, so agentx skill remove pdf --from cursor stops with exit code 6, cursor reads the library directly, so pdf cannot be removed from it alone, and leaves ~/.cursor/skills/pdf where it is. Delete that link yourself if you no longer want it, or take the skill off the machine with --from universal.

​
After a removal

A client may still see a skill through another client’s directory: Cursor reads Claude Code’s skills directory, for instance. agentx rescans and reports what the client sees now, so the output tells you whether the skill is really gone from it. Removing a skill from the machine warns for every client that still sees it afterwards, naming the path:
Universal clients, such as Codex and Gemini CLI, read the library, so removing the library entry is all agentx can do for them. A directory of their own under the same name stays, and the warning says where it is.

​
A skill whose library directory is gone

If a managed skill’s directory was deleted from the library outside agentx, agentx skill list warns about it until you install it again or remove it. Removing it always works, whatever the source holds now:
agentx deletes the record of where the skill came from and the placements it made, by the same rules as any removal, and takes the skill out of the settings. A copy placement may be the last copy of the skill on your machine: if it differs from the version the skill was installed at, or agentx cannot tell which version that was, agentx still removes it and warns you that your changes went with it, as in cursor's copy of pdf was different from its base version; removing it deleted those changes. Copy anything you want to keep out of it first. If a directory without a SKILL.md is still in the library under that name, agentx leaves it where it is and says so. --from <client> is refused with exit code 6 for such a skill: with nothing in the library, there is no skill for one client to keep. Leave --from out.

​
Forks

Removing a fork is not this command; it has its own, and agentx skill remove <fork> stops with exit code 6, with or without --from universal. You can still take a fork’s placements away with --from <client>. The universal clients keep seeing a fork until the fork itself is removed, so --from naming one is refused with a hint that says so rather than offering --from universal.

​
List your skills

Each row shows the skill, what agentx knows about it, how it stands against the version it was installed at, where it came from and how many placements it has, one per client that sees it.
  • managed: installed by agentx, with an upstream and a version it can compare against.
  • fork: a skill of your own in the account repo.
  • unmanaged: a directory in the library agentx did not install. It is inventoried and otherwise left alone.
  • current or modified: whether the directory still holds the version it was installed at. Every change counts, whatever tool made it: a file you edited, added or deleted, but also a file made executable, a file replaced by a symlink and a symlink added. Files git ignores do not count: see Files that do not count. See what changed with agentx skill diff.
  • displaced: a client that should see the skill through a link from its own skills directory has a real directory there instead, which is what an installer that copies over links leaves. For a client you placed a copy in, it is the other way round: a link to the library where the copy should be. Put it back with agentx skill place <name>.
  • missing: an enabled client has nothing of the skill in its own skills directory, because you placed the skill with --to, removed it with --from, or the placement was deleted. Place it in one client with agentx skill place <name> --to <client>, or in every client it is missing from with agentx skill place <name>. Universal clients and disabled clients are never missing a skill.
  • source removed: the source the skill came from is no longer added on this machine. The skill keeps working, stays where it is and keeps its record of where it came from. Add the source again to clear it: see below.
  • upstream removed: the last update check found the skill gone from its source. The skill stays as it is and is never updated. The next check that finds it back in the source clears the state.
  • update available: the last update check found a newer version of the skill in its source. Nothing changed in your library; apply the update with agentx skill update <name>, or read it first with agentx skill diff <name> --update.
  • merge pending: an update of the skill found your edits conflicting with it. The update left your library directory as it was, and it applies nothing until you resolve the merge with Git and update again, or give it up. See When your edits conflict.
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: they never make a command fail. If a managed skill’s directory is deleted from the library outside agentx, the skill has no row, since there is nothing left to compare or place. 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 you fetched the source since and the skill changed upstream, skill add refuses and tells you to run agentx skill remove first; after that, skill add installs the version the source holds now.
  • Stop managing it with agentx skill remove. This always works: it deletes the skill’s record in the account repo and the placements agentx made, and clears the warning.
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:
That clears the state and changes nothing else: the skill, its record and its placements stay exactly as they were. It works with any pin, since a source is identified by its URL. Installing another skill from the source by its URL, or adopting one with agentx adopt, adds the source again too.

​
See what you changed

Compare a managed skill with the version it was installed at:
There is one diff per file, and every path is relative to the skill’s directory. A file you moved shows as one deleted and one added. A skill that holds exactly its base version prints pdf matches its base version at 3f2a9c1. A file that is not UTF-8 text prints as the bytes it holds. Control characters other than the tab, such as the carriage return of a Windows line ending, print as a space, so nothing in a file can control your terminal. Use --json to get the patch exactly as git wrote it. The diff only reads your library: nothing is written to it. A file git ignores is never in the diff, and a file the skill’s .gitattributes converts, for example to other line endings, is compared as git converts it: see Files that do not count. 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 diff ends with the number of paths git cannot record, as in pdf differs from its base version at 3f2a9c1 only in 1 path git cannot record, and skill revert refuses it until you move the path out of the skill. An earlier version of agentx could store a skill from a source that uses an old kind of file mode in a form that makes it show as modified even though you changed nothing. skill diff then says so instead of showing a diff:
Run agentx skill revert pdf. It stores the version again without touching your files, and the skill shows as current. While the source still holds that version, installing it again with agentx skill add does the same. A skill agentx did not install, and a fork, have no base version to compare with, so skill diff stops with exit code 6.

​
Files that do not count

agentx compares a skill as git compares a work tree, so the files git ignores never make a skill modified, never show in skill diff, and are kept by skill revert and skill update:
  • 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.

​
Revert a skill

Put a managed skill back to the version it was installed at:
Reverting discards every change made to the skill since it was installed: files you added are deleted, and files you changed or deleted come back as they were, with their permissions. Files git ignores, such as a .DS_Store or a node_modules directory the skill’s .gitignore names, are kept, in the library and in every copy the revert refreshes. Run agentx skill diff first to see what you are about to discard. Only what the skill held when you ran the command is discarded. If the skill changes while the revert runs, for example because your editor saves a file, or another agentx command changes the version it was installed at, agentx stops with exit code 6 and discards nothing. Run agentx skill diff to see the change, then revert again. agentx keeps what it replaces until the revert is complete, so an interrupted revert finishes on the next command and loses nothing. A copy placement is handled on its own:
  • A copy that already holds the installed version is left alone.
  • A copy that holds the changes you are reverting is reverted too.
  • 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.
A skill that holds a repository of its own, or anything else git cannot record, is not reverted: the revert would delete it with no record of it anywhere. agentx names what it found; move it out of the skill, then revert again. If the skill’s library directory is a symlink to a directory of your own, skill revert stops with exit code 6 and discards nothing: a revert replaces the library directory, so it would remove your link and leave your changes where the link leads. Replace the link with the directory it points to, then revert again, or use agentx skill diff to see what differs and put the files back yourself. While a skill has a merge pending, skill revert stops with exit code 4 and discards nothing. A skill agentx did not install, and a fork, have no base version to revert to, so skill revert stops with exit code 6. Reverting a skill that already holds its base version changes nothing. If the version was stored in an older form, as described under See what you changed, the revert stores it again and changes none of your files:

​
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. A link of your own to another directory, a copy you edited, and clients you disabled are left as they are. So is a client’s directory that the library entry itself is a symlink to, for example ~/.agents/skills/pdf linked to ~/.claude/skills/pdf: that directory is the library’s own content.

​
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 instead, 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. Only what the directories held when you ran the command is replaced. If a directory or the library changes while skill place runs, agentx stops with exit code 6 and changes nothing; run it again. agentx keeps what it replaces until the command is complete, so an interrupted run finishes on the next command and loses nothing.

​
What stops it

A fork is placed as skill add places it: a directory that differs is left where it is with a warning, and --force stops with exit code 6. A managed skill whose library directory is gone stops with exit code 6: install it again with agentx skill add, or stop managing it with agentx skill remove, as the error says. skill place changes nothing, with or without --force, when symlinks make what it would change overlap something it must leave alone. It stops with exit code 6 and names the paths when:
  • it would remove a displaced directory while the skill’s own library directory, for example ~/.agents/skills/pdf, is a symlink. agentx installs every skill as a real directory, so replace the link with the directory it leads to.
  • a client’s directory it would replace or create lies inside your library, holds it, or overlaps a directory a library entry links to. For example, ~/.cursor/skills is a link to ~/.agents/skills/docx, or ~/.agents/skills/docx is a link to ~/.claude/skills/pdf/docx.
  • one client’s directory lies inside another’s, for example ~/.cursor/skills is a link to ~/.claude/skills/pdf/sub: replacing ~/.claude/skills/pdf would take everything in Cursor’s skills directory with it.
  • it would remove a displaced directory while the skill’s library directory holds a symlink. agentx never installs one there, so it is your edit: see it with agentx skill diff and go back to the installed version with agentx skill revert, or replace the link with the files it leads to. A run that only writes placements is not affected.
Keep the two apart, then run the command again. A client’s skills directory that is a link to a folder of yours outside the library, such as a dotfiles folder, is fine: agentx follows it there. agentx does not search your disk for other links: a link of yours into a directory you discard with --force leads nowhere afterwards.

​
Check for updates

Look for newer versions of the skills you installed:
agentx fetches every source your managed skills came from, once each and a few at a time, with your own git, so the credential helper, SSH key and URL rewrites you use in a terminal apply. It then compares each skill with what its source holds now and lists every skill that has a newer version, with the files that version changes. Paths are relative to the skill’s directory. Nothing is applied. Your library, your clients and your edits stay exactly as they were. agentx records the newer 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:
Run the check again whenever you like. It lists every update available, including the ones an earlier check found, except for a skill it could not check this time, which it names in a warning; agentx skill list still shows that skill’s update. A newer version upstream replaces the one found before. A change that does not reach your library, such as a symlink in the source, which agentx never installs, is not an update. If a newer version gives the skill another name, the check says so; the skill keeps the name you installed it under. The desktop app’s background process runs the same check when it starts and every thirty minutes, and fetches every other source you added in the same pass.

​
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.

​
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 is never updated. 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. The update needs no network: it applies exactly the version the last check found, the one agentx skill diff pdf --update shows. agentx never updates a skill unless you run this command. A skill you edited 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 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. Only what the skill held when you ran the command is replaced. If the skill changes before the update starts to write, for example because your editor saves a file or a check finds another version, agentx stops with exit code 6 and changes nothing. Run the command again. If a file of the skill changes while the update is being written, agentx stops with exit code 6, keeps your change and says that recovery is required: restore the file it names to let the next command finish the update. To keep your change instead, move the named file in ~/.agentx/mutations aside; the skill then shows as modified against the new version, with no update available. agentx keeps what it replaces until the update is complete, so an interrupted update finishes on the next command, running the update again included, and loses nothing.

​
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. Every change counts, whatever tool made it, except files your ignore rules name: they 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. Copies are handled as for any update: 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 changes nothing in your library. The merge waits in a Git worktree of the account repo in agentx home, ~/.agentx/merges/<name>, and never in the directory your agents read, so an agent never loads a half-merged file with conflict markers in it; the skill keeps working exactly as you left it. 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 worktree holds a Git merge in progress like any other: your edits are checked out and the update is being merged into them. It holds the skill one folder down, and the hint names that folder, so the files listed are found there by the paths shown. The merge stays until you finish it or give it up, across restarts, and agentx skill list shows the skill as merge pending. Meanwhile:
  • skill revert, 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. The update does not apply the merge, and stops with exit code 6, if the skill’s library directory changed while the merge was pending, or if something outside agentx moved the skill’s record in the account repo. 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

  • A skill with a merge pending that still has files to resolve stops with exit code 4 and lists them.
  • agentx skill update <name> of a skill whose source you removed stops with exit code 5, and the hint names the agentx source add command that brings the source back. With --all, the skill is skipped with a warning that names the same command, and the run does not fail. Either way, the update found earlier is kept.
  • A skill its source no longer holds, shown as upstream removed, is kept as it is and never updated: exit code 6.
  • A skill agentx did not install, and a fork, have no update to apply: exit code 6.
  • A skill whose library directory is gone stops with exit code 6. Install it again with agentx skill add <source> --skill <name>, or stop managing it with agentx skill remove <name>.
  • A skill whose record in the account repo agentx cannot read stops with exit code 6. Run agentx doctor and check the account repo it names.
  • A skill whose library directory is a symlink to a directory of your own stops with exit code 6, even if you edited that directory: an update replaces the library directory, so it would remove your link. Replace the link with the directory it points to, then update again. With --all this skill is counted as not updated.
  • A skill that holds something git cannot record, such as a repository nested in it, stops with exit code 6 and names it: an update would discard it with no record of it anywhere. Move it out of the skill, then update again. With --all this skill is counted as not updated.
With --all, a skill that is not updated does not stop the others: agentx names it and still updates the rest, then exits with the code those skills share, or 6 when they differ. A skill whose source you removed is skipped rather than counted, so it leaves the exit code at 0.

​
Script it

Add --json to get one library_skill event per skill:
placements lists every path each client sees the skill through, so Cursor, which also reads Claude Code’s skills directory, appears twice. The text of skill list counts Cursor once, and that of skill add and skill place shows one row per client. skill place and skill remove --from <client> emit one library_skill event too, whose placements are what the rescan found in the clients the command covered; skill remove without --from, or with --from universal, emits none, the skill being gone. skill add emits a source event for the source it installed from, whose last_fetched says when it was fetched, then a progress event per step per skill (blobs, import and install), then one for the rescan at the end, then one library_skill event per skill it installed, then result with a one-line summary. total counts the steps the run planned; a skill it has to skip takes its remaining steps out of that count, so the run always ends on its total. universal lists every universal client on this machine, whether or not the command placed into it, and is [] when none is installed. skill add and skill place end their result summary with the same always available to universal clients: words as their text. After --force, the summary of skill place adds ; discarded what <path>, ... held before them, naming every directory it discarded. The event carries two content hashes at its top level: base_hash is the version the skill was installed at, and content_hash is what the library directory holds now. Both names mean the same at the top level of every event and snapshot entry agentx emits; inside candidate, described below, content_hash names the newer version instead. state compares the files themselves, their permissions and symlinks included, so a skill whose only change is a file made executable is modified while its two hashes still agree. drift lists every other way a managed skill has drifted, beside its state, and is absent when there is none. Its values are displaced, missing, source removed and upstream removed:
Read drift as a list: more values will join it, and a skill can be in several at once. The snapshot of agentx scan and agentx serve lists every library skill the same way, under library, and agentx serve tells you when a skill’s state changes, see Drift. skill diff emits one diff event per file, sorted by path, with the file’s path relative to the skill’s directory, its status (added, modified or deleted) and the patch git wrote for it:
path and patch are JSON strings, which hold UTF-8 only: a byte that is not valid UTF-8, in a file name or in a file that is not UTF-8 text, arrives as U+FFFD. Such a patch is for display; the text output prints the bytes as they are. skill revert emits one library_skill event for the skill, with every placement, as skill list does. A skill with an update carries candidate, the newer version the last check found, by its own upstream_commit and content_hash. Inside candidate both name that newer version, not the version you installed and not what the library holds:
skill check emits a progress event per source it fetched, then one update_available event per skill with an update, sorted by name, then result:
upstream_commit and base_hash are the version you have, candidate_upstream_commit and candidate_hash the newer one, and candidate the commit agentx recorded for it, the one installing that version would write. files lists what the update changes, in the words of skill diff. upstream_name appears when the newer version names the skill otherwise; the skill keeps its name. skill diff --update emits one diff event per file. skill update emits one library_skill event per skill it updated, sorted by name, with every placement, as skill list does. The updated skill has no candidate, and its upstream_commit and base_hash now name the version it was updated to; a skill whose edits were merged is still modified. The result summary says what the run did, as in updated pdf from 3f2a9c1 to 8b1e0f4, 1 copy placement refreshed, updated docx from 3f2a9c1 to 8b1e0f4 and merged its edits cleanly, or with --all, updated 2 skills, 1 edited skill merged cleanly, 1 copy placement refreshed, which adds up what the update did to the copies of every skill and ends with the skills it skipped, as in 1 skill from a removed source skipped. For each skill whose edits conflict with its update, skill update emits one conflict event after the library_skill events, then the error:
base, mine and theirs at the top are the three versions merged: the commit of the version you installed, your library directory as git records it, without the files your ignore rules name, and the update. They are the base, the HEAD and the MERGE_HEAD of the merge in ~/.agentx/merges/<name>. Each file is one that conflicts there and names the blob each version holds, null for one that has no file there: to show a file, feed two of its versions to a diff tool. Every path is a path of the skill, relative to its directory. A skill with a merge pending carries pending_merge: true in its library_skill event and in the snapshot:

​
Where it is recorded

The account repo is a Git repository in agentx home, ~/.agentx/account.git, that plain git can read. Every install writes one commit per skill in it: the version’s files, the source it came from, the last upstream commit that changed the skill and its content hash. That commit is the same on every machine that installs the same version, however recently each one fetched the source, so your machines agree on what “the version you have” means without sending anything anywhere. A skill installed on its own and the same skill installed as part of a bulk install get the same commit.

​
Exit codes

  • 1: the command line names no skill to install, the flags contradict each other (--all with --skill, --except without --all, --except leaving nothing, or --from universal with a client that is not universal), it names the source with another branch or tag than its pin, skill add is given something that is not a source (for example, the name of a skill the library already holds), or skill update was given both a name and --all, neither, or --abort with --all.
  • 3: the source, or the files of the skill, could not be fetched. For skill check, also a run whose sources and skills failed for different reasons.
  • 4: skill update found your edits conflicting with the update and left the merge pending, or found files of a pending merge still to resolve, or a merge already pending blocks skill revert or a skill remove that takes the skill off the machine. See When your edits conflict.
  • 5: a source id names no source on this machine (for a source you removed, the hint names the agentx source add command that brings it back), the source did not serve a skill’s files, the path or a skill named by --skill or --except does not exist in the source, or --to or --from names a configuration that is not detected. For skill place, skill diff, skill revert and skill update (except with --abort), also a name the library does not hold as a skill; for skill update, also a skill whose source you removed; for skill remove, a name that is neither a skill of the library nor a managed skill whose library directory is gone. For skill check, also a source added on this machine that it has never fetched, such as one agentx import brought back; agentx source add fetches it.
  • 6: the library already holds a different skill under that name, the name is already managed at another version, the skill’s name cannot be both a directory and a git branch, the skill’s directory in the source is not one agentx can record, the skill holds a file whose path would put it outside the skill’s directory, agentx cannot use your library directory, or an interrupted change has to be resolved before anything else can run. The message names what to restore; if you would rather keep what is there, move the named file in ~/.agentx/mutations aside. For skill remove, it is also --from naming a universal client, one that reads the library directly, even next to --from universal, removing a name that is a fork, and --from <client> for a skill whose library directory is gone. For skill diff and skill revert, it is a skill agentx did not install or a fork, which have no base version, or a managed skill whose import branch records no version agentx can read; for skill diff --update, also a skill no check has found an update for; for skill check, a newer version agentx will not install, for the reasons skill add refuses one; for skill revert, also a skill that changed while it was being reverted, a skill whose installed version another command changed meanwhile, a skill that holds something git cannot record, or a skill whose library directory is a symlink. For skill place, it is a displaced directory that differs from the library when --force is not given, --force on a fork, a managed skill whose library directory is gone, a skill or placement that changed while it was being placed, a library directory that is a symlink or holds one when the command would remove a displaced directory, and a client’s directory it would change that symlinks make overlap the library, a directory a library entry links to or another client’s directory. For skill update, it is a skill agentx did not install or a fork, a managed skill whose library directory is gone or whose import branch records no version agentx can read, a skill its source no longer holds, a skill that holds something git cannot record, a skill whose library directory is a symlink, or a skill, its installed version or its update that changed while it was being updated. For skill update of a skill with a merge pending, it is also a library directory edited or a record moved outside agentx while the merge was pending, see Finish the merge; for skill update --abort, any name with no merge pending, one the library does not hold included. In a run of several skills other than skill check, 6 is also the code when the skills that were skipped disagree about why: a run whose failures all have one cause exits with that cause, so a batch that skipped two skills the source did not serve exits 5.
  • 7: another agentx command is running. Retry when it finishes.
  • 8: the account repo in agentx home cannot be read or written. Run agentx doctor. For skill update, also an update recorded in a form this agentx does not write; run agentx skill check to record it again.
  • 10: agentx could not read its own settings file, the library still held the skill after skill remove took it away, or agentx hit an error it has no better answer for. Run agentx doctor.