by John Lauer

How to use the Adom Wiki without breaking pages — the wiki is six tools in one (git, adompkg, 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 Requests Activity

Download

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:

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.
Index triggers at publish time so a page is discoverable the instant it's published, with no engagement required.
Persist page.json metadata.discovery_triggers (today it's dropped) — or document the manifest as the single source of truth and say so.
Relevance + quality blend in ranking, not quality alone: a highly-relevant new page should outrank a barely-relevant popular one.
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.
Unify the two layers: expose the same trigger corpus so local skill discovery and registry discovery agree on what a page is "about."
Synonym / fuzzy matching so near-miss phrasings still hit.
Per-type discovery (skill vs app vs component vs bootstrap) and per-type ranking.
Trigger conflict/dedup signal: warn when two pages claim the same trigger, and support disambiguation/negative triggers.
Exclude deprecated/soft-deleted/private pages from public discovery.
Fix the FTS hyphen bug in /search (most Adom slugs contain hyphens).
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.

---
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.

Adom Wiki Skill Pack