skill

Adom Wiki

Public Made by Adom

by adom

How the Adom Wiki (wiki.adom.inc) works and how to drive it with the adom-wiki CLI: the two storage layers (git page repo vs package registry), hosting source by pushing files (not a tarball), making

wikiclipackagesregistrypublishingguide
Overview Files Skills Discover Packages Releases Dependencies Issues4 Breadcrumbs Pull Requests Activity
Closed general

Feature: a Discover tab on page nav (auto-discovery self-test) — snippet + live sample-prompt scoring, like the Skills tab

Colby Knox · 21d ago ·closed by Colby Knox

The ask

Add a top-level Discover tab to the page nav, same treatment as the Skills tab, that reveals a repo's auto-discovery setup AND self-tests it live when the page loads.

Auto-discovery is one of the wiki's most novel, AI-first bets (GitHub and everyone else lack it), and it works remarkably well, but right now it is a black box to both authors and AIs: you can't see what your discovery snippet is, you can't see whether the wiki's discovery search actually returns your repo for a real user phrasing, and you have to fight your AI to get it to reveal the competing results. The Skills tab turned "is my repo structured right?" from a mystery into a litmus test (it already caught a repo that had only sub-skills and no main skill that routes to them). The Discover tab should do the same for discoverability.

What the Discover tab shows (for the page's repo)

(1) The snippet (parsed from page.json):

  • discovery_triggers: the short everyday-phrasing triggers ("remote into my machine", "watch the install"), not just the product name.
  • discovery_pitch: the one-line "when to use this" snippet.
  • tags
  • sample_prompts
  • metadata.activate: the activate recipe (kind, skill, bridgeManifestUrl, postInstall, requires, verbPrefixes).

(2) The self-test (the "score"): on page load, run each sample_prompt against the wiki's own discovery search (discover find) and show, per prompt:

  • this repo's RANK in the results ("#1 of 3"). The score is simply: does your sample prompt return your own repo at the top of the discovery search the wiki runs?
  • the OTHER results that matched (the competing repos). Today the AI hides these and the author has to fight to see them. The tab reveals them in a clean, legible way.
  • a result badge that pops in as each prompt resolves (live, self-running against itself).

Concrete example (adom/adom-desktop-rustdesk-bridge, v0.1.3): "can you connect to my office PC over rustdesk" returns it #1 of 3; "I need to see the screen of my windows home laptop remotely" also returns it #1 of 3, even though that phrasing never names the product, which is the everyday-phrasing triggers earning their keep. Seeing the rank plus the two other matches is exactly the legibility that is missing today.

Sub-tabs (to keep the tab row from sprawling)

Both of us are wary of too many top-level tabs. Two-part fix:

  • A caret / pulldown that tucks the less-central tabs (candidates: Skills, Discover, Pull Requests, Activity) under a submenu so the top row stays clean.
  • Sub-tabs inside Discover: Snippet and Sample Prompts (the static snippet fields vs the live-scored prompts).

Open question this tab would settle: is discovery metadata REQUIRED at publish?

It is genuinely unclear to us whether the publish path requires (and reprimands the AI for omitting) discovery_triggers + discovery_pitch + sample_prompts. Auto-discover working so consistently suggests it might be enforced, but we cannot tell from the outside. The Discover tab would make presence/absence visible per repo, and the answer should be documented. If it is NOT required today, consider requiring it via the publish lint (this ties into the #43 quality-gate spec).

A concrete optimization this surfaced (Gap-A)

discover find returns discovery_triggers / discovery_pitch / tags but NOT metadata.activate. So an AI that discovers a repo must do a SECOND fetch of .../files/page.json just to read the activate recipe before it can install/activate. Returning activate inline in the find result would remove that round-trip (and the Discover tab consumes the same data, so it helps both).

  • Skills tab: User / Dev / Publish sub-tabs + a "how to structure skills" help. The now-standard app skill layout is three kinds: user skills (shipped in the pkg tarball, installed for everyone), dev skills (how to build/debug/test the app, source-only), and publish skills (the app-to-wiki glue, source-only). Authors currently have to remember to exclude dev/publish from the tarball every publish. The Skills tab should split into those three groups and carry a "?" tooltip that teaches how to structure a repo's skills well (including that a main skill must route to sub-skills).
  • Periodic registry-wide skill-frontmatter scan. A live incident: ~16 skills in a container had unparseable YAML frontmatter; adom-google's skill loaded as 0 bytes, so the AI found the skill, read it, and reported it could not read the user's emails. The render parser was hardened (the Skills tab / install / search now fold block scalars and never 0-byte, see #42), but a proactive sweep that scans every repo's SKILL.md frontmatter and reports parse problems would catch authoring errors before they bite a user. Ties to #42 / #43.

Filed from a Colby + John thread while litmus-testing a new adom-desktop RustDesk bridge against auto-discovery.

3 Replies

Colby Knox · 21d ago

v1 shipped + live on prod: the Discover tab renders the snippet (discovery_triggers, discovery_pitch, tags, sample_prompts as {label, prompt}, and the metadata.activate recipe) and self-tests it, running each sample prompt + your combined triggers against the live discovery search and showing this repo's rank (e.g. adom/adom-desktop-rustdesk-bridge ranks #1 of 107) plus the competing results with scores. Still open here: the caret/pulldown to tuck Skills/Discover/PRs/Activity, the Snippet|Sample Prompts sub-tabs, returning metadata.activate inline in discover find (Gap-A), and the related Skills User/Dev/Publish sub-tabs + periodic skill-frontmatter scan.

Colby Knox · 20d ago

Progress: the two biggest pieces have landed.

Discover tab is live (///discover): it shows the snippet (discovery_triggers, discovery_pitch, tags, sample_prompts, metadata.activate) and self-tests each sample_prompt against the live discovery search, showing this repo's rank (#1 of 3 style) and the competing results. It appears only when the page ships triggers. (Also fixed along the way: {label, prompt} sample_prompts render correctly, not [object Object].)

The open question is settled: discovery metadata is now REQUIRED at publish for apps and skills (server gate, default-on; details in #43). So presence is enforced, not just made visible.

Still open, tracked here:

  • The caret/pulldown to tuck the less-central tabs (the row is up to ~10 entries now) and the Discover sub-tabs (Snippet | Sample Prompts). Doing this next.
  • Skills tab User / Dev / Publish sub-tabs plus the "how to structure skills" help.
  • Periodic registry-wide SKILL.md frontmatter scan.
  • Gap-A: return metadata.activate inline in discover find to remove the second page.json fetch.

Leaving open until the caret + sub-tabs land.

Colby Knox · 13d ago

The core ask -- a Discover tab that reveals the snippet AND self-tests it live -- is shipped. Mapping each ask to status:

DONE:

  • Discover tab in the page nav (shown when the repo has discovery_triggers).
  • Snippet: discovery_triggers, discovery_pitch, tags, sample_prompts, and metadata.activate (read live from page.json).
  • Live self-test / score: every sample_prompt runs against the wiki's discovery search on page load, showing THIS repo's rank as a "#N of M" badge (green #1, amber top-3, "not in results"), plus the competing results dimmed with their scores and "this repo" highlighted -- exactly the legibility that was missing. renderDiscover in server.js.
  • The open question is settled: discovery metadata IS required at publish now (discovery_triggers + discovery_pitch + sample_prompts, with an ADOMPKG_REQUIRE_DISCOVERY=0 emergency valve), and the tab makes presence/absence visible per repo.
  • Related: the Skills tab now has User / Dev / Publish sub-tabs.

Carved out (one concrete open server task) -> #101 (Gap-A):

  • discover find / /api/discover still omit metadata.activate inline, so a discovering AI does a second page.json fetch for the activate recipe. Non-trivial (activate lives in page.json, not the indexed row), so it gets its own focused issue with the recommended fix (index it into a column).

Not done (minor UI, low priority): Discover-internal Snippet/Sample-Prompts sub-tabs (currently one page) and a tab-row caret/pulldown to tuck less-central tabs. The periodic registry-wide frontmatter scan is a separate concern -- #42 already hardened the parser so a bad frontmatter never renders 0 bytes.

Closing the headline ask; Gap-A tracked in #101.

Log in to reply.