Skip to main content
A source is a git repository that holds one or more skills. Add it once by its URL. agentx fetches it and lists the skills inside, so you can choose what to install. agentx skill add adds the source itself when you install from a URL you have not added yet. Your account remote is a special source: the repository you publish your own skills to. In the desktop app, open Skills, then Sources. See Sources in the app.

Add a source

Paste the URL in whatever form you have: A path after the repository, such as owner/repo/skills, scopes the listing to that directory. On a server other than GitHub, end the repository name with .git so agentx knows where the repository ends and the path begins. A GitLab tree URL, with /-/tree/<ref>/<path>, needs no .git. No part of the path can be ., .. or .git. Adding a source you already have fetches it again. The confirmation tells you what moved:

Pin a source

A ref is a branch, a tag or a commit of a repository. A source’s pin is the ref agentx fetches for it. A source has at most one pin. To pin a source, add #<ref> to its URL:
  • Without a pin, the source follows the repository’s default branch. #HEAD does the same.
  • A tree URL pins the ref it names. For a branch with a slash in its name, such as release/1.x, use #release/1.x.
  • To change the pin, add the source again with the new ref. If you add it again without a ref, agentx removes the pin.
  • agentx source fetch and agentx source skills keep the pin. Given another #<ref>, they stop with exit code 1.
  • agentx source list shows the pin in its branch column.

Credentials

The fetch runs with your own git, so the credential helper, SSH key and URL rewrites you use in a terminal apply here too. A private repository you can already clone just works. Add each source by the URL agentx should fetch from and push to. To fetch a source over HTTPS and push to it over SSH, set Git’s own url.<base>.pushInsteadOf, for example git config --global url.git@github.com:.pushInsteadOf https://github.com/. Keep tokens out of the URL. If a URL holds a user name, a password or a token, agentx drops it and warns you. In an SSH URL, agentx keeps the user name, such as git@, and drops only a password. Store the credential in a Git credential helper instead:

Write access

agentx checks whether you can push to a source each time it adds one, with agentx source add, agentx skill add or agentx adopt, and each time you run agentx source fetch. agentx source list shows the answer in its access column: The check pushes nothing. It uses your own Git, credentials, SSH configuration and URL rewrites. It never asks for a password or passphrase, and it gives up after 30 seconds. If it gets no answer, the command still succeeds. To give the check of some sources another SSH key, key the setting on the URL as agentx source list prints it, for example includeIf "hasconfig:remote.*.url:ssh://git@github-work/**". The check ignores patterns in the git@host:path form and includeIf "gitdir:..." settings. A source you can write to can still refuse a push to a protected branch, or a push that a server hook rejects. The check cannot see those rules. If your organisation uses single sign-on or an IP allow list, the server may not report your access until you authorise your token or key. agentx then warns you:
Authorise it with your host, then fetch the source again to check once more. agentx skill check-updates and the desktop app’s background process never check access.

What is fetched

agentx fetches only what it needs to list skills: the directory trees of one branch and each skill’s SKILL.md. If the server cannot serve such a partial fetch, agentx fetches the whole repository. After a fetch, listing any part of the source needs no network. If a fetch fails or you stop it, the source stays at the last version that arrived complete. Fetch again to get the new version.

A failed add leaves nothing behind

If an add cannot finish, agentx undoes it. If the add fails while another agentx command runs for too long, agentx cannot undo it. It then names what it left and how to clear it:
Run either command in the hint. Adding the source again finishes the add. Removing it by id clears the leftover.

Fetch a source again

A fetch updates what agentx knows about a source: the commit it holds, the skills inside it, and whether you may write to it. Run it to see what changed in the source. You often do not need to. agentx skill check-updates fetches the sources your managed skills came from on its own. With an account remote set, it also fetches the account remote whenever one of your own skills is placed on this machine. When the desktop app opens, its background process fetches every source you added, once, including the ones you have not installed anything from yet. Name several sources to fetch them together, by URL or by id, or fetch every source on this machine:
Sources are fetched in parallel, a few at a time, and each one gets a line that says what moved:
--all fetches your account remote too, after the other sources. Its line counts the skills of yours it holds:
A source that fails is a warning naming it and does not stop the others. Every source that did fetch is recorded, and the command then fails, naming the ones that did not. If they all failed for the same reason, the exit code is the one that source would give on its own; if the reasons differ, it is 3. A fetch keeps the source’s pin. It always covers the whole source, even when the URL holds a path.

