scarf-miniapp-author

Author a Scarf mini-app — a small sandboxed web surface (HTML/CSS/JS) that renders inside a project's cockpit and talks to the bound Hermes session + project data through the versioned window.scarf bridge. Use to build a bespoke panel (a task board, an approval queue, a chart, a data table) for a project.

Jump to install

Repository: awizemann/scarf
Last source activity: June 21, 2026 at 07:13
Detected SKILL.md language: English
Stars: 831
Forks: 52

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

name	scarf-miniapp-author
description	Author a Scarf mini-app — a small sandboxed web surface (HTML/CSS/JS) that renders inside a project's cockpit and talks to the bound Hermes session + project data through the versioned window.scarf bridge. Use to build a bespoke panel (a task board, an approval queue, a chart, a data table) for a project.
version	1.0.0
author	Alan Wizemann
license	MIT
platforms	["macos"]
metadata	{"hermes":{"tags":["Scarf","mini-app","webview","bridge","cockpit","authoring"],"homepage":"https://github.com/awizemann/scarf/wiki/Mini-Apps"}}
prerequisites	{"commands":["hermes"]}

Scarf Mini-App Author

Build a mini-app: a small web surface (HTML/CSS/JS) that Scarf renders inside a project's cockpit (the "Mini-apps" panel) over a narrow, versioned JS bridge (window.scarf). A mini-app is a project facet — it lives in the project directory and is bound to the project (and, for scarf.prompt, a dedicated Hermes agent session). Because it's plain web + a tiny API, you can author one reliably with your file tools.

When to invoke this skill

"Build me a mini-app that …" / "Add a little app to this project for …"
"Make a panel that shows / lets me …" (a task list, an approval queue, a status board, a chart, a form).
During a project upgrade (the scarf-template-author upgrade flow), to add a starter mini-app or two.

Do not invoke for: editing the project's dashboard.json (that's the Dashboard panel — use widgets), or pure reference questions (answer inline from below).

Where a mini-app lives

<project>/.scarf/miniapps/<id>/
├── miniapp.json     # manifest (REQUIRED)
├── index.html       # entry document (REQUIRED; default entry name)
└── …                # any local CSS/JS/images, referenced by RELATIVE path

<id> is the directory name and is canonical — it must equal miniapp.json.id. Use a short kebab-case slug (e.g. task-board).
Scarf discovers the mini-app automatically once the dir + miniapp.json exist; no registration step.

The manifest — `miniapp.json`

{
  "id": "task-board",
  "name": "Task Board",
  "version": "1.0.0",
  "entry": "index.html",
  "minBridgeVersion"

Call	Permission needed	Sensitive?†	Returns
`scarf.version`	—	—	`"1.0"` (string)
`scarf.context`	—	—	frozen `{ projectId, projectName, projectRoot, serverId, miniAppId, generated, bridgeVersion }`
`scarf.ui.toast(msg)`	—	—	shows a host toast
`scarf.ui.setTitle(title)`	—	—	sets the panel title
`scarf.ui.resize(w, h)`	—	—	layout hint
`scarf.ui.requestClose()`	—	—	asks the host to close the app
`scarf.store.get(key)` / `scarf.store.set(key, value)`	`store`	no	per-(project, mini-app) persisted KV (JSON values); `get` → value or `null`, `set` → `true`
`scarf.query(kind)`	`query:<kind>`	no	rows for `kind` as a JSON array. Implemented: `"kanban.tasks"`; any other kind replies `not_implemented`. (A 2nd `params` argument is accepted but reserved — ignored in v1.)
`scarf.kanban.read()`	`query:kanban.tasks`	no	array of the project's Kanban tasks (tenant-scoped); `[]` if none
`scarf.file.read(path)`	`file:read`	no	UTF-8 contents of a project file (path is relative to the project root, read-only, ≤4 MB, contained — no escaping the project)
`scarf.prompt(text, opts?)`	`prompt`	yes	sends a prompt to the project's bound agent session → resolves to the agent's final text (string); stream incremental output via `scarf.onEvent`
`scarf.onEvent(cb)`	`events`	no	`cb(ev)` fires for streamed agent events (message chunks, tool calls, completion) — pair with `prompt`

{ "id": "task-board", "name": "Task Board", "version": "1.0.0",
  "entry": "index.html", "minBridgeVersion": "1.0",
  "permissions": ["query:kanban.tasks"], "generated": true }

<!doctype html>
<html><head><meta charset="utf-8" />
<style>
  body { font: 13px -apple-system, sans-serif; margin: 0; padding: 12px; color: #1d1d1f; }
  h1 { font-size: 15px; margin: 0 0 10px; }
  .task { padding: 8px 10px; border: 1px solid #e3e3e6; border-radius: 8px; margin-bottom: 6px; }
  .status { font-size: 11px; color: #6e6e73; }
  .empty { color: #6e6e73; }
</style></head>
<body>
  <h1 id="title">Tasks</h1>
  <div id="list"><p class="empty">Loading…</p></div>
  <script>
    (async function () {
      document.getElementById("title").textContent = scarf.context.projectName + " — Tasks";
      scarf.ui.setTitle("Task Board");
      const list = document.getElementById("list");
      try {
        const tasks = await scarf.kanban.read();           // [] if none
        if (!tasks.length) { list.innerHTML = '<p class="empty">No tasks yet.</p>'; return; }
        list.innerHTML = "";
        for (const t of tasks) {
          const el = document.createElement("div");
          el.className = "task";
          // textContent (not innerHTML) for task data — titles can come from
          // other users sharing the tenant; never render them as HTML.
          const title = document.createElement("div");
          title.textContent = t.title || "(untitled)";
           status = .();
          status. = ;
          status. = t. || ;
          el.(title, status);
          list.(el);
        }
      }  (e) {
        list. = ;
      }
    })();
  </script>
</body></html>