Skills

A Flowy skill is an instruction pack, a SKILL.md, that teaches an agent how to do one kind of Flowy work well: directing a multi-shot film, keeping a character consistent across shots, composing a timeline, and so on. Skills aren’t installed ahead of time. The MCP server serves them on demand, mid-conversation, over the same connection as its tools: an agent calls list_skills to see what’s available, then load_skill to pull the full instructions into context right before it needs them.

The Flowy MCP server’s own instructions tell a connected agent to check for a matching skill before starting any non-trivial Flowy work (a video, canvas build, brand kit, render, or storyboard) and load it before writing to the canvas. You shouldn’t need to ask for a skill by name; a capable agent loads the right one on its own.

Tools

Tool	What it does
`list_skills`	List every skill with its name and one-line “use when” description.
`load_skill`	Fetch one skill’s full `SKILL.md` by name. Takes an optional `resource` argument for a file the skill references (e.g. `composition-schema.md`).

The catalog

Skills live in the Flowy backend, not in the MCP server. The server fetches them from the catalog API, so a skill edit reaches every connected agent without a redeploy.

One source. Each skill is a SKILL.md plus optional resource files, versioned and checksummed by the backend. The server holds no copy of its own.
Per-surface. Every skill declares the surfaces it applies to (mcp, agent) and the tools it names. The MCP server lists only the skills for the caller’s surface, selected by the x-flowy-surface request header (agent, otherwise mcp).
Cached for 60 seconds. The server keeps the catalog per process for 60 seconds, then revalidates it with If-None-Match; an unchanged catalog costs a 304. A skill edit shows up in load_skill within about a minute.
No offline fallback. If the catalog can’t be fetched, list_skills and load_skill return the tool error skill catalog unavailable, and the server instructions omit the skill index until it can.
Models live in the skill. Default models per intent are declared in the skill’s frontmatter. Per-model limits such as duration, reference counts, and audio come from search_models and get_model, never from numbers in skill text.

Call list_skills for the live set of skill names and descriptions.

REST

The same catalog is available over the REST API with any API key or OAuth token. No extra scope is required.

Endpoint	Returns
`GET /v1/skills?surface=mcp\|agent`	`{ data: [{ name, description, surfaces, tools, models, resources, version, checksum }], etag }`. The `ETag` header is the catalog etag; send it back as `If-None-Match` for a `304`.
`GET /v1/skills/{name}`	`{ name, version, checksum, body, tools, models }`.
`GET /v1/skills/{name}?resource={file}.md`	`{ name, version, checksum, content, tools, models }` for one resource file.

An unknown skill or resource returns 404 with code set to not_found or resource_not_found.

How an agent loads them

Connect MCP, then:

list_skills
load_skill name=flowy-film
load_skill name=flowy-compose resource=composition-schema.md

There is no GitHub skill pack and no npx skills add. flowy skill install is a notice that points here.

Get started

Endpoints

Reference

Tools

The catalog

REST

How an agent loads them

​Tools

​The catalog

​REST

​How an agent loads them

Tools

The catalog

REST

How an agent loads them