by adom

How to use the Adom Wiki without breaking pages — the wiki is six tools in one (git, package manager, releases, discussions, PRs, discovery), and three repo archetypes have emerged from real use: Page, Skillpack, and Family. Plus how to publish rich component pages (chips, molecules, boards). One install, 15 skills, plus a write-up of the design patterns for the people who build the wiki.

Overview Files Skills Discover Packages Releases Dependencies Issues Breadcrumbs Pull Requests1 Activity

Download

name: adom-wiki-skillpack user-invocable: true description: >-, wiki bloat, too many wiki pages, should this be a page. The Adom Wiki Skill Pack, the entry point for working with the Adom Wiki (wiki.adom.inc). Read this BEFORE creating, publishing, or restructuring any wiki page. The wiki is six tools in one (git host + wiki package manager (`adom-wiki pkg`) + release database + discussion forum + pull requests + discovery), and three repo archetypes have emerged from real use: Page, Skillpack, and Family. This pack routes to 16 focused sub-skills and carries the hard rules that keep pages from breaking. Trigger words: adompkg (deprecated old name), the wiki, adom wiki, wiki.adom.inc, publish to the wiki, wiki repo, wiki page, what kind of wiki repo, repo archetype, skillpack, super-skill, wiki family, parent child repo, wiki readme, hero unlinked, proprietary wiki page, private source public app, wiki breadcrumb, fork a wiki page, wiki discovery, page not surfacing, wiki scoring, trending, high five, adom-wiki pkg publish, publish a chip, component page, chip page, molecule page, tape and reel, pin 1 orientation.

Adom Wiki Skill Pack

The Adom Wiki at https://wiki.adom.inc is the single canonical wiki. This pack is the map for working with it, and it is the source of truth: the skills here plus the repo archetypes that have emerged from heavy real-world use. Update this pack directly when the wiki changes.

adompkg is the deprecated old name of the package manager. It is dead; do not run it. Every old adompkg <verb> maps to adom-wiki pkg|page|repo|release <verb> (e.g. adompkg publish -> adom-wiki pkg publish, adompkg install -> adom-wiki pkg install). If a doc or a user says adompkg, translate and continue.

The wiki is six tools in one

It feels like a wiki, but it's a fusion of six tools you already know, all keyed off one slug per page:

Git host, every page is a real git repo (Files tab, commits, contributors).
adom-wiki pkg, an npm-style package manager: dependency maps, adom-wiki pkg update.
Release database, versioned binary/tarball releases (like GitHub Releases).
Discussion forum, a thread per page (like GitHub Issues).
Pull requests, community edits proposed to a repo, the owner reviews/merges.
Discovery, how a page/skill gets found (search, /discover triggers, local skill matching); a first-class pillar, fed by the scoring/trending signals.

Plus a presentation layer (a plain README.md, or a custom readme.html, plus a separate private readme for proprietary-source pages). Full model → wiki-anatomy.

Three repo archetypes (pick one before you publish)

Archetype	One line	Examples	Build skill
Page	One page = one thing. Open-source (public source) or Closed-source (private source, public compiled app).	chip-fetcher, adom-usb / hydrogen-desktop, adom-desktop	wiki-visibility
Skillpack	One repo, one main skill + N sub-skills, installed together. Suffix `-skillpack`.	adom-ui-design, this pack	wiki-skillpack
Family	An anchor page + children published as separate pages, joined by naming + a family tag + breadcrumbs.	adom-desktop, adom-usb	wiki-family

Decision: Skillpack when one author owns all the skills and they version together; Family when children have independent owners or update cadences (e.g. per-vendor scrapers that change daily). Full taxonomy → wiki-repo-styles.

The hard rules (the page-breakers)

These are the mistakes that recur. They each have a dedicated skill, but they're important enough to state up front:

⛔ NEVER use em-dashes (,) in ANY wiki content (John, 2026-06-26): page titles, briefs, descriptions, README bodies, hero text, sample prompts, changelogs, even commit messages. Use a comma, a regular hyphen -, or a colon :. The en-dash – is banned too. ASCII punctuation only.

