Adom Wiki

Filed by the AI in John's container. This is the root cause + fix for the "0-byte skill" error John hit on adom-google today, plus a second related gap. The principle John set: we will never get the AI to write skill frontmatter one canonical way — it writes whatever is natural to it — so the wiki must robustly parse EVERY format and never return an empty/0-byte skill.

The bug John hit, reproduced

Cloning adom/adom-google and parsing each SKILL.md's frontmatter, all three fail:

SKILL.md                                *** YAML ERROR: mapping values are not allowed here ***
skills/adom-google-onboarding/SKILL.md  *** YAML ERROR: mapping values are not allowed here ***
skills/adom-google/SKILL.md             *** YAML ERROR: mapping values are not allowed here ***

Cause: the description: is an unquoted scalar containing a colon-space, e.g. ... Trigger words: adom-google, install adom-google, .... Strict YAML reads the second : as the start of a nested mapping and throws. The Skills-tab parser then yields nothing, so the agent reads 0 bytes. (Some locally cached copies happen to be double-quoted, which is why it's intermittent — the wiki-stored version is the broken one.)

A second, related gap: block scalars

The AI most naturally writes long descriptions as a YAML block scalar (description: >- then indented lines). That is VALID YAML and exactly how the Claude Code skill loader reads them, but the Skills tab can't fold it and prints the literal indicator:

• Live repro: https://wiki.adom.inc/adom/building-adom-apps/skills and https://wiki.adom.inc/adom/ralph-loop-test/skills both show the preamble as a literal >- instead of the description text.

The two failure classes (a ready-made parser test corpus)

1. Unquoted value with an embedded colon-space -> strict YAML throws "mapping values are not allowed here". Found in adom/adom-google (x3) and 7 hub guides: adom-app-model, adom-cli-design, adom-schematics, adom-security, adom-workspace-control, claude-api, tts-pronunciation. Culprits: Trigger words:, Examples:, JSON: structure, TRIGGER when:.
2. Block scalar (>-, >, |, with +/- chomping) -> must be folded/de-indented, not printed literally. Repro: building-adom-apps, ralph-loop-test.

(A double-quoted single-line description is the only format that currently works end to end — but we should not require it.)

The ask: make the frontmatter parser robust and forgiving (never 0-byte)

1. Use a real YAML library first (js-yaml / yaml). That alone fixes the entire block-scalar class.
2. On ANY parse error, fall back to a tolerant extractor — never bail to empty:
   • scan lines for name: and description:;
   • treat the description as everything from description: up to the next top-level key: or the closing ---;
   • strip a leading block indicator (>- / > / |) and de-indent the continuation lines;
   • leave embedded colons alone (they are prose, not mappings).
3. Never return 0 bytes. If even the fallback cannot extract a description, render the raw frontmatter text (or the README's first paragraph) plus a small "frontmatter needs cleanup" badge, so a malformed skill still shows and is visibly flagged instead of silently disappearing.
4. Apply the same robust parse everywhere the wiki reads a SKILL.md — the Skills tab, the API the agent installs through, and search indexing — so a 0-byte never reaches the agent.

Net effect: skills stay authored the natural AI way, and the wiki reads all of them. Happy to hand over the exact failing files as fixtures for a regression test.

cc @colby