agentx skill new, fork with agentx skill fork or adopt as they are with agentx adopt. agentx keeps the history of each one in the account repo on this machine, ~/.agentx/account.git. To use them on your other machines, publish them to your account remote, a Git repository you own. You need an account remote only when you publish. Every client sees your own skills like any other skill.
A skill you fork from an installed skill keeps its upstream, the skill it came from, so you can take in newer versions later. A skill you create or adopt has no upstream.
Create a skill
SKILL.md with the name and the description in its frontmatter and a line that asks for the instructions. Open ~/.agents/skills/release-notes/SKILL.md in your library and write the instructions. Leave out --description to fill it in later.
agentx links the skill into every enabled client, as agentx skill add does. Each link is a placement. Clients that read the library directly, such as Codex, Cursor and Gemini CLI, need no link. See Clients that see every skill.
To publish the skill:
- Set an account remote once:
agentx source add <url> --account. The last output line shows only while none is set. - Publish the skill by name:
agentx skill publish release-notes.
agentx skill list shows the skill as not published. agentx skill publish with no name skips skills that you never published.
agentx skill list shows the skill as managed. Its source column shows your account remote URL with (account), or account remote not set.
Choose a name
Use 1 to 64 lowercase letters, digits and hyphens, with no hyphen at the start or end and no two in a row, such asrelease-notes.
agentx refuses the name, and changes nothing, when:
- it breaks the rule above;
- you already have a skill of that name, even with different capital letters. For example, a skill you installed as
Notesblocksnotes; - your library or
~/.agentx/worktreesalready holds something under that name.
Fork a skill
Fork a skill to edit it with a history of your own. You can fork a skill agentx installed, a plugin’s skill or one of your own skills. An installed skill is replaced by its fork:- The fork takes the skill’s place in your library, under the same name. Each client that reads the library, or has a link to the skill, now sees the fork. See What each client sees after a fork.
- The fork keeps the skill’s files as they are now, your edits included.
- The fork is one of your own skills. Publish it as you publish a skill you create.
- A fork of an installed skill remembers the version it came from, so
agentx skill listshows its upstream afterfrom, and you can update it to newer versions later. - Files that stay local, such as a
.DS_Store, move with the skill and are never published.
agentx skill fork stops with exit code 6 and names the command that adopts it:
- the library entry is a symlink you made;
- the skill folder holds its own
.git; - the library and
~/.agentxare on different file systems.
.git folder, you can also move it out of the skill first.
Fork under a new name
- The fork sits beside the skill, which stays exactly as it was.
- agentx writes the new name into the fork’s
SKILL.md, as part of the fork’s first commit. - The fork goes into the same clients as the skill, with a copy wherever the skill has a copy.
- Use a new name to fork a skill whose own name breaks the naming rule, such as
My_Skill.
Fork one of your own skills
One of your own skills already owns its name, so fork it under a new one:agentx skill fork my-pdf --name pdf-letters. The new skill starts from the last commit of the one you fork and keeps its history. The new skill includes your unpublished edits. Publish it to put it on your account remote. See Unpublished edits are kept.
The new skill holds the skill’s folder alone. A file you committed with Git next to the folder, such as a README.md at the root of the worktree, stays with the skill you forked. If the original skill is missing from your library, agentx does not place the new skill in any client. Place it with agentx skill place.
Fork a plugin’s skill
Name a plugin’s skill with its plugin, as<plugin>:<skill>:
- The plugin keeps its skill. agentx cannot change or remove it.
- The fork goes into your library and into the enabled clients that have the plugin. Clients that read the library also see it.
- A client that has the plugin and sees the fork has more than one skill named
format. The client decides which one it uses. The last line names those clients. - To avoid two skills with the same name, fork it under a new name:
agentx skill fork formatter:format --name my-format. In the desktop app, Use a different name starts on for a plugin’s skill. - The skill’s name alone,
agentx skill fork format, names a skill of your library, never a plugin’s.
What each client sees after a fork
A client sees every skill in every folder it reads. A fork changes your library, so what a client sees after it depends on how the client reaches the library: by reading it, through a link, or through a copy. See Where skills live.
When a client has more than one skill with the same name, the client decides which one it uses, or it shows them all. agentx does not control this. To keep them apart, fork under a new name, or rename your fork.
Publish your edits
Edit one of your own skills in any editor or agent, through your library.agentx skill list shows it as modified until you publish the edits. agentx publishes only when you run agentx skill publish.
~/.agentx/worktrees/<name>. The next publish pushes your commits. With -m, it combines them into one commit with your message.
Unpublished edits are kept
agentx skill update, agentx skill fork and agentx skill rename keep your unpublished edits. They save the edits first, then run. The edits stay unpublished: agentx skill list shows the skill as modified, and agentx skill diff shows the edits. If you edit the skill while the command runs, it stops with exit code 6. Run it again. A new skill that agentx skill fork makes starts from those edits, so it shows as current.
To discard your edits before you run such a command, put the skill’s last commit back with Git in its worktree, then delete the files you added:
.env.
To drop edits that an update, fork or rename already recorded, reset the skill’s worktree to the commit agentx skill diff <name> compares with, such as its last published version:
Read a skill’s history
- Commits are listed newest first, each with the number of files it changes in the skill. Add
--jsonto see the file names. - An upstream version, the one the fork started from or one an update merged in, is dated by its upstream commit.
- With
--json, each commit is ahistoryevent with its full message, its author and the machine that wrote it. A commit with no machine was made with Git. A file outside the skill folder, such as aREADME.mdat the root of the worktree, starts with../.
See what changed
skill diff shows your unpublished edits. It compares the skill folder with the version you last published. A skill you never published is compared with the version you created, adopted or forked. Files that stay local do not show.
To compare with an earlier commit, use --commit with an id that agentx skill history lists:
Take a new upstream version
A fork of an installed skill keeps its upstream.agentx skill check-updates finds newer upstream versions for it. Read an update, then take it:
- agentx merges the new version into your fork. Your changes are kept, and upstream changes to lines you did not touch come in.
- The merge is committed on the skill’s branch, as
release-notes: merge upstream 5d6e7f8 (laptop). Nothing is pushed: the fork shows asmodifieduntil you publish it. - With an account remote set, agentx first updates the fork to what your other machines published, then merges the new version on top, as two commits. If Git cannot reach the remote, agentx warns and takes the upstream version alone.
- Your unpublished edits are kept. See Unpublished edits are kept.
- Files that stay local are kept. If the new version holds a file at a path your ignore rules cover, that file replaces your local one, as
git checkoutdoes. agentx skill update --allupdates every managed skill with an update, your own skills included.- A skill you created or adopted, or forked from a plugin’s skill, has no upstream. For such a skill,
skill updateonly takes what your other machines published. Without an account remote, it stops with exit code 6. - If two machines took different upstream versions, run
agentx source fetchbefore you update.
Resolve a conflict
When your commits and the update change the same lines, your skill stays as it is, folder and branch alike, and the merge waits in a Git worktree,~/.agentx/merges/<name>. The command exits with code 4 and lists the files:
- Resolve each file with Git in
~/.agentx/merges/<name>/<folder>: edit it, or rungit checkout --ours <file>orgit checkout --theirs <file>, thengit addit. Runninggit committhere is optional, with any message: agentx still records which upstream version the fork now has. - Run
agentx skill update <name>again. agentx commits the merge on the skill’s branch and lays it out in the skill’s folder.
- If you edit the skill while the merge waits, agentx keeps the edits. If they conflict, resolve them the same way.
- Give the merge up with
agentx skill update <name> --abort. Your skill, its branch and the update stay as they were.
release-notes conflicts with the account remote in 1 file. See Update to what another machine published.
- A binary file or a symlink that both machines changed conflicts as a whole, with no markers: the waiting merge holds this machine’s version. Keep it, or take the other machine’s with
git checkout --theirs <file>, thengit addit. - If two machines take the same upstream version, publish from one and update the other before you edit again. Otherwise the next update can conflict. Resolve it and keep the lines you want.
Where your skills live
- The branch is
skills/<name>in the account repo. Plaingitreads it:git --git-dir ~/.agentx/account.git log skills/release-notes. - agentx checks the branch out in
~/.agentx/worktrees/<name>. You can run Git there. - Your library holds a symlink to the skill.
user.name and user.email. If you have not set them, it uses the machine label.
Files that stay local
Publishing one of your own skills records what Git would record in any repository: files your.gitignore, your global Git ignore file or the ignore_system_files list cover stay on your machine and are never published. If the skill holds a Git repository, agentx refuses to publish it. To publish anyway, list that repository in the skill’s .gitignore.
Recover a skill of your own
agentx puts one of your own skills back from its branch when something on disk went missing.agentx skill list names what is wrong, and so does the desktop app; any other agentx skill command warns about it once before its own output. Fix it with skill place:
- A deleted worktree is checked out again from the skill’s last commit on this machine, and the library symlink is written again. Edits not yet recorded in a commit are gone with the deleted folder. Everything agentx or you committed comes back, published or not.
- A library symlink that is missing or leads nowhere is written again.
- A worktree whose Git pointers broke, for example because you moved
~/.agentx, is repaired withgit worktree repair. agentx does not repair a copied worktree. - If a Git command you ran in the worktree, such as a merge, is waiting for you, finish or abort it first.
- If you switched the worktree to another branch, switch it back to the skill’s branch first, with the
git switchcommand agentx names.
agentx serve, makes the same repairs when it starts.
Something in the way
agentx never deletes or overwrites a folder of yours to recover a skill. When a folder sits where the skill’s worktree or library symlink belongs,skill place stops with exit code 6 and changes nothing:
--force to adopt the folder:
- A folder at
~/.agentx/worktrees/<name>becomes the skill’s worktree again, with its files kept. It must hold only the skill folder. Move other files out first. - A folder at the library entry moves into the skill’s worktree. If the worktree already holds edits of its own, publish or discard them first. If its skill folder holds files Git ignores, such as a local
.env, move the ones you want to keep into the folder you adopt first; agentx names them and changes nothing. System files such as a.DS_Storeare discarded with it. - A symlink of yours at the library entry is replaced; it holds no files.
SKILL.md, skill place stops with exit code 5 and changes nothing. Add a SKILL.md first.
What you adopt shows up as unpublished edits. Keep them with agentx skill publish <name>. --force on a skill with nothing in the way stops with exit code 6.
Rename a skill of your own
Rename one of your own skills withskill rename:
- The renamed skill is the same skill: it keeps its id and every commit of the old one. Its
SKILL.mdcarries the new name. - It is placed where the old one was, as a copy wherever the old one was a copy.
- If the new name is taken or a merge is waiting, the rename stops and nothing changes. Your unpublished edits move to the renamed skill. See Unpublished edits are kept.
- Only your own skills can be renamed. A skill you installed from a shared source, or one agentx does not manage, stops with exit code 6. Adopt an unmanaged skill first.
- Only the skill folder moves. Files Git ignores, such as a local
.env, and files beside the skill folder in the worktree are deleted. Copy the ones you want first. - The renamed skill shows as
modifieduntil you publish it under its new name.
- The first publish under the new name removes the old name from your account remote. If it cannot, it warns once. Then remove the old name with
agentx skill remove <old> --remote. - Your other machines keep the old name until you remove it there. To get the new name there, run
agentx skill add --name <new>, thenagentx skill remove <old>. - If the account remote refuses because the old branch is its default branch, make another branch the default, then run
agentx skill remove <old> --remote.
agentx skill remove <old> command it names.
If you edited or committed to the old skill while the rename ran, the removal stops, since the renamed skill lacks that work. To keep it, remove the renamed skill with agentx skill remove <new> and run the rename again, which records the edits. To drop it, run agentx skill remove <old>.
Remove a skill of your own
Remove one of your own skills from this machine withskill remove:
- agentx removes the skill from every client, your library and
~/.agentx. - Unpublished edits are deleted. Publish them first to keep them.
- If a merge is waiting, or Git is running in the worktree, agentx does not remove the skill. Finish or abort first.
- The skill’s branch stays on the account remote, and every other machine keeps the skill until you remove it there.
--remote to delete the skill’s branch from the account remote as well:
- Run it again if the account remote could not be reached. With the skill gone from this machine, it deletes the branch on the account remote alone.
- A hosting service refuses to delete a repository’s default branch. If the first skill you published became the default branch, make another branch the default on the hosting service, then run the command again.
- If the account remote’s branch of that name is another skill, agentx refuses to delete it.
not published, as it shows a skill you never published:
- With no published version left to compare with, that machine compares the skill with the commit that created it, so it also shows as
modifiedif it changed since then. - A bare
agentx skill publishthere skips the skill and names it, so it does not bring the branch back. - Remove it there with
agentx skill remove <name>. To keep it on the account remote after all, publish it by name from that machine withagentx skill publish <name>, which puts its branch back.
--from, as for any skill: see Remove a skill.
Exit codes
For what each code means, see Exit codes. Foragentx skill publish, see the agentx skill exit codes. These causes are special to your own skills: