Adom Hydrogen (Linux)
Public Made by Adomby adom
The Linux platform layer for Adom Hydrogen: Ubuntu, Debian and Fedora, the workspace and the computer.
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 equalsname:, 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'sskills/public-facing/shared/, published toadom/hydrogen-bootstrapwithscripts/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
--helpand 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:
- The page repo (what renders at
/skills): clone it, apply the same edit, push withadom-wiki repo push <org>/<pkg> --files skills/<name>/SKILL.md -m "...". - The package artifact (what
pkg install/updatedelivers): from the same edited tree, bumpversioninpackage.json, strip AppleDouble junk (find . -name "._*" -delete), thenCOPYFILE_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.
Related skills
- 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
---
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.
## Related skills
- **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