Leaf

If the input is a named leaf_delivery tool output or a leaf-delivery element, first run leaf delivery claim <id>. A pointer then needs leaf delivery read <id>; the named tool output already carries the same envelope. The claim immediately marks the first delivered reader move that still needs work as Working; a stale delivery changes nothing. Then read references/event-batches.md, the current host contract, and, for reader messages, references/conversation-threads.md. Process every batch and every event. Each event's obligation.response, when present, names the Leaf operation it required when captured: a reply, a page revision closed with leaf resolve, or leaf receipt. Recheck current page or conversation state before writing because a later event may already have settled it. The current host contract names whether it binds a plain reply to the turn's normal final message; otherwise use the explicit Leaf command. Version and request responses use their explicit Leaf commands. Do not initialize or hand the page over again in response to an existing delivery.

Otherwise, 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.

When the host sets $LEAF, use that launcher for every command shown as leaf. Otherwise resolve the directory containing this SKILL.md and use its ../../bin/leaf launcher. 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 the launcher at bin/leaf.

1. 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, playground for declarative interactive explorers, visual-review for an ordered website run with aligned before-and-after evidence, and targeting for selecting and proposing changes to preview elements, as in leaf page init --package diagram --package diff <page>. Re-running page init with the selection adds it to a page already written. Bespoke explorer or simulator behavior stays in that page's module and does not require a task-specific package.
2. 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.
3. 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.
4. 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.
5. 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 conversation needs work. Every host delivers the same leaf-delivery-v1 envelope: direct waits and App Server carry it inline, while queued Codex carries its immutable id. 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, whether a scrolling document or a workspace; references/page-authoring.md owns the concrete choices.

The page contract and widget capabilities are choices, not a checklist. Include only controls and gestures whose results advance the reader's task.

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, a page-authored module, or an event with "about": "design".

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.