Summer apps skill for AI agents

​

When your agent uses it

• The person asks for a tool for their team (“build us a loot balance tool”, “a board to track creatures”)
• The person needs a UI to decide, rate or edit something they will come back to
• Reading or changing the data of an existing Summer App
• Calling an app’s agent tools or waiting for what an app sends

​

Install

npx -y summer-engine@latest skills install summer-apps --agent claude-code

​

The skill

​

First: does Summer already do it?

​

When to build one

• The person asks for a tool (“build us a loot balance tool”, “track every creature from concept to in-engine”, “a board to review playtest clips”).
• They need a UI to decide or edit something they will come back to.
• Not for a one-off answer: reply in chat instead.
• Not when Summer already does it (above).

​

Layout or code

• Layout (format: "layout"): a JSON layout of kit nodes. Quick, throwaway, always on brand. Use it to ask the person to pick, rate or fill something now.
• Code (default): index.html + JS/CSS with the Summer SDK and UI kit. Use it for state, editing, shared data, generation or engine access.

​

Start from the working app

• minimal-app.md: a complete working app (manifest, index.html, app.js) built from kit components, using shared data, live changes, the viewer, page.declare, an agent event, an agent tool and frame-move state. Copy it and change it.
• sdk-reference.md: every SDK call with its exact arguments and return shape.
• manifest.md: every manifest field.
• The kit’s component catalog (every <summer-*> element with attributes, events and a copyable example) is apps.guide({ section: "kit" }), also at /summer-ui/v1/catalog.json on the app host. Copy its examples instead of inventing markup.

​

The loop

1. apps.guide({ section: "overview" }) first, then examples and the sections the app needs. Load the summer-apps-design skill for how it must look.
2. apps.create({ name, purpose, format }). The person’s Studio tab opens it.
3. Write the files in a local folder, then apps.publish({ appId, files, manifest, note }) with every file as { path, content, encoding } (index.html at the root; or layout for a layout app). Each publish is an immutable version the tab boots. A publish error names the file or rule: fix it and publish again.
4. Seed starter data with apps.write_data({ appId, ops, as: "seed" }) when the app should start full. Seed rows belong to the team and show no author.
5. Look at it: apps.screenshot({ appId }), then width: 390 (phone) and theme: "dark"; steps: [{click: "#edit"}] or [{press: "<action id>"}] shows a dialog or a second state. Fix the publish warnings too. Fix every error and console line it reports, publish again, look again. It is read-only: writes, sends and paid calls are refused there and work in Studio.
6. apps.events({ appId, after }) waits for what the app sends you (summer.agent.send), errors (uncaught and console.error) and feedback. Act on them; pass the cursor on.
7. Change the app by publishing again; apps.get({ appId }) returns the current files.

​

Data is the API

{ "appId": "<id>", "ops": [
  { "op": "patch", "collection": "items", "recordId": "bow", "patch": { "damage": 36 }, "ifRevision": 4 },
  { "op": "put", "collection": "notes", "recordId": "n-17", "data": { "text": "Boss too long", "status": "open" } },
  { "op": "remove", "collection": "notes", "recordId": "n-3" }
] }

​

Agent tools

​

Rules

• Declare only the permissions the app uses; declare every engineFiles path and every agentEvents name. A missing one fails at runtime with permission_missing.
• The app runs sandboxed (allow-scripts allow-forms allow-popups allow-modals allow-downloads, never allow-same-origin): no cookies, no localStorage, no network unless the workspace allows a domain. Keep state in summer.data.
• Paid SDK calls spend the credits of the person using the app. Say so before building an app that generates.
• Use real data (summer.data, summer.assets, summer.engine.readFile), never placeholder numbers.
• Studio moves an idle app to a fresh frame every few minutes. Keep UI state you care about in shared data, or return it from summer.app.onSnapshot(() => state) (up to 256 KB) and read it back from (await summer.ready).restored. Wrap Web Audio playback in summer.app.busy(true) / summer.app.busy(false) so a long sound is not cut; <audio> and <video> count on their own.
• Call summer.page.declare so agents can read and use the UI; mark delete, publish, pay and send actions critical.
• When the SDK cannot do what the app needs, say so and call apps.report_gap.
• apps.dock docks an app in the editor (it runs in the Summer MCP on this computer); on engines without app docks it returns engine_lacks_op: open the app in the Studio tab instead.
• Keep, archive, restore, rename and pin with apps.update (status, name, folder, pinned); copy one with apps.duplicate; add a starter app with apps.add_starter; send the makers a note with apps.feedback. apps.delete asks the person, and apps.rollback (an older version goes live) and apps.update_starter ask the app’s owner: each answers needs_approval with a link to give them, and nothing changes until they approve (jobs.wait on the job).

​

Done means

​

From a shell

​

Files in this skill

• manifest.md
• minimal-app.md
• sdk-reference.md

​

Related skills

• summer-apps-design: How a Summer App should look: layout, Summer UI kit components, tables, charts, states, pre-ship check.