A3L is a compact AI-first language and installable Agent Skill for turning substantial structured results into scannable, slide-like single-file HTML reports. Agents author a tiny non-JSON A3L source instead of verbose HTML/CSS/JS, compile it deterministically, and hand off the artifact with a short text fallback.
One command installs the self-contained a3l skill and lets you choose a supported agent and installation scope:
npx skills add agent-dance/A3L --skill a3lRequires a supported Node.js 22 or newer release.
Non-interactive global installs:
# Codex
npx skills add agent-dance/A3L --skill a3l --global --agent codex --yes
# Claude Code
npx skills add agent-dance/A3L --skill a3l --global --agent claude-code --yesStart a new agent session after installation. The skill should trigger for substantial status reports, reviews, plans, comparisons, flows, dashboards, release notes, risks, decisions, and retrospectives. You can also ask explicitly: Use A3L to present this as a slide-like summary. Tiny answers, code, raw command output, error traces, and explicit Markdown requests stay in text.
The success handoff is one HTML link plus a concise text fallback; it is not a second full Markdown report:
View: dist/present/<topic>.html
<short fallback summary>
See One Minute Install for platform-specific commands and the source-checkout fallback.
A3L has three different token measurements. Keep them separate:
- A3L → HTML expansion measures how much rendered HTML one compact A3L source produces. The checked-in
o200k_basecorpus currently reports460.45xsource-to-HTML expansion. This proves compact authoring and deterministic renderer reuse; it is not a Markdown-saving claim. - Semantic format A/B compares an equivalent Markdown report with the A3L source plus its short artifact handoff. The checked-in 12-scenario corpus preserves every fact and reports P50 output savings of
24.02%for short,30.79%for medium, and34.19%for long reports. Generated HTML is excluded. This is deterministic format evidence, not a live-Agent result. - Live Agent A/B verifies whether an actual Agent triggers the skill, creates the artifact, preserves facts, avoids false positives, and reduces the complete task output versus its own Markdown baseline. Cross-Agent results must pass the release gate before A3L claims universal Agent savings.
Input context is also real cost. The checked-in format benchmark counts the current SKILL.md at 858 input tokens: on the medium/long corpus its amortized savings breaks even after 9 reports sharing that context and reaches 30% after 116. See reports/agent-token-ab.md for assumptions and scenario-level results.
Reproduce expansion with npm run bench:tokens, deterministic Markdown A/B with node scripts/agent-token-ab.js, and live Claude behavior with npm run claude:eval.
Two production showcase pages are built with A3L itself and live in dist/. Click any thumbnail for the full interactive page rendered live in your browser (no install needed).
A3 内置能力展览馆 50 capsules · 点卡片即弹出实时预览 + 原始 A3L 源码对比 Live preview ↗ · Full screenshot · Raw HTML |
A3 价值与生产级证据 Token 压缩、三层数据、覆盖矩阵、验证体系，全部来自可重复脚本 Live preview ↗ · Full screenshot · Raw HTML |
Both pages are self-contained single HTML artifacts produced by npm run build:showcase; the live-preview links above route through htmlpreview.github.io so anyone can open them directly from GitHub without cloning.
A3L means Agent Abstract Assembly Language:
- Agent: designed for AI agents first, not human hand-authoring first.
- Abstract: expresses UI/development intent above raw HTML/CSS/JS.
- Assembly: keeps the source terse, compact, and compiler-oriented.
- Language: defines an independent DSL with a deterministic compiler boundary.
A2UI's useful lesson is architectural: keep structure, state, and actions declarative. A3L keeps that separation but uses terse glyph forms because JSON spends too many tokens on keys, quotes, commas, and braces.
Production A3L starts with capsules: high-level intent opcodes that compile into full HTML/CSS/JS.
!counter#app"Counter"
Run the exact source-to-generated-HTML expansion benchmark:
npm run bench:tokensCurrent o200k_base results exceed the 20x expansion target on every production capsule case; see reports/token-report.md. This benchmark does not compare A3L with an equivalent Markdown answer.
A3L now uses a three-layer expansion model:
- Lower syntax for exact one-off HTML/CSS/state/event work.
- Middle components for 26 self-contained reusable modules that can be nested inside custom layouts.
- Upper capsules for full-page/page-flow intents, now composed from middle components plus small lower-layer glue.
See docs/ARCHITECTURE.md for the extension model, docs/COMPONENT_CATALOG.md for the full built-in surface, docs/DESIGN_SYSTEM_RESEARCH.md for the design-system rationale, and reports/layer-report.md for measured layer ratios.
Lower-layer A3L is still available when the AI needs exact markup, styles, state, and events:
=t"Counter"
main#app.app(h1"A3L Counter" p#read($n) button#inc.btn"+")
.app{w:360;mx:a;mt:18vh;p:28;ta:c;bg:#fff;br:16}
.btn{p:10/18;bd:0;br:999;bg:#111827;c:#fff;cur:p}
$n=0
#inc@click{n++;#read.txt=n}
Compile it:
npm test
node bin/a3c.js examples/capsule-counter.a3 -o dist/counterDefault generated file:
index.html
a3c prints exact source-to-generated-HTML token stats after every compile. Treat this as an expansion/reuse metric, not as a Markdown A/B saving. If a three-file bundle is explicitly needed, use:
node bin/a3c.js examples/capsule-counter.a3 --bundle -o dist/counter-bundle!counter#app"Counter": production capsule.=t"Title": metadata.main#id.class(...): HTML tree..class{p:24;br:8}: CSS with aliases.$n=0: state.#btn@click{n++;#out.txt=n}: event action list.
See docs/SPEC.md for the formal MVP grammar and alias table.
See docs/AI_AUTHORING_GUIDE.md for the short prompt surface that was used in Codex AI smoke tests.
npm test
npm run bench:coverage
npm run bench:layers
npm run agent:smoke
npm run ai:smokenpm run ai:smoke invokes local codex exec, asks it to author A3L from short requirements, compiles the result, and verifies the output. Latest results are stored in reports/ai-smoke.md.
For the full production gate:
A3L_CODEX_BIN=/path/to/codex \
A3L_EVAL_JUDGE=codex-default \
A3L_EVAL_JUDGE_COMMAND=scripts/codex-judge-provider.js \
npm run verify:prodThe production gate deliberately fails closed when no real judge is configured. A source checkout includes adapters for Codex and Claude Code; any executable that implements the documented JSON stdin/stdout contract may be used instead. Run npm run skill:eval:prod:codex or npm run skill:eval:prod:claude to execute only one provider-judged Skill gate. The Claude variant is intentionally suited to slower manual or scheduled verification.
The compiler uses the mature Node.js runtime and node:test. The only dev dependency is @dqbd/tiktoken, used for real OpenAI-compatible tokenizer measurement with o200k_base.
The standard skill entrypoint is skills/a3l/SKILL.md; its compiler runtime is bundled inside the same directory, so a cold skill installation does not depend on the target workspace containing this repository's bin/, src/, or node_modules/.
Prefer the one-command Skill installation above. The snippets under agent-adapter/ are manual alternatives for a source checkout or an agent without Skill discovery. The decision contract is the same everywhere: use A3L for substantial, structured, slide-like reporting; preserve exact evidence; and fall back to concise Markdown if no suitable capsule/compiler is available or compilation fails.
Smooth local viewing:
npm run serve:present
# open http://127.0.0.1:41731/present/<topic>.htmlManual smoke test:
echo '!status#app"Adapter Ready"[state=Ready ok=1 warn=0 fail=0 next="Use A3L for structured summaries"]' | node bin/a3present.js -Public A2UI docs describe a JSONL/JSON-oriented protocol with component catalogs and a separation between UI structure and state. A3L takes the separation principle, then replaces JSON with compact source forms and a target-neutral IR so future emitters can target shell commands or other development languages.
References: