scarf-miniapp-author

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": "1.0",
  "permissions": ["query:kanban.tasks"],
  "panelHint": { "preferredWidth": 480, "placement": "panel" },
  "generated": true
}

• Only id + name are required; entry defaults to index.html, permissions to [] (default-deny), minBridgeVersion to "1.0", generated to false.
• Set "generated": true for anything you author — it labels the app as agent-written in the cockpit and on the permission sheet. It no longer buys or costs permissions (sensitive ones are off for everyone), so claiming otherwise gains nothing; be honest.
• permissions must list every bridge surface the app uses (default-deny — an undeclared call is refused).
• Raise minBridgeVersion only for a surface you actually need — "1.1" for scarf.openURL. An older Scarf refuses the app outright rather than half-running it.