ambleloftDeveloper guide: editor and collection templates
Register templates for defined business data so the agent can present an editor or collection in chat. This page is for skill and extension developers. Built-in follow-up forms do not require these steps.
Outcome: Register an editor or collection template and verify selection, submission and instance updates.
Before you begin: Prepare the files and tools specified on this page. The previous page in the learning path is not automatically a dependency.
On this page
01Prepare a business template
This example uses the optional locale-demo development sample to demonstrate a collection template. A skill or extension with its own registered template can use that template directly. The model discovers its actual key with ui_list and checks capabilities with ui_capabilities.
Optional: create the sample template02Validate the template
Run in locale-demo. Validation does not prove host rendering or business execution. This template uses collection; the host also supports editor.
npx --no-install amble-extension validate-ui skills/expense/templates/requests.json03Present data in the active chat
Ask the agent to call ui_list for the actual template key. Then call ui_present with the arguments below, replacing key with that value. The result is a complete flow including id, revision, data, status and additional fields; do not reduce it to id/revision.
{
"key": "REPLACE_WITH_UI_LIST_KEY",
"data": {
"rows": [
{
"id": "request-1",
"subject": "Review handoff notes",
"description": "Demo data",
"status": "open",
"owner": "Project team",
"notes": "Awaiting user selection"
}
],
"state": "ready"
}
}04Visible result and updates
The user should see collection cards. Chat delivery occurs only after a user action. Call ui_read_submission with the actual submissionId and inspect instanceId, input, data and rowKeys. ui_update takes the original id, expectedRevision and new data, returning a new ID; the old instance becomes superseded and read-only. data.state is display state; businessStatus=false means it does not track per-row business outcomes.
05Request managed repairs from a review
An ordinary skill such as ai-rules can opt a chat action into managedRepair: true. Check ui_capabilities.managedRepair === 1, then provide actual report, rule and source-file SHA-256 hashes in data.baseline when presenting or updating the UI. Use scope: enumerated-files. The host binds the owning chat and local project, rechecks before dispatch and serializes participating repairs in that project. Only listed files are covered. External editors, shells and ordinary model tasks are not locked; remote managed repairs are unsupported.
| Displayed state | Meaning |
|---|---|
| Waiting to execute | Waiting for the project lease, an idle chat or explicit user continuation. |
| Turn ended · Review needed | The model turn ended. Inspect changes, run checks and produce a new review before claiming success. |
| Re-review required | Execution is uncertain or interrupted. Old requests are not replayed automatically; a fresh report links baseline.reviewOf to the previous submissionId. |
06Recovery and next steps
On a revision conflict, stop updating and review the latest successful full flow receipt with the user. Model tools have no ui_get for arbitrary current instances. If the valid id/revision is unknown, use ui_list to select the template again and ui_present after user review. Do not guess revisions or overwrite automatically. Stop using old submissions when the source or chat becomes invalid. forms/UI errors use MCP text/isError, with TOOL_ERROR when code is absent; do not add operation Result fields. Missing tools mean unavailable support. Use follow-up input to persist requests for missing details.
Explore persistent follow-up inputCheck the result and troubleshoot
Register an editor or collection template and verify selection, submission and instance updates.
Check actual results using this page’s verification steps. For business integrations, inspect UI submission, tool receipts and server records separately.
Open the error reference →