main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-skill-loop description: >- Maintainer loop for fixing a wrong Hydrogen skill on Linux: verify against the running system, fix the live copy, fix the text at its source (the Hydrogen repo's Linux set or a wiki package), ship it. Use when a skill is wrong or stale, or to publish a skill fix. disable-model-invocation: true

Hydrogen Skill Loop: verify, fix live, fix the source, ship

Hydrogen's skills are the only way the in-workspace AI knows anything about Hydrogen. A wrong skill silently breaks every user's AI (it curls a dead hostname, hunts a command that doesn't exist, claims it needs a tool that isn't installed…). This skill is the loop to find those and make them perfect.

Cardinal rule: TEST, don't assert

Never write a skill claim from memory, old skill text, or docs — verify it against the running system first. Run the command. Read the live env. Read the code. Observe the real return shape. If you can't test a claim, don't state it as fact. (Most skill bugs are confident, untested assertions.)

Where skills live — the live copy and the text source

Copy Where Role
Live (ephemeral) ~/.claude/skills/<name>/SKILL.md (flat) What the running AI reads NOW. Editing it fixes this session and lets you test, but the next Hydrogen launch or package update replaces it.
Text source depends on who ships it (below) Where the fix must land.
Shipped a Hydrogen build (Linux set) or a wiki package What every workspace gets. A fix isn't done until it ships.

Who ships which skill on Linux:

  • The Linux set (every skill Hydrogen writes on Linux): the Hydrogen repo, skills/public-facing/shared/<name>/SKILL.md (one source per skill: the Linux text is its shared text plus its Linux platform blocks). The build embeds its Linux render (hydrogen-setup/build.rs, linux_skills.rs) and Hydrogen writes it over ~/.claude/skills/ at every launch and package convergence. A fix ships with the next Hydrogen build, not a wiki publish. Rules the build's gate test enforces: the folder name equals name:, no folder carries a platform suffix, and the text names no other platform's host tools or paths.
  • Platform-generic hydrogen-* skills not in the Linux set: the Hydrogen repo's skills/public-facing/shared/, published to adom/hydrogen-bootstrap with scripts/publish-skills-to-bootstrap.sh <skill>... (it clones the wiki repo, refuses to clobber lines that exist only in the wiki copy, bumps the patch version and publishes). If the Linux set has a skill of the same name, fix that one too, or Linux users keep the old text.
  • Every other package: its wiki page repo is the source. Clone it, edit, publish.

Find which package owns a skill: adom-wiki pkg list shows installed packages; the skill's frontmatter and content usually name their set, and the package's wiki page (https://wiki.adom.inc/<org>/<pkg>/skills) lists what it ships.

If the folder exists in the Hydrogen repo's skills/public-facing/shared/, Hydrogen owns the Linux text.

The loop

1. Reproduce / notice

A skill made the AI do the wrong thing. Name the skill and the exact wrong claim.

2. Get ground truth from the LIVE system

  • Run the real command and read its --help and actual output: adom-cli hydrogen <verb> --help → then run it → note the EXACT return shape.
  • Read the live env, never hardcode: env | grep ADOM_, adom-cli hydrogen probe, the control-URL file if present.
  • Read the Hydrogen source for the endpoint/behavior when you have a checkout.

3. Fix it live + re-test

Edit ~/.claude/skills/<name>/SKILL.md to match what you verified. Re-read it, then re-run the failing action to confirm the fix actually works.

4. Fix the source

For a skill in the Linux set, edit skills/public-facing/shared/<name>/SKILL.md in the Hydrogen repo (the shared text, or its Linux block when only Linux differs). It ships with the next Hydrogen build, not a wiki publish.

For any other package, a fix must land on both wiki surfaces, or the wiki page still shows the stale skill:

  1. The page repo (what renders at /skills): clone it, apply the same edit, push with adom-wiki repo push <org>/<pkg> --files skills/<name>/SKILL.md -m "...".
  2. The package artifact (what pkg install/update delivers): from the same edited tree, bump version in package.json, strip AppleDouble junk (find . -name "._*" -delete), then COPYFILE_DISABLE=1 adom-wiki pkg publish --org <org>. Fix lint errors rather than skipping the linter.

Staging both from one clone of the page repo keeps them identical.

If you added / renamed / removed a skill, also update the package's index skill (e.g. hydrogen-overview for hydrogen-bootstrap) and check for cross-references to the old name in the rest of the package.

5. Converge + verify

adom-wiki pkg update in a workspace, then re-read the installed skill and confirm the wiki page shows the fix. Note: a package upgrade does not prune skills an older version delivered — after a rename/delete, remove the stale ~/.claude/skills/<old-name> directory too.

For a Linux-set skill, install the Hydrogen build that carries the fix and re-read the skill after its next launch.

Validation checklist before you publish a skill

  • Every command in the skill was actually RUN and produced the documented output.
  • No invented CLI verbs — each confirmed with --help.
  • No tool assumed present that isn't in the workspace — test before relying on it.
  • Endpoint paths / ports / step names match CURRENT code (they drift fast).
  • No content about deprecated or unimplemented features — it only pollutes context.
  • Linux mechanics live in the Linux set; a Linux skill never describes another platform.
  • Cross-links use sibling skill names that resolve flat at deploy.
  • name: matches the directory.

Why this matters

The skills ARE Hydrogen's self-knowledge for the AI. Ship them wrong and every Adom user's AI is confidently wrong with them. Treat "the skill is inaccurate" as a product bug and run this loop until the validation checklist is clean.

  • hydrogen-staying-current — how workspaces receive published package updates
  • hydrogen-wiki-review — load the edited wiki page in pup so the user can review it
  • hydrogen-self-update: how a new Hydrogen build (and its Linux skills) arrives