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

# Agent Skill

> A drop-in skill that teaches Claude, Cursor, and other AI agents how to drive the Moda MCP server effectively — without you re-explaining the rules in every conversation.

The Moda **agent skill** is a small Markdown package — one `SKILL.md` plus a gotchas reference and six task recipes — that you install into an AI agent. It teaches the agent how Moda's MCP tools work, which one to call for a given user request, and the non-obvious behaviors it should respect (concurrency caps for bulk fan-out, brand-kit resolution order, conversation vs. canvas vs. template semantics, etc.).

With the skill installed, the agent gets:

* A mandatory first-call **`get_moda_bootstrap`** handshake that loads workspace context and skips downstream lookups when defaults are unambiguous.
* A consolidated **gotchas reference** covering the silent failures the tool signatures can't communicate.
* **6 recipes** for the canonical design-task patterns (create / edit / find-a-template / fill-template / rebrand-template / bulk).
* Clear guidance on **`find_brand_kits` vs `list_brand_kits`** so brand-kit lookups don't take over the screen.

The skill works with any MCP-capable agent. Pick the install path that matches how you use Moda:

## Install

<Tabs>
  <Tab title="Claude Code (plugin)">
    Bundles the MCP server **and** the skill in one command:

    ```bash theme={null}
    claude /plugin marketplace add moda-design/skills
    ```

    Then enable the Moda plugin when prompted. The skill becomes active in any conversation that touches Moda.

    To update later:

    ```bash theme={null}
    claude /plugin marketplace update moda-design/skills
    ```
  </Tab>

  <Tab title="Vercel skills CLI">
    [Vercel's `skills` CLI](https://github.com/vercel-labs/skills) installs skills into Claude Code, Cursor, VS Code, or any other compatible client without touching MCP server config:

    ```bash theme={null}
    npx skills add github.com/moda-design/skills
    ```

    This is the right path if you already have the Moda MCP server connected (manually or via OAuth Custom Connector) and just want to add the skill on top.
  </Tab>

  <Tab title="claude.ai / Claude Desktop (zip upload)">
    For users on claude.ai web or Claude Desktop who aren't running a terminal — download the skill zip and upload it:

    1. Download the latest `moda-mcp` skill zip:
       [`github.com/moda-design/skills/releases/latest/download/moda-mcp.zip`](https://github.com/moda-design/skills/releases/latest/download/moda-mcp.zip)
    2. Open claude.ai (or Claude Desktop) → **Settings** → **Capabilities** → **Skills** → **Upload skill**.
    3. Select the downloaded `moda-mcp.zip`.
    4. In any chat where you want the skill active, enable it under the **+ Skills** menu in the message composer.

    <Note>
      Upload the per-skill `moda-mcp.zip`, **not** the bundled `skills.zip`. claude.ai's uploader
      requires exactly one skill per zip; `skills.zip` contains both `moda-mcp` and `moda-api` and
      will be rejected.
    </Note>

    The MCP server itself is added separately via the **Moda** Custom Connector — see [Setup](/mcp/setup) for that flow.
  </Tab>

  <Tab title="Manual include">
    For raw system prompts, the [Claude Agent SDK](https://docs.claude.com/en/docs/agents-and-tools/agent-sdk/overview), or any other context where you control the prompt:

    1. Clone or download [`github.com/moda-design/skills`](https://github.com/moda-design/skills).
    2. Include `skills/moda-mcp/SKILL.md` in your system prompt. The agent will autoload referenced files (`references/*.md`, `recipes/*.md`) as needed during the conversation.

    The agent SDK supports skill packages natively — see [the Agent SDK skills docs](https://docs.claude.com/en/docs/agents-and-tools/agent-sdk/skills) for the canonical wiring.
  </Tab>
</Tabs>

## What the agent learns

A short tour of the skill files, in order of how the agent uses them:

* **`SKILL.md`** — orientation page. The "call `get_moda_bootstrap` first" handshake, a 13-bullet "what goes silently wrong" sheet, a recipe map, and pointers to references.
* **`references/gotchas.md`** — single-page consolidated reference for non-obvious behaviors: the `format_category` default (an omitted category resolves to a generic `other` canvas at 1080×1080), the `wait`-default asymmetry between `start_design_task` and `remix_design`, the `canvas_id` / `template_canvas_id` / `conversation_id` mutual-exclusion matrix, brand-kit resolution order, attachment role semantics, the `not_ready` export retry state, and more.
* **`recipes/create-new-design.md`**, **`edit-existing-canvas.md`**, **`fill-template.md`**, **`rebrand-template.md`** — one short page per canonical design-task pattern. Mirrors the patterns documented at [Design Task Recipes](/api-reference/design-task-recipes), but framed for an AI agent making tool-call decisions.
* **`recipes/find-a-template.md`** — how to discover the team's curated templates and themes (`list_my_canvases` vs `search_canvases`, the `template_type` filter, what an empty result means), and the "be aware of a template's author-pinned instructions, don't restate them, don't contradict them" contract that governs the prompt written against a template.
* **`recipes/bulk-variants.md`** — fan-out patterns for "make N variations of this": windowed launch respecting the plan's `concurrency_cap` (from `get_moda_bootstrap`), `list_tasks(status="running")` polling, deliver-as-queued UX.

## Stay updated

The skill ships from the [`moda-design/skills`](https://github.com/moda-design/skills) GitHub repo. Watch the **Releases** page for changelogs.

* Released versions: [github.com/moda-design/skills/releases](https://github.com/moda-design/skills/releases)
* Latest `moda-mcp` skill zip (stable URL): [github.com/moda-design/skills/releases/latest/download/moda-mcp.zip](https://github.com/moda-design/skills/releases/latest/download/moda-mcp.zip)

Each release also attaches `moda-api.zip` (the REST-API skill) and `skills.zip` (both skills bundled, for tooling that wants everything in one download).

When a new version ships, `claude /plugin marketplace update`, `npx skills add` (re-run), or a re-upload of the zip all pull the latest.

## See also

* [MCP Tools Reference](/mcp/tools) — full tool catalog with parameters
* [Design Task Recipes](/api-reference/design-task-recipes) — the canonical patterns the skill recipes are based on (REST + MCP side-by-side)
* [Setup](/mcp/setup) — install paths for the MCP server itself