Skip to main content
Your own skills are the skills you create with 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

The skill starts from a template: a 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:
  1. Set an account remote once: agentx source add <url> --account. The last output line shows only while none is set.
  2. Publish the skill by name: agentx skill publish release-notes.
Until you publish it, 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 as release-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 Notes blocks notes;
  • your library or ~/.agentx/worktrees already 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 list shows its upstream after from, 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 does not fork a skill it does not manage, such as a directory you put in your library yourself. agentx skill fork stops with exit code 6 and names the command that adopts it:
Adopting makes it one of your own skills, with its files as they are. See Skills adopted as they are. agentx cannot fork a skill in its place, and stops with exit code 6, when:
  • the library entry is a symlink you made;
  • the skill folder holds its own .git;
  • the library and ~/.agentx are on different file systems.
Fork it under a new name instead. For a .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.
Publishing records your edits as one commit and pushes it to your account remote. See Publish a skill. You can also commit with Git in ~/.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:
These commands keep files that Git ignores, such as a local .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:
This drops every commit made since that one, an update’s merge included.

Read a skill’s history

  • Commits are listed newest first, each with the number of files it changes in the skill. Add --json to 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 a history event 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 a README.md at the root of the worktree, starts with ../.
In the desktop app, select one of your own skills in Skills. History lists its latest commits; select Show all to see every commit and the files each one changed. When agentx knows the web page of the skill a fork came from, such as a plugin’s repository, the name of the plugin, source or skill in the commit that created the fork is a link: select it to open the page in your browser. For a fork of a source’s skill on GitHub, GitLab or Bitbucket, the fork’s name is a link too: it opens the skill’s folder at the commit you forked. A fork made with an earlier version of agentx has no link.

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 as modified until 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 checkout does.
  • agentx skill update --all updates 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 update only 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 fetch before 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:
  1. Resolve each file with Git in ~/.agentx/merges/<name>/<folder>: edit it, or run git checkout --ours <file> or git checkout --theirs <file>, then git add it. Running git commit there is optional, with any message: agentx still records which upstream version the fork now has.
  2. 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.
A conflict with what another machine published waits the same way. The first line then reads 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>, then git add it.
  • 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. Plain git reads 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.
agentx writes commits with your Git 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 with git 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 switch command agentx names.
The desktop app’s background process, 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:
This happens when a worktree’s registration was removed with Git, or when another tool replaced the library symlink with a copy. Add --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_Store are discarded with it.
  • A symlink of yours at the library entry is replaced; it holds no files.
If the folder has no 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 with skill rename:
A rename works on this machine alone. The old name’s folder, worktree and branch go, and the skill carries on under the new name.
  • The renamed skill is the same skill: it keeps its id and every commit of the old one. Its SKILL.md carries 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 modified until you publish it under its new name.
In the desktop app, open one of your own skills and select Rename, type the new name, then select Rename. The first publish of the new name renames it on the account remote:
  • 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>, then agentx 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.
If the removal fails after the renamed skill was made, the error says so. Finish the rename with the 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 with skill 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.
Add --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.
Your other machines keep the skill. The next time one of them fetches the account remote, it shows the skill as 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 modified if it changed since then.
  • A bare agentx skill publish there 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 with agentx skill publish <name>, which puts its branch back.
To take one of your own skills out of one configuration only, use --from, as for any skill: see Remove a skill.

Exit codes

For what each code means, see Exit codes. For agentx skill publish, see the agentx skill exit codes. These causes are special to your own skills: