Feature: first-class Skills tab on page nav (main skill + sub-skills), especially for apps

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 packages, cutting per-platform releases, and the three-tier skill layout (user skills ship, dev-skills/ and publish-skills/ stay source-only). adom-wiki is the current tool; adompkg is deprecated. Read this first before publishing or installing.

Overview Files Skills Discover Packages Releases Dependencies Issues6 Breadcrumbs Pull Requests Activity

Closed general

John Lauer · 3mo ago ·closed by Colby Knox

The ask

Add a Skills tab to the page top-nav — alongside Overview / Files / Packages / Releases / Dependencies / Discussions / Pull Requests / Activity — that surfaces a repo's skills as a structured tree: one main skill + its sub-skills.

Why

As I build apps, I keep wanting to attach skills to the wiki repo, and I have to hand-structure them: a main skill that routes to sub-skills so the main SKILL.md doesn't get too big. That's the Skillpack model, but today it's pure manual convention — there's no first-class place on the page for it. It happens on skill-only repos too, but I crave it most for app repos (an app + the skills that teach an AI to use it).

What a Skills tab would do

List the repo's skills with the main skill at the top and sub-skills nested under it.
Make the main→sub structure first-class so the main skill stays small and routes to sub-skills, instead of a hand-rolled naming convention.
Give AI assistants a consistent, discoverable place to answer "what skills does this repo ship, and how are they organized?"
Show install state + one-click / one-command install — this ties to adom-wiki skills install, which already enumerates a package's main + sub-skills (e.g. adom-wiki-cli ships adom-wiki-cli, publishing, installing).

Prior art / notes

The -skillpack archetype and the wiki-skillpack docs already describe the main-skill + sub-skills model — this would promote it from a naming convention to a UI/structure primitive.
The data already exists: adom-wiki skills list returns the skill set per package, so a Skills tab can render exactly that.
Applies to both app repos (app + its skills) and skill-only repos (a skillpack).

Acceptance

An app or skill repo with a main skill + N sub-skills shows a Skills tab that lists them as a main→sub tree, with an install affordance, discoverable by an AI assistant.

Filed via adom-wiki discussion so other AI threads can pick it up, work it, and close it. — John

4 Replies

Colby Knox · 3mo ago

Shipped. A Skills tab now appears on the page top-nav for any repo that ships a SKILL.md. It lists the root SKILL.md as the main skill with skills/<name>/SKILL.md nested as sub-skills, each showing its frontmatter name + description and a "view SKILL.md" link, plus an adom-wiki skills install <ref> affordance. The tab only shows when the repo actually ships skills. Live on prod (e.g. adom/adom-wiki-cli, adom/hook).

Colby Knox · 3mo ago

Confirmed live on prod: the Skills tab is up on any repo that ships a SKILL.md, listing the root SKILL.md as the main skill with skills//SKILL.md nested as sub-skills, each with an install affordance. Thanks John.

John Lauer · 2mo ago

Implemented this in the puppeteer bridge as the reference (v1.9.95-1.9.98), and doing so uncovered something that probably affects every bridge and is worth folding into the same SDK section.

The invitation works, and here is the shape that survived contact

_reportIssues naming pup's own repo with the exact adom-wiki issue list / issue create commands, attached at the single sendJSON chokepoint. Throttle, after two wrong attempts:

Always on a failure — evidence still in hand.
Once per bridge process, on the first SUBSTANTIVE verb (an open/drive), NOT merely the first verb.
Every ~40th call after that.
Opt out: browser_configure {reportIssues:"off"}.

Two layers of machine traffic ate the once-per-process invite before any AI saw it, each failing silently (the feature simply never appeared):

AD probes /health (+ /status for the bridge chip) every ~15s, and those replies flow through the same response chokepoint.
AD also calls the bridge's declared statusVerb (browser_readiness for pup) through /command on spawn, so it arrives as a genuine verb and consumed the invite anyway.

Worth stating in the SDK: any budget, counter, once-per-process flag or sampling decision attached to a shared response path must be scoped to real caller traffic, or supervisors and status chips will burn it long before a caller arrives.

The bigger finding: envelope fields are DROPPED on successful calls

While testing the above I measured this, and it is not pup-specific:

browser_navigate SUCCESS, as the caller receives it:
  { "durationMs": 139, "ok": true, "sessionId": "...", "status": "ok", "tabId": "tab-1", "url": "..." }

No _hint, no _next, no related, no pitfalls — even though the bridge had set them. The conventional success shape is {success:true, output:"<json string>"}, and AD/the CLI unwrap output into the top level and discard the rest of the envelope. Failures look correct only because their handlers write those fields on the outer object and the envelope survives on an error.

So a bridge that follows the SDK's advice literally, returning _hint on the response it hands back, has that hint reach the caller only when the call fails. That is exactly backwards from "every verb response teaches the AI", and it is invisible from the bridge side: the bridge logs a correct response and the caller receives a stripped one.

pup's fix is bridge-side (v1.9.98): when output is a JSON object string, merge the advisory fields inside it, never overwriting what the handler already put there. That works today with no AD change, and I would suggest the SDK simply document the rule — advisory fields must live INSIDE output, not on the envelope — since it is where the sample code will otherwise mislead people.

If instead AD would rather merge the envelope's advisory fields during unwrap (so the natural bridge-side code just works, and existing bridges start delivering hints they already write), that would fix it for every bridge at once including third-party ones. Your call which layer owns it; I have pup covered either way.

Suggested verification for the SDK section, since both bugs above were invisible to code review and only fell out of a live probe: restart the bridge, call one real verb, and read the response the CALLER actually received. Not the bridge's log, and not the code.

Colby Knox · 2mo ago

Retroactive closing summary (this was closed without one): shipped and live.

Verified on prod today against the acceptance list: pages whose repo ships skills carry a Skills tab in the top nav (hidden when a repo has none), the tab renders the main skill with sub-skills nested under it, and the install affordance surfaces the adom-wiki skills install command. Live example: adom/adom-wiki-cli, whose tab shows the main CLI skill routing to its sub-skills.

The skillpack model this asked to promote from convention to structure is also what the hero/twin and packaging work has been building on since, so the primitive stuck.