Claude Code

1---
2name: floom
3description: Build and deploy AI apps to Floom from Claude Code. Use when the user says "deploy to Floom", "publish this to Floom", "/floom-init", "/floom-deploy", or "/floom-status". Creates a floom.yaml manifest, publishes the app to floom.dev, and returns a live URL plus an MCP install snippet.
4---
5 
6# Floom Skill for Claude Code
7 
8Thin wrapper around the `floom` CLI. Three slash commands:
9 
10- `/floom-init` — scaffold a `floom.yaml` in the current directory
11- `/floom-deploy` — publish the current app, return live URL + MCP snippet
12- `/floom-status` — list the caller's published apps and recent runs
13 
14Docs: https://floom.dev/docs. Examples: https://github.com/floomhq/floom/tree/main/examples.
15 
16---
17 
18## One-time setup (auth)
19 
20The `floom` CLI resolves auth in this order:
21 
221. `FLOOM_API_KEY` env var (+ optional `FLOOM_API_URL`, default `https://floom.dev`)
232. `~/.floom/config.json` written by `floom auth`
243. Legacy `~/.claude/floom-skill-config.json` (backward-compatible)
25 
26Check on first run:
27 
28```bash
29floom auth --show 2>/dev/null || echo "NOT_CONFIGURED"
30```
31 
32If not configured, prompt the user for their API key:
33 
34```
35Get your Floom API key at https://floom.dev/me/api-keys, then run:
36 
37  floom auth <your-api-key>
38 
39Or for self-host:
40 
41  floom auth <your-api-key> http://localhost:3051
42```
43 
44Run `floom auth <key>` — the CLI writes `~/.floom/config.json` (chmod 600).
45 
46Verify with `floom status` (expects JSON or "No apps yet", not an auth error).
47 
48---
49 
50## `/floom-init` — scaffold a new app
51 
52Ask one question at a time:
53 
541. "What's the app called? (e.g. 'Lead Scorer')"
552. "One-sentence description?"
563. "Type? (a) wraps an existing OpenAPI service, or (b) custom Python code"
574. If `a`: "OpenAPI spec URL?"
585. If `b`: "Secrets needed? (comma-separated, e.g. GEMINI_API_KEY)"
59 
60Derive slug: lowercase, dashes only, matches `^[a-z0-9][a-z0-9-]{0,47}$`.
61 
62Then run:
63 
64```bash
65floom init
66```
67 
68The CLI prompts interactively. If a flag shortcut is needed, run with `--name`, `--description`, etc. (see `floom init --help`).
69 
70Stop after scaffolding. Do NOT deploy from `/floom-init`.
71 
72---
73 
74## `/floom-deploy` — publish to Floom
75 
76```bash
77floom deploy
78```
79 
80Or for a dry-run preview:
81 
82```bash
83floom deploy --dry-run
84```
85 
86On success the CLI prints:
87 
88```
89Published: <name>
90  App page:    https://floom.dev/p/<slug>
91  MCP URL:     https://floom.dev/mcp/app/<slug>
92  Owner view:  https://floom.dev/me/apps/<slug>
93 
94Add to Claude Desktop config:
95  {"mcpServers":{"floom-<slug>":{"command":"npx","args":["-y","mcp-remote","https://floom.dev/mcp/app/<slug>"]}}}
96```
97 
98On 409 `slug_taken`: show the response `suggestions` array, ask the user to pick one, update `floom.yaml`, retry.
99 
100**Python/Node (custom code):** no public publish HTTP API yet. The CLI will print:
101 
102```
103Custom Python/Node apps can't be published via HTTP yet. Options:
104  1. Open a PR against floomhq/floom with your dir under examples/<slug>/.
105  2. Wrap your code in a thin HTTP server, publish an OpenAPI spec, and re-run 'floom deploy'.
106```
107 
108---
109 
110## `/floom-status` — my apps + recent runs
111 
112```bash
113floom status
114```
115 
116Render two tables from the output: `slug / visibility / status / runs / last_run`, and `run_id / app / action / status / duration`. If empty:
117 
118```
119No apps yet. Run /floom-init to scaffold one.
120```
121 
122---
123 
124## Error handling
125 
126| HTTP | Code | What to say |
127|------|------|-------------|
128| 401 | auth_required | "Floom token isn't working. Run `floom auth --clear` then `floom auth <key>` to re-auth." |
129| 400 | invalid_body | Show `details` from response, point at the bad field. |
130| 400 | detect_failed | "Couldn't reach or parse <url>. Does `curl <url>` return valid JSON/YAML?" |
131| 409 | slug_taken | Show `suggestions`, ask user to pick, retry. |
132| 5xx | — | "Floom returned <code>. Retry in a minute or check https://floom.dev/status." |
133 
134Never retry on 4xx. 5xx may retry once with 2s backoff.
135 
136---
137 
138## Gaps flagged for launch
139 
1401. **No publish endpoint for custom runtimes.** `POST /api/hub/ingest` only accepts OpenAPI URLs; Python/Docker apps like `lead-scorer` get seeded from `examples/` on server boot. The skill routes users to open a PR.
1412. **No server-side dry-run.** Skill simulates dry-run client-side via `FLOOM_DRY_RUN=1`. A `?dry_run=1` on `/api/hub/ingest` would let users preview the parsed manifest.
142