List your sources

List the skills of a source

Every directory with a SKILL.md is a skill. Hidden directories and node_modules are skipped. Give a path to see one part of the repository, for example anthropics/skills/skills/pdf. You can also name the source by its id. The command reads what the last add or fetch stored and makes no network calls. A #<ref> that differs from the source’s pin is refused with exit code 1.

Remove a source

The source and everything fetched from it leave this machine. Skills you installed from it stay as they are, in your library and in your clients, and keep their record of where they came from. agentx skill list shows each of those skills as source removed, and the inventory the desktop app reads says the same:
Add the source again to fetch it anew and clear the state:
Your skills and their placements stay as they are. You can add the source at any pin. Installing a skill from the source by its URL, or adopting one with agentx adopt, also adds the source again. After you remove a source, commands no longer accept its id, because agentx needs the URL to fetch it. While a skill still records the source, the error names the command to run:
Once you remove the last of those skills with agentx skill remove <name>, agentx no longer knows the source’s URL. Add the source again by its URL. Removing your account remote clears it from this machine’s settings. Your own skills stay on this machine, and nothing on the remote changes:

Add your account remote

The account remote is a Git repository you own. You publish your own skills to it: the skills you create with agentx skill new or fork with agentx skill fork. Your other machines install them from it. For why you need one and what to choose when you create it, see Account remote. Create a repository on your Git host, then add it with --account:
  • Give any URL Git can reach. In the user@host:path form, agentx reads the path from the server’s root, so on your own server give the full path, for example git.example.com:/srv/git/forks.git. GitHub and GitLab URLs work either way.
  • Give the repository alone: a #<ref>, a path or a token in the URL is refused with exit code 1. Keep credentials in a Git credential helper or an SSH key, as for any repository.
  • If Git cannot reach the repository, agentx stops with exit code 3 and changes nothing.
  • agentx source list shows it with (account).
  • Only your own skills travel through it. Skills you install from other sources, their update checks and the sources themselves stay on each machine.
  • A machine without an account remote keeps the whole history of your own skills: agentx skill history and agentx skill diff work without one. Add it when you want a backup, or a second machine.
  • Adding the account remote’s URL again, with or without --account, fetches it again.
  • Adding another URL with --account replaces the account remote. Your own skills stay on this machine. agentx skill list shows them as not published until you publish each one to the new remote with agentx skill publish <name>. agentx skill publish with no name skips them.
  • A source you added without --account cannot become the account remote, even under another URL for the same repository. agentx stops with exit code 6. Remove the source first with agentx source remove <url>, then add the account remote.

Exit codes

For what each code means, see Exit codes. These causes are special to agentx source:
  • 1: the URL is not one of the accepted forms, or its #<ref> and its tree URL name different refs. Also: the account remote’s URL carries a token, a ref or a path; source fetch or source skills names a ref other than the source’s pin; or source fetch was given both sources and --all, or neither.
  • 3: the source cannot be reached, is not a git repository, or needs credentials git does not have. The hint names the fix. From source fetch over several sources, it also means they failed for different reasons. Read the warnings.
  • 5: the pinned ref or the path does not exist in the source, the source is not on this machine, or what this machine holds of it is incomplete. For an id of a source you removed, the hint names the agentx source add command that brings it back.
  • 6: source skills names your account remote, or source add names its repository by another URL. List its skills with agentx skill list --remote, and install one with agentx skill add --name <name>. See Install your skills on another machine. Exit code 6 also means --account named a source you added without it, by the same or another URL.
  • 7: another agentx command is running. Retry when it finishes. An add that could not undo its work says what it left and how to clear it.
  • 8: the account repo in agentx home cannot be read or written. Run agentx doctor.