> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/mcp/tools/skills-and-discovery.md).

# Skill and discovery tools

Reference for the FLORA MCP tools that list and read skills, create workspace skills, and list the tools on your connection.

These [FLORA MCP](https://flora.ai/mcp) tools help an agent find out what it can do. Skills are step-by-step playbooks for common jobs, such as batch generation or building a deck, and [`flora_list_tools`](#flora_list_tools) lists the tools on the current connection. See [FLORA MCP skills and plugins](https://docs.flora.ai/mcp/skills.md) for every skill and how to install them in your client.

| Tool                                              | What it does                                                                                                                | Labels    |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------- |
| [`flora_discover_skills`](#flora_discover_skills) | List FLORA's skills, or read one skill's instructions by name.                                                              | read-only |
| [`flora_list_tools`](#flora_list_tools)           | List the tools on this connection with a short purpose and safety hints for each.                                           | read-only |
| [`flora_create_skill`](#flora_create_skill)       | Save a shared skill to a workspace so every agent there can load it with [`flora_discover_skills`](#flora_discover_skills). | writes    |

## flora\_discover\_skills <a href="#flora_discover_skills" id="flora_discover_skills"></a>

List FLORA's skills, or read one skill's instructions by name.

**Labels:** read-only

**Shown in clients as:** Discover skills

**Use when:** Before a multi-step job such as a batch, a product-photo deck or a canvas iteration, or when a tool's description says to load a skill (for example `flora-deck-editor` or `flora-action-studio`).

**Don't use when:** You want the list of tools: use [`flora_list_tools`](#flora_list_tools). If a skill is missing, fetch `https://raw.githubusercontent.com/florafauna-ai/flora-mcp-skills/main/skills/<name>/SKILL.md` instead.

{% hint style="info" %}
On signed-in connections where the skill API is live, this tool also lists your own skills and your workspace's shared skills, and takes `scope` (`flora`, `user` or `workspace`) and `workspace_id`.
{% endhint %}

**Arguments**

| Argument     | Type                      | Required | Notes                                                                       |
| ------------ | ------------------------- | -------- | --------------------------------------------------------------------------- |
| `name`       | string, number or boolean | no       | Omit to list skills. Otherwise, use the exact name from a discovery result. |
| `skill`      | string, number or boolean | no       | Alias for name.                                                             |
| `skill_name` | string, number or boolean | no       | Alias for name.                                                             |
| `query`      | string, number or boolean | no       | Alias for name.                                                             |

**Returns:** Without `name`: each skill's name and description. With `name`: the skill's name, description and full instruction `content`, plus `references` when it has any.

**Cost:** Free. This tool doesn't spend money.

**Usually comes before:** [`flora_create_generations`](https://docs.flora.ai/mcp/tools/generations.md#flora_create_generations)

**Example prompt:** "Which FLORA skills can you use?"

**Example call:**

```json
{
  "name": "flora-batch-generate"
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Discover built-in FLORA skills. Call without a name to list them, or pass a name to read one.
```

{% endcode %}

</details>

## flora\_list\_tools <a href="#flora_list_tools" id="flora_list_tools"></a>

List the tools on this connection with a short purpose and safety hints for each.

**Labels:** read-only

**Shown in clients as:** List tools

**Use when:** You need to know which FLORA tools this account and client can use, for example before telling the user a capability is missing.

**Don't use when:** You need a tool's calling details: the purposes are short previews, so read the tool's full description and schema from your client's `tools/list`.

**Arguments**

None. Call it with `{}`.

**Returns:** `{guidance, tools}`: each tool's `name`, `title`, a `description_preview` (up to 480 characters) and its `annotations`. App UI entry points aren't included.

**Cost:** Free. This tool doesn't spend money.

**Usually comes before:** [`flora_discover_skills`](#flora_discover_skills)

**Example prompt:** "Which FLORA tools can you use right now?"

**Example call:**

```json
{}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
List the tools available to the model on this FLORA connection, with a short purpose and safety hints for each. These purposes are abbreviated previews, not calling instructions. Before calling a listed tool, read its full registered description and input schema from your host's tools/list, including payment, retry and permission constraints.
```

{% endcode %}

</details>

## flora\_create\_skill <a href="#flora_create_skill" id="flora_create_skill"></a>

Save a shared skill to a workspace so every agent there can load it with [`flora_discover_skills`](#flora_discover_skills).

**Labels:** writes

**Shown in clients as:** Create skill

{% hint style="info" %}
**Availability:** Only on signed-in connections, once the FLORA API serves skills. Creating a skill also needs the paid workspace-skills feature and write access to the workspace.
{% endhint %}

**Use when:** The user wants to turn a workflow into a reusable skill for their team.

**Don't use when:** The user wants a personal skill: the API can't write those. If the call is refused with `402` or `403`, ask for access or use a workspace that has the workspace-skills feature.

**Arguments**

| Argument       | Type   | Required | Notes                                                                                            |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `workspace_id` | string | yes      | Workspace (ws\_…) from flora\_list\_workspaces or current\_workspace\_id to create the skill in. |
| `name`         | string | yes      | Display name; the API derives the unique slug from it.                                           |
| `description`  | string | yes      | One-line summary shown in skill pickers.                                                         |
| `content`      | string | yes      | Skill body — the instruction text agents follow.                                                 |

**Returns:** The new skill's slug, which [`flora_discover_skills`](#flora_discover_skills) reads it by.

**Cost:** Free. This tool doesn't spend money.

**Usually comes after:** [`flora_list_workspaces`](https://docs.flora.ai/mcp/tools/workspaces-and-projects.md#flora_list_workspaces)

**Usually comes before:** [`flora_discover_skills`](#flora_discover_skills)

**Example prompt:** "Save these steps as a skill called Weekly social posts in our FLORA workspace."

**Example call:**

```json
{
  "workspace_id": "ws_123",
  "name": "Weekly social posts",
  "description": "Make five square social images from the weekly brief.",
  "content": "Read the weekly brief. Quote five 1:1 images with flora_create_generations and quote: true, show the cost in US dollars, run them after approval, then arrange them in a row."
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Create a shared skill in a workspace (ws_…) from flora_list_workspaces or current_workspace_id. The workspace needs the paid workspace-skills feature and write access; on a 402/403 refusal, ask for access or use a workspace that grants it. The content is the instruction body agents follow. Returns the slug flora_discover_skills retrieves it by. Personal user skills are not writable through this API.
```

{% endcode %}

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flora.ai/mcp/tools/skills-and-discovery.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