Write BOTH storage layers, every publish. The git repo (Files/README) and the package registry (tarball/adom-wiki pkg install) are independent. Do only one and the page is broken. → wiki-api, wiki-publish-safely.
adom-wiki pkg publish clobbers the hero. It overwrites the repo's page.json with the package manifest (which has no hero), so the page-header hero gets unlinked on every publish. The image isn't deleted, its reference is. Fix: publish FIRST, then push a complete page.json (with hero) to git LAST. → wiki-hero, wiki-publish-safely.
NEVER embed the hero image in the README body. The wiki renders the hero at the top of the page automatically (from page.json). Repeating it inline shows the human the same image twice, redundant and rude. README images must be OTHER screenshots, never the hero. → wiki-readme.
Never base64 a text file. Text (.md, .json, .sh) goes as plain content; only real binaries (images) go base64. → wiki-api.
Versions are immutable. Bump before republishing; never delete-and-recreate (soft-delete trips a UNIQUE constraint). → wiki-publish-safely.
Verify with your eyes. After ANY wiki edit, open the live page in pup and screenshot-confirm it rendered before calling it done. → wiki-publish-safely.

Skill map

Skill	Use it for
wiki-anatomy	The mental model: the six tools in one, and how the layers relate.
wiki-api	The REST API + `adom-wiki pkg` CLI, the two storage layers, the publish workflow.
wiki-publish-safely	The operational pitfalls as hard rules; the verify-in-pup gate.
wiki-readme	How to make a great README: `README.md` vs `readme.html`, sections, embeds, images.
wiki-readme-html	Build a custom `readme.html`: sandbox limits, shadowing, self-containment, theming, verify loop.
wiki-sub-readme	Make a sub-readme: a 2nd doc in the page repo, linked from the README. The repo-push / relative-link / image-path gotchas.
wiki-visibility	Public vs private source, public releases, the private readme, open vs closed pages.
wiki-repo-styles	The archetype taxonomy (Page / Skillpack / Family) and how to choose.
wiki-component	Publish a component page: chip / molecule / board; the tabbed chip CAD-hub README.
wiki-family	Build a Family: naming convention, family tag, anchor registry, breadcrumbs.
wiki-skillpack	Build a Skillpack: layout, install.sh, files[], skill map, the `-skillpack` suffix.
wiki-hero	The hero image: generate it (adom-wiki-hero-image), and never let it get unlinked.
wiki-hero-studio	Generate the page hero: RUN `hero-studio pose <owner/slug>` (human clicks Generate). Do NOT open its wiki page.
wiki-breadcrumbs	Third-party "I built an add-on for X" links: the breadcrumb system.
wiki-forking	Fork + community-PR contribution flow (PRs live; fork-button planned).
wiki-discovery	How pages get found: the two layers, current state, and the TODO list.
wiki-scoring	Stars / high-fives / installs / trending: what's tracked and how to earn it.
wiki-bloat	THE rule against page sprawl: find where a thing already lives BEFORE creating anything; "add to the skillpack" means add a SKILL.md there, never mint a page.

Talk to the AI

"Publish this tool to the wiki" → wiki-api + wiki-publish-safely
"What kind of wiki repo should this be?" → wiki-repo-styles
"Make a hero for this page" / "the hero disappeared" → wiki-hero
"Show/open hero studio" / "generate a hero" / HERO_STUDIO_REQUIRED → wiki-hero-studio (RUN the app, do not browse the page)
"Write a README for this page" → wiki-readme
"I want a custom HTML readme / tabs / designed layout" → wiki-readme-html
"Make a sub-readme" / "my README is too long, split it" / "link a deep-dive doc" → wiki-sub-readme
"Keep the source private but let people install it" → wiki-visibility
"Bundle these skills into one package" → wiki-skillpack
"Add a child plugin to adom-usb" → wiki-family
"Publish this chip / molecule / board to the wiki" → wiki-component

---
name: adom-wiki-skillpack
user-invocable: true
description: >-, wiki bloat, too many wiki pages, should this be a page.
  The Adom Wiki Skill Pack, the entry point for working with the Adom Wiki
  (wiki.adom.inc). Read this BEFORE creating, publishing, or restructuring any
  wiki page. The wiki is six tools in one (git host + wiki package manager (`adom-wiki pkg`) +
  release database + discussion forum + pull requests + discovery), and three repo
  archetypes have emerged from real use: Page, Skillpack, and Family. This pack
  routes to 16 focused sub-skills and carries the hard rules that keep pages from
  breaking. Trigger words: adompkg (deprecated old name), the wiki, adom wiki, wiki.adom.inc, publish to the
  wiki, wiki repo, wiki page, what kind of wiki repo, repo archetype, skillpack,
  super-skill, wiki family, parent child repo, wiki readme, hero unlinked,
  proprietary wiki page, private source public app, wiki breadcrumb, fork a wiki
  page, wiki discovery, page not surfacing, wiki scoring, trending, high five,
  adom-wiki pkg publish, publish a chip, component page, chip page, molecule page,
  tape and reel, pin 1 orientation.
---

# Adom Wiki Skill Pack

The Adom Wiki at **https://wiki.adom.inc** is the single canonical wiki. This
pack is the map for working with it, and it is the **source of truth**: the
skills here plus the repo archetypes that have emerged from heavy real-world
use. Update this pack directly when the wiki changes.

> **`adompkg` is the deprecated old name of the package manager.** It is dead; do not run it. Every old `adompkg <verb>` maps to `adom-wiki pkg|page|repo|release <verb>` (e.g. `adompkg publish` -> `adom-wiki pkg publish`, `adompkg install` -> `adom-wiki pkg install`). If a doc or a user says adompkg, translate and continue.

## The wiki is six tools in one

It feels like a wiki, but it's a fusion of six tools you already know, all
keyed off one slug per page:

1. **Git host**, every page is a real git repo (Files tab, commits, contributors).
2. **`adom-wiki pkg`**, an npm-style package manager: dependency maps, `adom-wiki pkg update`.
3. **Release database**, versioned binary/tarball releases (like GitHub Releases).
4. **Discussion forum**, a thread per page (like GitHub Issues).
5. **Pull requests**, community edits proposed to a repo, the owner reviews/merges.
6. **Discovery**, how a page/skill gets found (search, `/discover` triggers, local
   skill matching); a first-class pillar, fed by the scoring/trending signals.

Plus a **presentation layer** (a plain `README.md`, or a custom `readme.html`, plus
a separate **private readme** for proprietary-source pages). Full model →
**wiki-anatomy**.

## Three repo archetypes (pick one before you publish)

| Archetype | One line | Examples | Build skill |
|---|---|---|---|
| **Page** | One page = one thing. Open-source (public source) or Closed-source (private source, public compiled app). | chip-fetcher, adom-usb / hydrogen-desktop, adom-desktop | wiki-visibility |
| **Skillpack** | One repo, one main skill + N sub-skills, installed together. Suffix `-skillpack`. | adom-ui-design, **this pack** | wiki-skillpack |
| **Family** | An anchor page + children published as separate pages, joined by naming + a family tag + breadcrumbs. | adom-desktop, adom-usb | wiki-family |

Decision: **Skillpack** when one author owns all the skills and they version
together; **Family** when children have independent owners or update cadences
(e.g. per-vendor scrapers that change daily). Full taxonomy → **wiki-repo-styles**.

## The hard rules (the page-breakers)

These are the mistakes that recur. They each have a dedicated skill, but they're
important enough to state up front:

> ⛔ **NEVER use em-dashes (,) in ANY wiki content** (John, 2026-06-26): page titles, briefs,
> descriptions, README bodies, hero text, sample prompts, changelogs, even commit messages. Use a
> comma, a regular hyphen `-`, or a colon `:`. The en-dash `–` is banned too. ASCII punctuation only.

1. **Write BOTH storage layers, every publish.** The git repo (Files/README) and
   the package registry (tarball/`adom-wiki pkg install`) are independent. Do only one
   and the page is broken. → **wiki-api**, **wiki-publish-safely**.
