skill
Adom Wiki Skill Pack
Public Made by Adomby adom
The Adom Wiki Skill Pack : one main skill plus the focused sub-skills that teach the AI to publish to wiki.adom.inc without breaking pages, name the wiki repo archetypes (Page, Skillpack, Family), and publish rich component pages (chips, molecules, boards). The wiki is six tools in one: git, package manager, releases, discussions, pull requests, and discovery. One package manager install drops the whole set onto your container. Includes reviewed Z-up component artwork, surface-selected MPN marki
← Commit history
Publish 0.2.0
9 files changed
+254−75
README.md+16−8@@ -1,6 +1,6 @@ # Adom Wiki Skill Pack -**One install, 13 skills that teach the AI to use the Adom Wiki without breaking+**One install, 14 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.** @@ -27,13 +27,13 @@ deliberately. adompkg install adom-wiki-skillpack ``` -This drops the main `adom-wiki-skillpack` skill plus 12 sub-skills onto your+This drops the main `adom-wiki-skillpack` skill plus 13 sub-skills onto your container, and pulls in **`adom-wiki-hero-image`** (a dependency) for hero generation. -## The wiki is five tools in one+## The wiki is six tools in one -It feels like a wiki, but it's a fusion of five tools you already know, all keyed+It feels like a wiki, but it's a fusion of six tools you already know, all keyed off one slug per page: | # | Tool | Like | What it powers |@@ -43,10 +43,17 @@ off one slug per page: | 3 | **Release database** | GitHub Releases | versioned downloadable binaries | | 4 | **Discussions** | GitHub Issues | a forum thread per page | | 5 | **Pull requests** | GitHub PRs | community edits, owner reviews/merges |+| 6 | **Discovery** | npm search / app-store surfacing | how a page/skill gets found — search, `/discover` triggers, local skill matching | -Plus a **scoring/trending** layer (stars / high-fives / installs) and a-**presentation** layer (`README.md` or a custom `readme.html`, and a separate-**private readme** for proprietary pages).+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@@ -133,7 +140,7 @@ The pack encodes these; they're worth stating here too: | Skill | What it's for | |---|---| | **adom-wiki-skillpack** | Entry point: the five-tools model, the archetypes, the hard rules, the map. |-| **wiki-anatomy** | The mental model — five tools in one, and the two storage layers. |+| **wiki-anatomy** | The mental model — six tools in one, and the two storage layers. | | **wiki-api** | The REST API + `adompkg` CLI and the publish workflow. | | **wiki-publish-safely** | Operational pitfalls as hard rules + the verify-in-pup gate. | | **wiki-readme** | Make a great README — `README.md` vs `readme.html`, sections, embeds. |@@ -144,6 +151,7 @@ The pack encodes these; they're worth stating here too: | **wiki-hero** | Generate a hero, and never let it get unlinked. | | **wiki-breadcrumbs** | Third-party "I built an add-on for X" links _(implemented, basic)_. | | **wiki-forking** | Fork + community-PR contribution _(PRs live; fork-button planned)_. |+| **wiki-discovery** | How pages get found — the two layers, current state, and the TODO list _(Layer 1 live; `/discover` partial)_. | | **wiki-scoring** | Stars / high-fives / installs / trending _(stars live; rest partial)_. | ## Talk to the AI
SKILL.md+12−9@@ -4,15 +4,16 @@ user-invocable: true description: >- 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 five tools in one (git host + adompkg package manager +- release database + discussion forum + pull requests), and three repo+ wiki page. The wiki is six tools in one (git host + adompkg package manager ++ release database + discussion forum + pull requests + discovery), and three repo archetypes have emerged from real use: Page, Skillpack, and Family. This pack- routes to 12 focused sub-skills and carries the hard rules that keep pages from+ routes to 13 focused sub-skills and carries the hard rules that keep pages from breaking. Trigger words: 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 scoring, trending, high five, adompkg publish.+ page, wiki discovery, page not surfacing, wiki scoring, trending, high five,+ adompkg publish. --- # Adom Wiki Skill Pack@@ -24,9 +25,9 @@ pack is the **public, installable digest** of that knowledge plus the repo archetypes that have emerged from heavy real-world use — update gallia first, then refresh this page. -## The wiki is five tools in one+## The wiki is six tools in one -It feels like a wiki, but it's a fusion of five tools you already know, all+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).@@ -34,9 +35,10 @@ keyed off one slug per page: 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. -Cross-cutting: a **scoring/trending** system (stars / high-fives / install counts)-and a **presentation layer** (a plain `README.md`, or a custom `readme.html`, plus+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**. @@ -80,7 +82,7 @@ important enough to state up front: | Skill | Use it for | |---|---|-| **wiki-anatomy** | The mental model: the five tools in one, and how the layers relate. |+| **wiki-anatomy** | The mental model: the six tools in one, and how the layers relate. | | **wiki-api** | The REST API + `adompkg` 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. |@@ -91,6 +93,7 @@ important enough to state up front: | **wiki-hero** | The hero image: generate it (adom-wiki-hero-image), and never let it get unlinked. | | **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. | ## Talk to the AI
install.sh+3−2@@ -20,7 +20,8 @@ install_skill wiki-skillpack skills/wiki-skillpack/SKILL.md install_skill wiki-hero skills/wiki-hero/SKILL.md install_skill wiki-breadcrumbs skills/wiki-breadcrumbs/SKILL.md install_skill wiki-forking skills/wiki-forking/SKILL.md+install_skill wiki-discovery skills/wiki-discovery/SKILL.md install_skill wiki-scoring skills/wiki-scoring/SKILL.md -echo "OK: Installed the Adom Wiki Skill Pack plus 12 bundled skills to $DEST/."-echo "Hint: Ask Claude 'publish this to the wiki', 'what kind of wiki repo should this be', or 'how do I make a readme'."+echo "OK: Installed the Adom Wiki Skill Pack plus 13 bundled skills to $DEST/."+echo "Hint: Ask Claude 'publish this to the wiki', 'what kind of wiki repo should this be', 'how do I make a readme', or 'why isn't my wiki page surfacing'."
package.json+6−2@@ -1,8 +1,8 @@ { "slug": "adom-wiki-skillpack",- "version": "0.1.4",+ "version": "0.2.0", "type": "skill",- "description": "The Adom Wiki Skill Pack — one main skill plus 12 focused sub-skills that teach the AI to publish to wiki.adom.inc without breaking pages, and that name and document the wiki repo archetypes (Page, Skillpack, Family) that have emerged from real use. One adompkg install drops the whole set onto your container.",+ "description": "The Adom Wiki Skill Pack — one main skill plus 13 focused sub-skills that teach the AI to publish to wiki.adom.inc without breaking pages, and that name and document the wiki repo archetypes (Page, Skillpack, Family) that have emerged from real use. The wiki is six tools in one: git, adompkg, releases, discussions, pull requests, and discovery. One adompkg install drops the whole set onto your container.", "discovery_triggers": [ "publish to the wiki", "the wiki",@@ -27,6 +27,9 @@ "proprietary wiki page", "wiki breadcrumb", "fork a wiki page",+ "wiki discovery",+ "page not surfacing",+ "discover endpoint", "wiki scoring", "wiki trending" ],@@ -52,6 +55,7 @@ "skills/wiki-hero/SKILL.md", "skills/wiki-breadcrumbs/SKILL.md", "skills/wiki-forking/SKILL.md",+ "skills/wiki-discovery/SKILL.md", "skills/wiki-scoring/SKILL.md" ], "scripts": {
page.json+75−41@@ -1,46 +1,80 @@ {- "type": "skill", "slug": "adom-wiki-skillpack",- "title": "Adom Wiki Skill Pack",- "brief": "How to use the Adom Wiki without breaking pages — the wiki is five tools in one (git, adompkg, releases, discussions, PRs), and three repo archetypes have emerged from real use: Page, Skillpack, and Family. One install, 13 skills, plus a write-up of the design patterns for the people who build the wiki.",- "hero": {- "type": "image",- "path": "screenshots/hero.png"+ "version": "0.2.0",+ "type": "skill",+ "description": "The Adom Wiki Skill Pack — one main skill plus 13 focused sub-skills that teach the AI to publish to wiki.adom.inc without breaking pages, and that name and document the wiki repo archetypes (Page, Skillpack, Family) that have emerged from real use. The wiki is six tools in one: git, adompkg, releases, discussions, pull requests, and discovery. One adompkg install drops the whole set onto your container.",+ "discovery_triggers": [+ "publish to the wiki",+ "the wiki",+ "adompkg publish",+ "what kind of wiki repo",+ "wiki repo archetype",+ "skillpack",+ "super skill",+ "wiki family repo",+ "parent child wiki",+ "how to make a wiki readme",+ "wiki page presentation",+ "hero in readme",+ "hero shows twice",+ "duplicate hero",+ "don't repeat the hero",+ "hero unlinked",+ "hero disappeared",+ "name a child page",+ "family child title",+ "private source public app",+ "proprietary wiki page",+ "wiki breadcrumb",+ "fork a wiki page",+ "wiki discovery",+ "page not surfacing",+ "discover endpoint",+ "wiki scoring",+ "wiki trending"+ ],+ "dependencies": {+ "john/adom-wiki-hero-image": "^0.2.1" },- "visibility": {- "public": true+ "files": [+ "SKILL.md",+ "README.md",+ "page.json",+ "install.sh",+ "uninstall.sh",+ "screenshots/hero.png",+ "screenshots/archetypes.png",+ "skills/wiki-anatomy/SKILL.md",+ "skills/wiki-api/SKILL.md",+ "skills/wiki-publish-safely/SKILL.md",+ "skills/wiki-readme/SKILL.md",+ "skills/wiki-visibility/SKILL.md",+ "skills/wiki-repo-styles/SKILL.md",+ "skills/wiki-family/SKILL.md",+ "skills/wiki-skillpack/SKILL.md",+ "skills/wiki-hero/SKILL.md",+ "skills/wiki-breadcrumbs/SKILL.md",+ "skills/wiki-forking/SKILL.md",+ "skills/wiki-discovery/SKILL.md",+ "skills/wiki-scoring/SKILL.md"+ ],+ "scripts": {+ "install": "./install.sh",+ "uninstall": "./uninstall.sh" },- "metadata": {- "tags": [- "wiki",- "adompkg",- "publishing",- "skillpack",- "guidelines",- "documentation",- "repo-archetypes",- "open-source",- "mit"- ],- "discovery_triggers": [- "publish to the wiki",- "the wiki",- "adompkg publish",- "what kind of wiki repo",- "wiki repo archetype",- "skillpack",- "super skill",- "wiki family repo",- "parent child wiki",- "wiki readme",- "hero disappeared",- "hero unlinked",- "private source public app",- "proprietary wiki page",- "wiki breadcrumb",- "fork a wiki page",- "wiki scoring",- "wiki trending"- ]+ "tags": [+ "wiki",+ "adompkg",+ "publishing",+ "skillpack",+ "guidelines",+ "documentation",+ "repo-archetypes",+ "open-source",+ "mit"+ ],+ "author": {+ "name": "John Lauer",+ "email": "[email protected]" }-}+}
skills/wiki-anatomy/SKILL.md+15−11@@ -3,24 +3,24 @@ name: wiki-anatomy description: >- The mental model of the Adom Wiki (wiki.adom.inc): it is five familiar tools fused into one product keyed off a single slug per page — a git host, the- adompkg package manager, a release database, a discussion forum, and pull- requests — plus a scoring layer and a presentation layer. Read this to- understand WHAT the wiki is before learning HOW to drive it. Trigger words:- what is the adom wiki, how does the wiki work, wiki architecture, wiki mental- model, git plus npm plus releases, wiki page is a repo, two storage layers,- why both git and registry, wiki anatomy, explain the wiki.+ adompkg package manager, a release database, a discussion forum, pull requests,+ and discovery — plus a presentation layer. Read this to understand WHAT the wiki+ is before learning HOW to drive it. Trigger words: what is the adom wiki, how+ does the wiki work, wiki architecture, wiki mental model, git plus npm plus+ releases, wiki page is a repo, two storage layers, why both git and registry,+ wiki anatomy, explain the wiki, six tools in one. --- Parent skill: **adom-wiki-skillpack** # What the Adom Wiki actually is -The Adom Wiki looks like a wiki, but it is **five tools you already know, fused+The Adom Wiki looks like a wiki, but it is **six tools you already know, fused into one**, all addressed by a single `slug` per page. Understanding this is the prerequisite for everything else — most publishing mistakes come from treating it as one tool when it is really several stacked together. -## The five tools+## The six tools 1. **A git host (per page).** Every page owns a real git repo. The Files tab, README rendering, commit log, and contributors all read from it. You push to@@ -42,10 +42,14 @@ it as one tool when it is really several stacked together. 5. **Pull requests.** Community members propose edits to a page's repo; the owner reviews and merges. The contribution path for a wiki you don't own. -## Two cross-cutting layers+6. **Discovery.** How a page/skill gets FOUND — search, the `/discover` endpoint's+ trigger matching, and local installed-skill matching. A first-class pillar: a+ page that can't be discovered may as well not exist. The **scoring/trending**+ signals (stars, high-fives, installs) feed discovery's ranking. See+ **wiki-discovery** (and **wiki-scoring** for the signals).++## The presentation layer -- **Scoring / trending.** The wiki tracks signals — stars, high-fives, install- counts — to surface what's trending. See **wiki-scoring**. - **Presentation.** The Overview tab renders either a plain `README.md` or a custom `readme.html` for full control. A page whose source is private can also carry a **private readme** so the public still sees docs. See **wiki-readme**
skills/wiki-discovery/SKILL.mdadded+119@@ -0,0 +1,119 @@+---+name: wiki-discovery+description: >-+ Discovery on the Adom Wiki — a FIRST-CLASS component of the wiki, peer to git,+ adompkg, releases, discussions, and pull requests. How pages/skills get FOUND:+ the two layers (local installed-skill matching vs the registry /discover + search+ endpoints), how to make a page discoverable (manifest + page discovery_triggers),+ the current real state of what works and what doesn't, and the TODO list of what+ discovery still needs. Read this when a page won't surface, when setting+ discovery triggers, or when reasoning about how the AI finds the right skill.+ Trigger words: wiki discovery, discover endpoint, discovery_triggers, page not+ surfacing, skill not found, how does the AI find skills, wiki search, make a page+ discoverable, trigger words, /discover, registry discovery, why isn't my page+ showing up.+---++Parent skill: **adom-wiki-skillpack**++# Discovery — a first-class component of the wiki++Discovery is **not a nice-to-have bolted onto the wiki — it is one of its core+pillars**, on the same footing as the git host, the adompkg package manager, the+release database, the discussions forum, and pull requests (see **wiki-anatomy**).+A page that can't be discovered may as well not exist: discovery is how an AI (or+a human) finds the right skill/app/doc *for what they're doing right now*, ideally+**before** they've ever installed or starred it.++## The two layers of discovery++Discovery happens at two distinct layers. They are wired differently and fail+differently — know which one you're reasoning about.++### Layer 1 — Local installed-skill discovery (works today)++Once a skill is installed (`~/.claude/skills/<name>/SKILL.md`), the AI picks it by+matching the user's intent against the skill's **frontmatter `description`** —+specifically its trigger phrases. This is why every skill's description must end+with a generous, specific list of trigger words. This layer is reliable: if the+phrase is in the description and the skill is installed, the AI surfaces it.++→ To make a skill catch a specific mistake, put the failure-mode phrases in its+`description` (e.g. wiki-readme carries "hero shows twice", "duplicate hero" so it+fires the moment someone is about to embed a hero).++### Layer 2 — Registry discovery (search + /discover) — partially working++For pages a user has **not** installed yet, the wiki exposes:+- `GET /api/v1/search?q=<query>` — full-text search. **Works** (finds pages by+ slug/title/brief). Caveat: the FTS hyphen bug (`chip-fetcher` →+ "no such column: fetcher").+- `GET /api/v1/discover?triggers=<csv>` — intended to surface pages whose+ declared `discovery_triggers` match what the user is doing. **This is where+ discovery is currently weak — see the state + TODO below.**++You declare a page's triggers in the **package manifest** (`package.json`+`discovery_triggers: [...]`) and they ARE stored (verify:+`GET /api/v1/packages/<slug>/manifest`).++## ⚠️ Current real state (verified 2026-06-21 — re-verify, this WILL change)++- ✅ Local installed-skill discovery (Layer 1) works.+- ✅ `/search?q=` finds pages.+- ✅ Manifest `discovery_triggers` are accepted and stored server-side.+- ❌ **`/discover?triggers=` does NOT match manifest `discovery_triggers`.** It+ returns roughly the same fixed ~70-page set regardless of the triggers passed,+ so it appears to rank a popular set (stars/installs/recency) rather than match+ the requested phrases. A brand-new, correct, zero-engagement page is effectively+ invisible to trigger discovery until it organically accrues engagement — which+ is backwards (you discover something in order to *start* using it).+- ❌ Page-level `metadata.discovery_triggers` pushed via `page.json` to `/files`+ does not persist (reads back as `metadata: []` on `GET /pages/:slug`).++**Practical consequence today:** rely on Layer 1 (install the relevant skillpack,+then local discovery is solid) and on `/search` for pages. Don't assume+`/discover` will surface a fresh page by its triggers yet.++## 📋 TODO — what we need from discovery (for Colby)++Discovery deserves to be as solid as the wiki's other pillars. The asks, roughly+in priority order:++1. **Make `/discover?triggers=` actually match `discovery_triggers`.** Text-relevance+ match the requested phrases against each page's manifest (and persisted page)+ triggers — not just return a popular set. This is the core bug.+2. **Index triggers at publish time** so a page is discoverable the instant it's+ published, with no engagement required.+3. **Persist `page.json` `metadata.discovery_triggers`** (today it's dropped) — or+ document the manifest as the single source of truth and say so.+4. **Relevance + quality blend in ranking**, not quality alone: a highly-relevant+ new page should outrank a barely-relevant popular one.+5. **Author-side discovery preview/debug**: "what would `/discover` surface for+ trigger X, and why/where does my page rank?" so authors can test discoverability+ the way this skill pack dogfoods it.+6. **Unify the two layers**: expose the same trigger corpus so local skill+ discovery and registry discovery agree on what a page is "about."+7. **Synonym / fuzzy matching** so near-miss phrasings still hit.+8. **Per-type discovery** (skill vs app vs component vs bootstrap) and per-type+ ranking.+9. **Trigger conflict/dedup signal**: warn when two pages claim the same trigger,+ and support disambiguation/negative triggers.+10. **Exclude deprecated/soft-deleted/private pages** from public discovery.+11. **Fix the FTS hyphen bug** in `/search` (most Adom slugs contain hyphens).+12. **Discovery analytics**: which trigger surfaced a page, and install+ attribution, so authors can see discovery actually working (feeds **wiki-scoring**).++> ⏳ **UPDATE THIS SKILL when discovery is upgraded.** The "current real state"+> section above is a snapshot and is expected to go stale fast. After any wiki+> discovery change, re-run the probes (`/discover?triggers=`, manifest check,+> page metadata read-back), update the ✅/❌ list, and tick off the TODO items+> that shipped. Don't let this skill claim a broken thing works or a fixed thing+> is broken.++## Relationship to scoring++Discovery answers "can this be found?"; **wiki-scoring** covers the engagement+signals (stars / high-fives / installs / trending) that *rank* what's found. They+are linked — ranking is part of discovery — but distinct: a page can be perfectly+discoverable with zero stars, and discovery should surface it on relevance, with+scoring breaking ties among relevant results.
skills/wiki-scoring/SKILL.md+6@@ -19,6 +19,12 @@ The wiki tracks engagement signals so good pages surface — the equivalent of stars + download counts driving a "trending" view. The intent is to capture everything that indicates a page is valued; the surfacing is partly built. +These signals are the **ranking input to discovery** (a first-class wiki pillar —+see **wiki-discovery**). Scoring answers "how valued is this page?"; discovery+answers "can it be found at all?" Relevance should surface a page; scoring should+break ties among relevant results — a great new page shouldn't be invisible just+because it has zero stars yet.+ ## Status - **Stars: live.** `POST/DELETE /api/v1/pages/:slug/star` and
uninstall.sh+2−2@@ -4,7 +4,7 @@ DEST="$HOME/.claude/skills" for n in adom-wiki-skillpack \ wiki-anatomy wiki-api wiki-publish-safely wiki-readme wiki-visibility \ wiki-repo-styles wiki-family wiki-skillpack wiki-hero \- wiki-breadcrumbs wiki-forking wiki-scoring; do+ wiki-breadcrumbs wiki-forking wiki-discovery wiki-scoring; do rm -rf "$DEST/$n" done-echo "OK: Removed the Adom Wiki Skill Pack and its 12 bundled skills."+echo "OK: Removed the Adom Wiki Skill Pack and its 13 bundled skills."