> ## Documentation Index
> Fetch the complete documentation index at: https://flow.engineer/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Teach a workflow

> Give your tools the instructions an agent needs to use them well.

A skill teaches a workflow: when to look up information, which tool to use, what to confirm
and what to do next. The tools perform the operations; the skill explains how they fit together.

Teach the task, not a fixed dialogue. Someone may give all the details at once, add a correction
or ask a question halfway through. A useful skill explains what must be known before an action
and when to ask, without making the person work through a form one message at a time.

Skills live in `agent/skills/<name>/SKILL.md`. Flow uses the same source files in your messaging
agent, standalone MCP server and generated plugin packages.

## Write a skill

After adding the `get_hours` tool in [Write a tool](https://flow.engineer/docs/build-agent.md), create
`agent/skills/opening-hours/SKILL.md`:

```md agent/skills/opening-hours/SKILL.md
---
name: opening-hours
description: Use when someone asks when the business opens, closes or can be visited.
---

Call get_hours for the current opening and closing time.

State the business time zone with the hours. If someone asks for the time in
their own zone and you do not know it, ask them which time zone to use.
```

The description is how an agent discovers the skill. Make it specific enough that the agent can
decide to load it without reading the whole file.

## Where the skill goes

**Messaging agent**

`createAgent({ dir })` reads `AGENTS.md` and `skills/` from the agent folder. The model sees
skill descriptions and loads the full instructions when needed.

Set `inlineSkills: true` to include every skill in the prompt instead of loading them on demand.

**Standalone MCP**

`mcpServer({ dir })` adds skill descriptions to the server's instructions and exposes
`read_skill`. An MCP host can read a skill when it needs the workflow.

The server and messaging agent can point at the same `agent/` folder.

**CLI**

`skill list` shows skill names and descriptions, plus the generated `<cli-name>-cli` guide.
`skill get <name> [name...]` reads only the selected instructions; `--json` returns named records.
The CLI uses the standalone MCP endpoint and the same skill source files as the agent.
See [CLI skills](https://flow.engineer/docs/cli.md#list-and-read-skills) for examples and exporting selected SKILL.md files.

**Plugin**

`flow plugin` copies the skills into the generated packages. Each package connects to
`/mcp/plugin`, the tools-only endpoint, so the host receives each skill once.

[Regenerate the packages](https://flow.engineer/docs/plugins.md) when a skill or its assets change.

## Keep instructions portable

Write about your product's workflow and name its tools. Platform formatting and send tools are
already handled by Flow for messaging.

> [!NOTE]
>
> A skill shipped through MCP or a plugin must use tools that endpoint actually exposes.
> `flow check` reports references to chat-only tools; plugin generation refuses them.

## Check it worked

Restart the MCP server or messaging agent, then ask “When do you open?” In the playground,
turn on **Debug** and look for the skill load and `get_hours` call. A model may skip a skill it
already has enough information to answer without; the important result is that the hours come
from the tool.

For a plugin, regenerate the output and run:

```sh Terminal
npx @flow-engineer/flow check --plugin plugins
```

## Agent instructions and coding-agent skills

These files have different readers:

| Location          | Reader                                 | Purpose                          |
| ----------------- | -------------------------------------- | -------------------------------- |
| `agent/AGENTS.md` | Your messaging agent                   | Its role, scope and behavior     |
| `agent/skills/`   | Your agent and MCP or plugin hosts     | Product workflows                |
| `.claude/skills/` | The coding agent building your project | How to use Flow Framework        |
| Root `AGENTS.md`  | The coding agent building your project | Project development instructions |

`flow new` installs the coding-agent skills for you. Edit the files in `agent/` to change how
your product behaves, rather than the framework skills that explain how to build it.

> **[Try your workflow in the playground](https://flow.engineer/docs/playground.md)**
>
> Switch people and channels, inspect tool calls and test sign-in.