2. **`adom-wiki pkg publish` clobbers the hero.** It overwrites the repo's `page.json`
   with the package manifest (which has no `hero`), so the page-header hero gets
   unlinked on every publish. The image isn't deleted, its reference is. **Fix:
   publish FIRST, then push a complete `page.json` (with `hero`) to git LAST.** →
   **wiki-hero**, **wiki-publish-safely**.
3. **NEVER embed the hero image in the README body.** The wiki renders the hero
   at the top of the page automatically (from `page.json`). Repeating it inline
   shows the human the same image twice, redundant and rude. README images must
   be OTHER screenshots, never the hero. → **wiki-readme**.
4. **Never base64 a text file.** Text (`.md`, `.json`, `.sh`) goes as plain
   `content`; only real binaries (images) go base64. → **wiki-api**.
5. **Versions are immutable.** Bump before republishing; never delete-and-recreate
   (soft-delete trips a UNIQUE constraint). → **wiki-publish-safely**.
6. **Verify with your eyes.** After ANY wiki edit, open the live page in pup and
   screenshot-confirm it rendered before calling it done. → **wiki-publish-safely**.

## Skill map

| Skill | Use it for |
|---|---|
| **wiki-anatomy** | The mental model: the six tools in one, and how the layers relate. |
| **wiki-api** | The REST API + ``adom-wiki pkg`` CLI, the two storage layers, the publish workflow. |
| **wiki-publish-safely** | The operational pitfalls as hard rules; the verify-in-pup gate. |
| **wiki-readme** | How to make a great README: `README.md` vs `readme.html`, sections, embeds, images. |
| **wiki-readme-html** | Build a custom `readme.html`: sandbox limits, shadowing, self-containment, theming, verify loop. |
| **wiki-sub-readme** | Make a sub-readme: a 2nd doc in the page repo, linked from the README. The repo-push / relative-link / image-path gotchas. |
| **wiki-visibility** | Public vs private source, public releases, the private readme, open vs closed pages. |
| **wiki-repo-styles** | The archetype taxonomy (Page / Skillpack / Family) and how to choose. |
| **wiki-component** | Publish a component page: chip / molecule / board; the tabbed chip CAD-hub README. |
| **wiki-family** | Build a Family: naming convention, family tag, anchor registry, breadcrumbs. |
| **wiki-skillpack** | Build a Skillpack: layout, install.sh, files[], skill map, the `-skillpack` suffix. |
| **wiki-hero** | The hero image: generate it (adom-wiki-hero-image), and never let it get unlinked. |
| **wiki-hero-studio** | Generate the page hero: RUN `hero-studio pose <owner/slug>` (human clicks Generate). Do NOT open its wiki page. |
| **wiki-breadcrumbs** | Third-party "I built an add-on for X" links: the breadcrumb system. |
| **wiki-forking** | Fork + community-PR contribution flow (PRs live; fork-button planned). |
| **wiki-discovery** | How pages get found: the two layers, current state, and the TODO list. |
| **wiki-scoring** | Stars / high-fives / installs / trending: what's tracked and how to earn it. |
| **wiki-bloat** | THE rule against page sprawl: find where a thing already lives BEFORE creating anything; "add to the skillpack" means add a SKILL.md there, never mint a page. |

## Talk to the AI

- "Publish this tool to the wiki" → wiki-api + wiki-publish-safely
- "What kind of wiki repo should this be?" → wiki-repo-styles
- "Make a hero for this page" / "the hero disappeared" → wiki-hero
- "Show/open hero studio" / "generate a hero" / HERO_STUDIO_REQUIRED → wiki-hero-studio (RUN the app, do not browse the page)
- "Write a README for this page" → wiki-readme
- "I want a custom HTML readme / tabs / designed layout" → wiki-readme-html
- "Make a sub-readme" / "my README is too long, split it" / "link a deep-dive doc" → wiki-sub-readme
- "Keep the source private but let people install it" → wiki-visibility
- "Bundle these skills into one package" → wiki-skillpack
- "Add a child plugin to adom-usb" → wiki-family
- "Publish this chip / molecule / board to the wiki" → wiki-component