Skip to content

Install and update your Hadron skills

CLI onlyIntermediate~5 min

Every skill your Hadron memories publish can be installed on this machine and kept up to date with one command. Your coding agent picks them up at its next session start, and running the same command again later brings them up to date.

This one needs the hadron CLI: a build that has skill export, signed in as you. If your coding agent has a terminal (Claude Code, Codex, Cursor), you can simply ask it:

Run hadron skill export --dry-run, show me what it would change, then run it for real.

The rest of this page is what that does, and what to do when the report refuses or skips something. To publish a task as a skill in the first place, see Export a task node as a Claude Code skill.

Before you start

  • The hadron CLI, signed in (hadron auth status). If hadron skill export --help answers unknown command "export" for "hadron skill", your build predates it: upgrade to v0.16.0 or later first.
  • Nothing else. The command creates the skills directories if they are missing.

Install

Preview first. A dry run reports exactly what the real run will do and changes nothing, not even a missing directory:

hadron skill export --dry-run

Then install:

hadron skill export

The report lists each skill under its host and where it went:

claudeSkill → /Users/you/.claude/skills
STATE    SKILL                 DETAIL
written  drive-pr-home         No installed skill exists for this declaration.
written  create-node           No installed skill exists for this declaration.
skipped  end-worker-session    description is 1180 characters; the host caps it at 1024 …

codexSkill → /Users/you/.agents/skills
  nothing to export for this host

Hosts load skills when a session starts: restart a running session to pick up changes.

Restart your agent's session afterwards. Hosts read skills only at session start.

What it installs, and where

It installs every enabled skill you can read, from every memory, for every host it knows. There is no selector and no prompt.

Host Directory
Claude (claudeSkill) ~/.claude/skills/<name>/SKILL.md
Codex (codexSkill) ~/.agents/skills/<name>/SKILL.md

The deprecated ~/.codex/skills is never written or cleaned. When two memories publish the same name, the report shows the source's URN beside it so you can tell them apart.

