| name | leaf |
| description | Presents designs, decisions, findings, or live work as an HTML page the user can comment on and manipulate. Use for “explain this in HTML,” “write up the findings,” “show me the options,” or work whose progress or review belongs in a shared page. |
| allowed-tools | ["Bash(leaf:*)","Bash(jq:*)"] |
Present the session's subject as a live HTML page. The user comments on exact
passages, acts through the page's widgets, and follows revisions in place. With
no subject in $ARGUMENTS, use the work already under discussion.
Leaf's writing guidance supplies defaults only; any user-specific guidance on
tone, structure, depth, or format takes precedence.
$ARGUMENTS
Return to the user
After first handing over a browser page's URL, repeat that exact URL every time
you return to the user in chat, including interim updates, questions, and the
final handoff. An inline MCP App has no durable URL to invent; refer to the review
and its observed mode instead. If you open its browser page, the URL rule begins then.
Start here
Pages conventionally live at ~/.local/state/leaf/pages/<slug>/, though every
command takes the directory explicitly. A page holds mutable index.html,
immutable valid revisions, event-backed stamped version aliases, the event log,
service state, and its vendored layer. Export or copy anything that must outlive
that live state.
Resolve the directory containing this SKILL.md, then use its
../../bin/leaf launcher for every command shown as leaf. In Claude Code that
path is ${CLAUDE_SKILL_DIR}/../../bin/leaf, and Claude Code also puts it on
PATH. If the resolved file is absent, report that the plugin payload is
incomplete. A checkout keeps it at bin/leaf.
- Run
leaf page init <page>. Optional shapes need their packages named here:
diagram for Mermaid, diff for a unified diff, swipe for rapid
pass-or-keep triage, and playground for declarative interactive explorers, as in
leaf page init --package diagram --package diff <page>. Re-running page init
with the selection adds it to a page already written.
- Read
references/page-authoring.md, then the authoring reference each part of
the page needs (listed under "Author a version" below). Write
<page>/index.html using only the registry's vocabulary. A valid save becomes
the active immutable revision; an invalid save leaves the last valid revision
live and reports its diagnostic in page state and the browser.
- Match the handoff ceremony to the page's intended lifetime, regardless of
its shape or whether it asks a question:
- For a quick page that will be revised or dropped after an immediate
reaction, run
leaf version check <page> and fix every failure. Do not
stamp it or delay its first handoff for a browser review.
- For a finished record that work will rely on after the conversation, run
the pre-handover review in
references/page-authoring.md, including
leaf version check <page> --render, and fix every failure. Then stamp it
with leaf version stamp <page> --text "<changelog>" before its URL first
reaches the user.
- A page declaring
<meta name="lf-review" content="sign-off"> is a record,
whatever else it looks like: work will rely on the approval, and sign-off is
offered only on a stamped version. Give it the record's ceremony before its
URL first reaches the user.
- If a later stamp turns a quick page into a record, run that review before
the stamp.
- Read
references/conversation-loop.md and exactly one host contract:
references/host-claude-code.md or references/host-codex.md. Set the page's
status as the conversation reference defines, and hand over by the route the
host contract defines. Both hosts use the full browser page by default; retain
the exact keyed URL. Inline MCP Apps are an explicit experimental route with a
reduced fallback.
- Name the available gesture and finish the turn. Send the exact URL for a
browser handoff; for an MCP App, name the review and report the observed mode
or that rendering remains unverified.
When input arrives, read references/event-batches.md before processing it and
references/conversation-threads.md when a thread needs work; in Codex the
delivery arrives as a leaf-delivery element, which references/host-codex.md
owns. Read references/page-checkpoints.md before stamping or ending. Edit only
index.html; Leaf alone writes immutable revisions and public version mappings.
Page contract
Unless the user specifies the page's form or depth, a Leaf is a short sequence
of visually distinct, self-contained views. Each view makes one point, shows one
state, or offers one move, so the reader can grasp it at a glance and continue;
disclosures keep supporting detail available without putting it in that path. A
quick-answer page puts its first Ask in the initial viewport, with the short
shared premise and alternatives it needs. A record or system page may expose the
whole state and put each Ask where that state makes it answerable. The visible
page follows the subject's shape rather than a report outline;
references/page-authoring.md owns the concrete choices.
A page states what is true now, not how it got there. Correct a wrong figure in
place and drop a superseded claim rather than narrating its withdrawal; the
version stamp changelog and the event log carry the history. Save freely as
the subject changes and stamp meaningful checkpoints. Use status detail for
progress between revisions. Keep the waiter alive while work continues so
comments can affect the next step.
Improve Leaf through use
Leaf's agent interface is still in development, and experience making real
pages should inform it. When using Leaf exposes concrete friction, ambiguity,
or a missing capability, raise it with the user and offer to file an issue in
the Leaf repository. Agent-reported issues are welcome.
Describe the specific case: what you wanted to do and how the interface got in
the way. Then explain the general improvement and why it would make Leaf better
beyond that page.
Conditional references
Read references directly from this skill directory. Every route is listed here,
so a phase does not depend on discovering a chain of references.
Author a version
references/page-authoring.md: before writing or revising any version.references/authoring-asks.md: while authoring a new, unanswered ask or
sign-off.references/authoring-revisions.md: before changing a handed-over page,
proposing a rewrite, using a reader-owned draft, or revising standing state.references/authoring-evidence.md: before using measured facts, diagrams,
charts, source files, images, or before/after captures.
First handoff
references/conversation-loop.md: before a page handoff or working status.references/host-claude-code.md: before the first handoff in Claude Code or
recovery of its direct wait loop.references/host-codex.md: before the first handoff in Codex, and for the
delivery payload its later turns receive.
Continue after input
references/event-batches.md: after delivery and before processing its events.references/conversation-threads.md: before opening, replying to, editing, or
resolving a thread.references/page-checkpoints.md: before stamping or ending a page.
Serve or extend a page
references/serving-pages.md: for the first handoff, --export, an unreachable
URL, --host, a standing page, re-vendoring a served page, or resuming another
session's page.references/packages.md: for a package-design request or an event with
"about": "layer".
Change Leaf itself
references/internals/page-storage.md: when changing page files or storage
invariants.references/internals/session-lifetime.md: when changing work claims,
watchers, hooks, or server lifetime.references/internals/layer-registry.md: when changing composition or the
registry's custom vocabulary.references/internals/events.md: when changing events, undo, authorship, or
conversation semantics.references/internals/validation.md: when changing static or browser
validation, passages, or parsed source. These internal contracts are not for
ordinary page use.references/internals/mcp-app.md: when changing the MCP tools, app resource,
process-scoped page server, private result payload, or snapshot fallback.
Use a separate Codex watcher
references/codex-watcher.md: only after the user explicitly authorizes a
visible Codex watcher task. Follow it before handing over the page.
