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

# Offer agent skills

Tools give an AI agent the ability to *call* your API. **Skills** give it the *know-how* to use those tools well. A skill is a short markdown playbook — a `SKILL.md` document — that teaches an agent how to accomplish a multi-step task with your server's tools, for example:

> *To create an order: first call `list_customers` to find the customer, then call `create_order` with their id, then confirm with `get_order`.*

This guide explains how to author skills and how AI clients consume them.

## How clients consume a skill

When a skill is enabled, the runtime offers it to connected MCP clients in two ways, so it works regardless of how advanced the client is:

* **As a resource** — the playbook is published at `skill://<slug>/SKILL.md`. Clients that support MCP resources list available skills and read the playbook on demand (progressive disclosure).
* **As a wrapper tool** — a read-only tool named `skill_<slug>` is also registered. Calling it returns the same playbook. This is the compatibility path for clients that don't yet surface resources or a native skills extension.

Enabled skills are also summarized in the server's `instructions`, so the model learns they exist on connect.

## Managing skills from an agent

Skills can be managed two ways: from the dashboard (below) or by an AI agent connected to the [FlowCP MCP server](/guides/agent-driven-onboarding.md). The agent surface exposes skills as tools — `list_skills`, `create_skill`, `update_skill`, and `delete_skill` — so an agent can author and toggle skills for a server without leaving the chat. Like the dashboard, new skills start **disabled**.

## Opening the skills list

From your app's dashboard, click the **Skills** tab. The page lists every skill on the selected server, each with an on/off switch. If your app has multiple environments (branches), use the branch buttons to switch between them.

## Creating a skill

1. Click **New skill**.
2. Fill in the fields:
   * **Name** — a `snake_case` identifier, e.g. `create_order`. The wrapper tool is derived from it as `skill_create_order`.
   * **Description** — a one-line summary shown to the agent so it can decide when the skill is relevant.
   * **SKILL.md body** — the markdown playbook itself. Reference your tools by their exact names and spell out the steps in order.
3. Click **Create skill**.

New skills are created **disabled**, following the platform's default-deny model — see [Default-deny model](/security/default-deny-model.md).

## Generating skills with AI

If you're not sure where to start, let AI draft skills for you. Click **AI Suggestions** on the Skills page. FlowCP reads the selected server's tools and asks an LLM to propose **three** skills that chain those tools into real workflows.

Each suggestion shows its name, a one-line description, and a preview of the playbook. Click **Use this** on the one you want — it opens the skill editor **pre-filled** so you can review and adjust the wording before saving. Nothing is created until you click **Create skill**, and (like every skill) it starts disabled.

AI Suggestions require an AI provider to be configured for the platform. If it isn't, the button reports that suggestions aren't available — you can still author skills manually.

## Enabling a skill

Toggle the switch on a skill's row to **On** to offer it to AI clients. Changes take effect immediately — no re-publish required. Disabled skills are never exposed as a resource or a tool.

## Editing and deleting

* Click the **pencil** icon to edit a skill's name, description, or body. Renaming re-derives the slug and the wrapper tool name.
* Click the **trash** icon to delete a skill. This cannot be undone.

## Writing effective skills

* **Name the tools explicitly.** Use the exact tool names from the [Tools](/guides/review-and-customize-tools.md) page so the agent can map steps to calls.
* **Be procedural.** List steps in order, including how to handle the common failure case.
* **Keep it focused.** One skill per task or flow reads better than a single catch-all document.
* **Enable the tools it references.** A skill is only useful if the tools it mentions are themselves enabled.