Adom Wiki Skill Pack

One install, 15 skills that teach the AI to use the Adom Wiki without breaking pages — plus a write-up of the wiki repo archetypes that have emerged from real use.

Publishing to wiki.adom.inc is powerful but fraught: the AI re-breaks pages (unlinks heroes, base64-mangles READMEs, writes only one of the two storage layers, forgets to verify what it shipped). And as the wiki has been used heavily, a set of repo archetypes has quietly emerged — patterns nobody had named or written down. This pack fixes both: it bundles the publishing know-how as installable skills, and it names the archetypes so they can be used deliberately.

📌 Note for Colby (and anyone building the wiki): the section The repo archetypes is for you. It documents the page structures that have emerged from heavy real-world use of the wiki — Page, Skillpack, and Family — and a few features they lean on (private source + public releases, the private readme, breadcrumbs, scoring). Some of it is built, some is partial, some is still a spec; each skill labels its status honestly. This is meant as a design mirror: here's how your heaviest user is actually structuring repos, so the platform can meet those patterns.

Install

adompkg install adom-wiki-skillpack

This drops the main adom-wiki-skillpack skill plus 14 sub-skills onto your container, and pulls in adom-wiki-hero-image (a dependency) for hero generation.

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:

Plus a presentation layer (README.md or a custom readme.html, and a separate private readme for proprietary pages). The scoring/trending signals (stars / high-fives / installs) feed Discovery's ranking.

Discovery is a first-class pillar, and it's the least-finished one. Layer 1 (local installed-skill matching) works; Layer 2 (the registry /discover endpoint) does not yet match declared discovery_triggers. The wiki-discovery skill carries the current state + a TODO list of what discovery still needs — see it (and finding #3 in our Colby feedback).

The single most important consequence: the git repo and the package registry are two independent storage layers. adompkg publish does not push your source to git, and pushing files does not make a tarball. A correct publish writes both. Doing one leaves the page half-broken — the root of most incidents.

The repo archetypes (emerging from real use)

Three repo shapes have emerged. Naming them turns "how should I structure this?" into a deliberate choice.

1. Page — one page = one thing

A single page for a single app/tool/skill/doc. Two sub-variants by source visibility:

• Open-source Page — source public + installable. e.g. chip-fetcher, adom-usb. MIT, contributions welcome.
• Closed-source Page — source private, releases/adompkg public, so people install the compiled app but can't read the code. e.g. hydrogen-desktop, adom-desktop. Uses the private readme so the page still has public docs.

The wiki lets the git source, the release/package, and the readme each be public or private independently — that's what makes a proprietary app and an open-source library both first-class on the same platform.

2. Skillpack — one repo, one main skill + N sub-skills

One repo / one installable package carrying a whole set of skills, deployed together by a single adompkg install. Sub-skills are files under skills/, not separate pages. Convention: the slug ends in -skillpack so the class is recognizable.

• e.g. adom-ui-design (grandfathered, predates the suffix), and this pack.
• This very repo is a Skillpack — it dogfoods its own archetype.

3. Family — an anchor page + separately-published children

An anchor page plus children published as their own pages, joined by convention rather than living in one repo:

• Slug <parent>-<descriptor>; Title leads with the parent (Adom USB - CDC serial sniffer); a family tag (<parent>-plugin); and breadcrumbs linking children back to the anchor.
• e.g. adom-desktop (+ bridges), adom-usb (+ sniffer/firmware plugins).

Skillpack vs Family — the decision rule

Both are "a main thing + many smaller things." The divider is ownership and update cadence:

• Skillpack when one author owns all the parts and they version together.
• Family when children have independent owners or release cadences — each is its own page, and third parties can add their own without touching the anchor.

Worked example — chip-fetcher: it's open source AND has many per-vendor scraper skills (DigiKey, Mouser, TI, Analog Devices) that change daily and that third parties want to own. As a Skillpack, every vendor tweak would force the single owner to re-publish the whole pack. So it's better as a Family: an anchor plus chip-fetcher-digikey, chip-fetcher-mouser, … each independently publishable, discovered via the family tag + breadcrumbs. Rule of thumb: does each part need its own lifecycle and maybe its own author? Yes → Family.

The hard rules (page-breakers)

The pack encodes these; they're worth stating here too:

1. Write both storage layers every publish (git + registry).
2. adompkg publish clobbers the hero — it overwrites the repo's page.json (no hero), so the hero gets unlinked (not deleted) on every publish. Fix: publish first, push a complete page.json LAST. (This is the recurring "hero disappeared" bug.)
3. Never base64 a text file — only real binaries are base64.
4. Versions are immutable — bump; never delete-and-recreate (soft-delete trips a UNIQUE constraint).
5. Verify with your eyes — open the live page in pup and screenshot it before calling any wiki edit done.

Skills in this pack

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
• "Write a README for this page" → wiki-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 / a bridge to adom-desktop" → wiki-family

Dependencies

Companion tools (not hard dependencies): adompkg itself (the package manager), and adom-desktop / pup for the verify-in-pup step.

Relationship to gallia

Gallia's adom-wiki-v2 and adom-wiki-hero-image skills remain the employee-internal source of truth. This pack is the public, installable digest of that knowledge plus the archetype taxonomy — same model as adom-ui-design. Update gallia first, then refresh this page.

License

MIT.