Flow Team

Flow Team API Skill

Drive the Flow work-collaboration platform through its Open API. This skill teaches an agent to read workspace state (projects, tasks, calendar, team, alarms) and act on it (create tasks/posts/schedules/todos/events, update task status & dates, manage the calendar) — and to propose next steps proactively.

Setup (once)

1. The user issues an API key from Flow's 키관리 (Key Management) page.
2. Put it in one place only: copy the repo-root .env.example to .env and fill it:

   FLOW_API_KEY=the-users-key
   

   .env is gitignored — the key is never committed, printed, or shared. If FLOW_API_KEY isn't set and no .env exists, ask the user to fill .env rather than guessing or requesting the key in chat.
3. All requests go to https://api.flow.team with two headers:

   Content-Type: application/json
   x-flow-api-key: <from FLOW_API_KEY>
   

A ready-to-use client lives in scripts/flow.mjs (Node 18+, zero dependencies). It auto-loads the repo-root .env. Run node scripts/flow.mjs me to verify the key works.

Where this runs (cross-platform — read before running scripts)

The user clones this repo and asks you to act, so detect the environment first and pick the right path. Don't assume macOS or a Unix shell.

• All .mjs scripts are pure Node (node:path, node:os, global fetch) — they run identically on Windows, macOS, Linux as long as Node 18+ is present. Always invoke them as node <script>, never via a shell-specific wrapper.
• npm run check is Node-based (check.mjs), so it's portable too — don't reintroduce shell for/&& loops.
• Scheduling is OS-specific, and schedule-setup.mjs already branches for you: it prints launchd on macOS, cron on Linux, schtasks (Task Scheduler) on Windows. Just run node scripts/schedule-setup.mjs --hour=8 and hand the user the printed commands. For an always-on schedule (machine may be off, or you're in a hosted/app context), use a cloud routine instead of a local scheduler — see SCHEDULING.md.
• No local shell / filesystem (claude.ai app or web)? Then the .mjs scripts and local scheduling don't apply. Read this SKILL + reference/API.md and call the Flow API directly (the response envelope and endpoints are the same); for automation, reach for a cloud routine rather than launchd/cron.

The response envelope (read this first)

Every response is wrapped:

{ "response": { "success": true, "code": 200, "message": "success", "data": { ... } } }

On failure data is replaced by error: { code, message } (messages are Korean). Always read response.data — scripts/flow.mjs unwraps it for you.

Core capabilities

Recommend mode (맞춤 추천)

When the user asks something like "뭘 자동화하면 좋을까?" / "추천해줘" / "내 상황에 맞는 거":

1. Run node scripts/recommend.mjs — it profiles their Flow (overdue, mentions, ownerless, no-deadline, projects, meetings…) via their key and ranks the recipe catalog by what's most actionable for them with the real numbers.
2. Present the top 2–3 in your own words ("밀린 1건·담당없는 11건이라 마감 트리아지·담당 배정이 0순위예요"), and offer to run one. Confirm before any write recipe.
3. Each recipe lives in recipes/ with its API combination and steps. To add a new one, copy recipes/_TEMPLATE.md (or scaffold it for the user from their description).

The complete endpoint list, request/response schemas, paging, and the field-name gotchas live in reference/API.md. Read it before composing any write call — several fields differ from what you'd guess (see Gotchas below).

Gotchas that will bite you (verified live)

• Date formats differ by endpoint. Tasks use YYYYMMDD (8). Schedules and calendar events use YYYYMMDDHHmmss (14).
• schedule.isAllDay is a boolean (true/false). But calendarEvent.allDayYn is a string ("Y"/"N"). Same concept, two types.
• Calendar-event create uses eventStartTimestamp / eventFinishTimestamp — yet the read endpoint returns eventStartDateTime / eventFinishDateTime. Don't mix.
• Todos require todoList: [{ contents }] — the checklist items, not a flat body.
• Workers / attendees must already be participants of the target project, or the call returns 412. Use GET /user/projects/{id}/participants to confirm.
• Paging is cursor-based: pass cursor, read data.hasNext / data.lastCursor, loop until hasNext === false.

Working style — be proactive (Hermes mode)

This skill is meant to act like a chief-of-staff, not a passive API wrapper.

1. Gather before answering. For any "what's going on" question, pull the relevant reads in a loop (projects → tasks, alarms, today's events) and synthesize — don't dump raw JSON.
2. Surface what needs attention. After reading, always call out: overdue/at-risk tasks, unread alarms, today's meetings, tasks with no owner.
3. Propose, then act. Offer concrete next actions ("3 tasks are past due — want me to push their deadlines or ping the owners?") and execute on confirmation.
4. Confirm before writes. Creating/patching changes a shared workspace. State exactly what you'll write (project, title, dates, assignee) and get a yes first.
5. Never invent ids. Resolve project/task/user ids from the read endpoints; never guess numeric ids or emails.

Safety

• The API key is a secret. Keep it in FLOW_API_KEY; never print it, commit it, or put it in slides/screenshots.
• Writes are real and immediate. There is no task/post delete in the API — only calendar events can be deleted. Prefer a throwaway/test project when experimenting.
• Don't call PATCH /user/alarms/read/all casually — it clears the user's entire alarm inbox state.