Your own skills are safe. A SKILL.md the export doesn't recognise as Hadron's — no provenance header, or a header it can't read as one — is someone else's, and the export never changes, moves or removes it. (A copy you exported by hand with a recognised Generated from line is Hadron's: see Skills you exported by hand earlier.) If it sits under a name one of your Hadron skills wants, that Hadron skill is refused rather than written. See below.

Update

Run the same command again:

hadron skill export

A skill that already matches its source is reported as skipped with The installed skill already matches the source node, and is left alone. Anything that changed at the source is rewritten. A skill renamed at its source moves to its new directory, and one whose source has been switched off is removed. Restart the session to pick up the changes.

Read the report

State Meaning Exit
written Installed or updated. 0
moved Renamed at its source, and moved to the new directory. The detail says where it came from. 0
removed Switched off at its source, so its SKILL.md was deleted (the directory too, if nothing else was in it). 0
skipped Nothing done, and the detail says why. See below. 0
orphaned A Hadron skill whose source node is gone, or no longer declares it. Kept until you pass --prune. 0
pruned An orphan removed, because you passed --prune. 0
refused Kept as it is. The detail says why: local edits, another skill already using the name, or a skill directory that is a symbolic link. 5
failed Could not be written. The row's detail says why. If the whole host failed, as with a symlinked skills root, the line above the table says so and every skill is failed. 5

One failing skill never stops the others. The command finishes the whole report and then exits 5 if anything was refused or failed, so a script can still check the exit code.

Recover

"The installed skill has local edits"

Someone edited the installed SKILL.md by hand, so the export keeps it and reports refused. The file is generated from a Hadron node, and that node is the source of truth. Choose one:

  • Your edit should survive: make the change in the source node (or ask its owner to). The installed file still counts as hand-edited afterwards, so a plain export keeps refusing it: finish with the --force step below, once the node has your change.
  • Your edit can go: overwrite it with --force. But --force has no selector: it overrides every refusal it can in that run, not just this one. Preview it with the same flags:
hadron skill export --dry-run --force

Every would write, would move and would remove row is exactly what the real run does, including other hand-edited skills and ones their owners have switched off. Save anything you want to keep, then:

hadron skill export --force

--force applies to this run only, and never touches a skill that isn't Hadron's.

If the skill's SKILL.md is itself a symbolic link, a changed skill is reported as local edits, and --force then fails with "is a symbolic link, so it was left alone". The export never writes through a link. Replace the link with a real file, then run the export again.

When a skill is skipped

The detail names the reason. Most are fixed at the source node, by whoever owns it:

Detail says Fix
The installed skill already matches the source node. Nothing to do. It is current.
description is N characters; the host caps it at 1024 … The node's owner shortens the description.
node declares a skill but isRunnable is not true The owner marks the node runnable, or removes the declaration.
node has no content — the body IS the skill The owner writes the node's body.
The declaration is disabled for this host and has no installed file to remove. Nothing to do. The owner has switched it off and you don't have a copy. If you do have one, it is removed on the next ordinary run instead (a copy you edited is refused and kept).
The installed skill has no provenance node id … A copy you exported by hand. See Skills you exported by hand earlier.

A skipped skill you already have goes stale

If an older copy of a skipped skill is installed, it stays at its old version. The export neither updates nor removes it. That one skipped row is the only sign, so read the skipped rows, not just the exit code.

Orphaned skills

A skill whose source node was deleted, or no longer declares that skill, is reported as orphaned and left in place. --prune removes every orphan on the machine, and an orphan whose source is gone may be the only copy left. Look first:

hadron skill export --dry-run --prune

Every would prune row is a skill the real run deletes. Copy out anything you want to keep, then:

hadron skill export --prune

A removal deletes SKILL.md, then its directory only if nothing else is in it. Anything else you keep there stays.

This is different from a skill its owner has switched off, where the node still declares it but with enable: false. That one is removed on the next ordinary run, without --prune. A copy you have edited by hand is the exception: it is refused and kept.

Another skill already has that name

If a directory under your skills folder already holds a SKILL.md the export did not write, the Hadron skill of that name is refused, and the detail says the directory "holds a SKILL.md this command did not write … rename or remove it to export this skill here". The existing file is kept. --force doesn't override this: the export never replaces a file it can't claim as its own. Rename or move the other skill's directory, then run the export again.

A file whose Hadron header names a node that no longer exists is refused the same way, as "An installed directory already occupies this skill name", and is also listed as orphaned. Move it aside the same way.

Skills you exported by hand earlier

A skill written by the older by-hand procedure in Export a task node as a Claude Code skill carries a <!-- Generated from <URN> --> line instead of the header the command writes. This section is about copies in your user skills folder. A copy you put in a project's .claude/skills is outside what the export manages: update or remove it by hand. For a user-folder copy, what the export does depends on how that URN is spelled.

Generated from hrn:node:<org>:<memory>:<loc>, with single colons. The export recognises it as Hadron's and reports it as skipped: "The installed skill has no provenance node id. This export preserves it". To replace it with a managed copy:

  1. If you edited the file, copy your changes out first. The next step replaces it.

  2. Preview what --force does. It applies to the whole run, so it overrides every refusal it can, not just this file: all your hand-made copies at once, plus any other hand-edited or switched-off skill. Use the same flags:

    hadron skill export --dry-run --force

    Every would write, would move and would remove row is what the real run does. Save anything you want to keep from any of them first.

  3. Replace the hand-made copies:

    hadron skill export --force

Generated from hrn:node:<org>::<memory>::<loc>, with double colons. This spelling appeared in these docs' examples between June and early August 2026. The export doesn't recognise it as Hadron's, so it treats the file as someone else's: the skill is refused (see Another skill already has that name), and --force doesn't help. Move just those directories aside, which also keeps any edits you made, then install:

mkdir -p ~/skills-before-export
mv ~/.claude/skills/<name> ~/skills-before-export/
hadron skill export

Don't reach for --prune in either case. It removes every orphan on the machine, not just these, and an orphan whose source is gone may be the only copy left.

From then on, a plain hadron skill export keeps them current.

If one skill's own directory (~/.claude/skills/<name>) is a symbolic link, that skill is refused, and --force doesn't change it: the export never writes through a link. Replace the link with a real directory, or remove it, then run the export again.

If a skills directory, or any directory between your home and it, is a symbolic link, the export refuses to write anything for that host. Every skill is listed as failed, and the command exits 5. Writing through a link could put one host's skills in another host's directory. To fix it, replace the link with a real directory, then run the export again.

A skill doesn't show up in your agent

  1. Restart the session. Skills load at session start.
  2. Check what the export says about it. Run hadron skill export --dry-run and look for the skill. Every declared skill you can read is listed, current and disabled ones included. If it's listed as disabled, its owner hasn't enabled it. If it isn't listed at all, no node you can read declares it. See Export a task node as a Claude Code skill.