skill

Building Adom Apps

Public Made by Adom

by adom

Build software the AI can drive. Hints are the breakthrough.

ai-agentdevelopercli-designapp-creationui-designhintsai-firstskillpack
Overview Files Skills Discover Packages Releases Dependencies Issues Breadcrumbs Pull Requests Activity
building-adom-apps / SKILL.md
Download

name: building-adom-apps description: >- How to build software the Adom (AI-first) way, so the apps, CLIs, and tools every Adom user writes are a joy for an AI agent to drive. The centerpiece is HINTS: every CLI returns OK:/ERROR: + Hint: lines (and a JSON {status,data,hints[]} envelope) so your tool teaches the agent what to do next at the exact moment it needs to know, more reliable than skills, memory, or system prompts, which get read once and compacted away. Read this BEFORE writing any Adom CLI, app, or tool. Routes to the four pillars: hints, CLI design, app creation, and UI design. Use when the user says: write a CLI, build an Adom app, create a tool or bridge, add a command, make an app for the wiki, ai-first code, return hints, hint lines, cli design, ui design, app creator, how should my tool talk to the AI.

Building Adom Apps (the AI-first way)

Adom apps are built to be driven by an AI agent, not just used by a human. That one constraint changes how you write everything: a CLI, a web app, a bridge, a service. The breakthrough that makes it work is hints.

The breakthrough: HINTS

The AI tends to never read skills properly, find them, or read all the way through them. Skills are read-once and get summarized away as the conversation compacts. So the most reliable way to make an AI behave the way your tool expects is to teach it from inside the tool's own output, at the moment of need.

Every Adom CLI prints:

  • a status line: OK: ... or ERROR: ...
  • one or more Hint: ... lines telling the agent exactly what to do next
  • for --json, a { "status", "data", "hints": [...] } envelope
$ adom-wiki pkg publish --org adom
ERROR: skill packages must include a SKILL.md at the package root.
Hint: Move your SKILL.md to the package root (or skills/<slug>/SKILL.md), then re-run.
Hint: Run `adom-wiki pkg lint` to see all blockers before publishing.

The agent reads that in the fresh tool output, in-context and unmissable, and fixes it next turn. No skill re-read required. Hints are read-at-the-moment-of-need; skills are read-once. It is the single most reliable steering channel you have, more than skills, memory, or the system prompt.

Full rationale, the channel-comparison table, and the relay case study live in the ai-hints-in-clis guide (in the adom skills hub) and relay-hint-pattern. This pack promotes them to the front door.

What to put in a hint (not just error fixes)

Hints are how your tool hands the agent everything it cannot be expected to remember. Emit a hint for:

  • What to do next - the literal next command, flag, or file.
  • How long this call takes / when it times out - e.g. Hint: this build runs ~90s and times out at 180s.
  • How to check on a long-running call - Hint: poll status with adom-desktop record_status {"id":"rec_8f2"}.
  • Pitfalls - the foot-gun the agent is about to hit, and how to avoid it.
  • Where to put files - Hint: write generated parts to ./adom_modules/<slug>/, not /tmp.
  • Async artifacts that arrive LATER - Hint: the screenshot will be dropped at ./shots/iter-3.png in ~2s; watch for it with a Monitor.
  • The SHAPE of what is coming back - Hint: screenshots[] includes child windows; an error dialog is usually a child of the parent hwnd.
  • Correct-pattern teaching - when the agent does it the wrong way, hint the right way: Hint: use adom-desktop screenshot instead of curling the relay directly.

If you ever wish the agent "would just know" something, that is a hint waiting to be written.

Rules for good hints

  1. Every ERROR: has at least one Hint:. Never leave the agent guessing.
  2. Hints are actionable commands, not explanations. Hint: start it with shotlog serve & beats "the server may be down."
  3. Name the exact command, flag, or file. Not "check the config" but Hint: set relay_port in ~/.config/adom/desktop.toml.
  4. Chain hints for multi-step recovery (create the page, THEN upload the asset).
  5. Warnings get hints too - OK: started on 8820. Hint: register it in PORT-REGISTRY.md.
  6. Hints can teach patterns, not just fix the immediate error.

Do not rely on it being read - ENFORCE it

The whole point is that docs (including this one) get skipped. So the pattern is enforced, not just taught:

  • adom-ui-linter checks CLI-02 (output starts OK:/ERROR:), CLI-03 (errors carry Hint:), CLI-04 (a health subcommand exists), CLI-05 (an install subcommand exists). Run adom-ui-linter lint . --category cli-compliance.
  • Make it a publish gate. Wire that check into adom-wiki pkg lint so a wiki app with no hints cannot ship, exactly how lint already blocks a missing SKILL.md, tags, or hero. The skillpack teaches; the gate guarantees. Then every third-party app in the wiki behaves this way and the whole ecosystem benefits.

The four pillars (route here when building)

Building... Read Covers
Any CLI the HINTS sections above + adom-cli-design OK:/ERROR: + JSON companion, --json for machines / pretty for humans, no-color-when-piped, exit codes, subcommand layout, health + install subcommands.
A web app app-creator A mini web server that renders its UI in a Hydrogen webview tab.
The UI adom-ui-design + adom-ui-linter The Adom UI design system + the deterministic UI/CLI/skill compliance linter.
Hints (always) the HINTS sections above + ai-hints-in-clis The breakthrough: your tool teaches the agent from its own output.

Bottom line: write the app so the agent never has to guess. Status-prefix every output, emit a Hint: on every error and every non-obvious next step, return a hints[] array in --json, and let the linter enforce it. That is what makes an Adom app a joy for an AI to drive.