{
  "markdown": "# Moda Skills\n\n> **Create editable, brand-aligned slides and designs.**\n\nModa is an AI design agent that creates brand-aligned slides, one-pagers, ads, graphics, and more on a fully editable canvas. This repo ships two installable agent skills that teach any AI agent to drive Moda like a power user:\n\n- [`moda-mcp`](./skills/moda-mcp/SKILL.md) — the Moda MCP server. Kick off designs from a conversation in Claude / Cursor / VS Code / Gemini. Generate a deck from a prompt, spin up variations in bulk, customize a template for a prospect, pull an existing canvas into chat to revise, or turn a Moda canvas into production code.\n- [`moda-api`](./skills/moda-api/SKILL.md) — the Moda REST API. Scheduled jobs, CI pipelines, webhook receivers, and backend integrations authenticated with an API key.\n\nInstall once and your agent knows the canonical design-creation flow, the prompt-gathering ritual before `start_design_task`, the brand-kit default, the 2–10 minute async task lifecycle, the `format_category` disambiguation table (including `carousel`), the prefixed-ID rule, the typed error envelope, and the webhook verification pattern — without re-deriving them from the docs every time.\n\n📖 **Full docs and install walkthroughs:** [docs.moda.app/mcp/agent-skill](https://docs.moda.app/mcp/agent-skill)\n\n## Which install should I pick?\n\n| Situation | Install path |\n| --- | --- |\n| You already have the Moda MCP connected, or only want the REST-API skill | **Vercel `skills` CLI** — `npx skills add moda-design/skills` (skills only, no MCP touch) |\n| You're new to Moda and want one-shot skills + MCP setup | **Editor-native plugin** — pick your editor below |\n| You use Codex and want skills + MCP setup | **Codex plugin** — use the bundled [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json) manifest |\n| You're on Claude Desktop, claude.ai, or Claude Mobile | **OAuth Custom Connector** — pair with `npx skills add` on a machine where you code |\n| You write raw system prompts or use the Claude Agent SDK | **Manual include** — `@include skills/moda-mcp/SKILL.md` |\n\nEvery install path ultimately surfaces the same Markdown files under [`skills/`](./skills/). The per-editor manifests (`.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/`, `gemini-extension.json`, `.mcp.json`) just bundle them with the right install ritual for each host.\n\n## Install\n\n### Claude Code — plugin (bundles skills + MCP)\n\n```bash\nclaude /plugin marketplace add moda-design/skills\nclaude /plugin install moda\n```\n\nClaude Code registers both skills and adds the `moda` MCP server from [`.mcp.json`](./.mcp.json). The first time a tool fires, you'll sign in via OAuth in your browser. If you already have a `moda` server configured, disable the plugin's bundled MCP in plugin settings or use the skills-only path instead.\n\n### Claude Code — skills only (no MCP change)\n\n```bash\nnpx skills add moda-design/skills -a claude-code\n```\n\nInstalls both skills under `.claude/skills/`. Use this if you already connected the Moda MCP (or prefer to connect it manually — see the [Moda MCP setup docs](https://docs.moda.app/mcp/setup)).\n\nIf you only want one skill:\n\n```bash\nnpx skills add moda-design/skills --skill moda-mcp -a claude-code\nnpx skills add moda-design/skills --skill moda-api -a claude-code\n```\n\n### Cursor — plugin\n\n```\n/add-plugin moda-design/skills\n```\n\nCursor reads [`.cursor-plugin/plugin.json`](./.cursor-plugin/plugin.json) and auto-registers the skills plus the MCP server. The OAuth flow runs on first tool call. Skills-only fallback:\n\n```bash\nnpx skills add moda-design/skills -a cursor\n```\n\nManual MCP setup lives in [`.cursor/mcp.json`](https://docs.moda.app/mcp/setup) — same `streamable-http` config:\n\n```json\n{\n  \"mcpServers\": {\n    \"moda\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"https://mcp.moda.app/mcp\"\n    }\n  }\n}\n```\n\n### Claude Desktop / claude.ai (browser) / Claude Mobile\n\nFirst add the Moda Custom Connector:\n\n1. Open **Customize** in the sidebar → **+** → **Add custom connector**.\n2. **Name**: `Moda`. **URL**: `https://mcp.moda.app/mcp`. Click **Add**, then **Connect** and sign in.\n\nThen add the skill. Two options:\n\n- **Upload the skill zip** (no terminal needed): download [`moda-mcp.zip`](https://github.com/moda-design/skills/releases/latest/download/moda-mcp.zip) from the latest release, then in claude.ai go to **Settings → Capabilities → Skills → Upload skill** and select the file. (Use the per-skill `moda-mcp.zip`, not the bundled `skills.zip` — claude.ai's uploader requires a single skill per zip.)\n- **`npx skills add`**: on a machine where you also code, run `npx skills add moda-design/skills`.\n\nTeam/Enterprise claude.ai users: an admin must first add the Moda connector in **Admin Settings > Connectors**.\n\nMobile picks up connectors you've added on claude.ai automatically.\n\n### VS Code\n\nAdd to your user or workspace `settings.json`:\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"moda\": {\n        \"type\": \"streamable-http\",\n        \"url\": \"https://mcp.moda.app/mcp\"\n      }\n    }\n  }\n}\n```\n\nThen install the skills:\n\n```bash\nnpx skills add moda-design/skills -a vscode\n```\n\n### Gemini CLI\n\n```bash\ngemini extensions install https://github.com/moda-design/skills\ngemini /mcp auth moda\n```\n\nThe extension manifest at [`gemini-extension.json`](./gemini-extension.json) registers the MCP server; the `auth` step opens the OAuth flow.\n\n### Codex\n\nThe Codex plugin manifest lives at [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json). It registers both skills from [`skills/`](./skills/) and points Codex at the Moda MCP server in [`.mcp.json`](./.mcp.json).\n\nTo package plugin visuals, add PNG assets under `assets/` and reference them from the manifest:\n\n```json\n{\n  \"interface\": {\n    \"composerIcon\": \"./assets/icon.png\",\n    \"logo\": \"./assets/logo.png\",\n    \"logoDark\": \"./assets/logo-dark.png\",\n    \"screenshots\": [\n      \"./assets/screenshot-create-design.png\",\n      \"./assets/screenshot-export-flow.png\"\n    ]\n  }\n}\n```\n\nOnly add those fields when the files exist in the plugin package; Codex plugin validation rejects missing logo or screenshot paths.\n\n### Other agents / raw `CLAUDE.md` include\n\nFor the Claude Agent SDK, Continue, Windsurf, or any agent that reads Markdown from a known path, either:\n\n- Run `npx skills add moda-design/skills -a <agent>` (the CLI supports 45+ agents).\n- Or include the SKILL.md directly in your system prompt:\n\n  ```markdown\n  @include skills/moda-mcp/SKILL.md\n  @include skills/moda-api/SKILL.md\n  ```\n\nFor HTTP clients that don't have a plugin concept, hand-configure from [`.mcp.json`](./.mcp.json) — the URL is `https://mcp.moda.app/mcp`.\n\n## What's in each skill\n\n### [`moda-mcp`](./skills/moda-mcp/SKILL.md)\n\nFor agents running inside chat / IDE hosts (Claude Desktop, Claude.ai, Claude Code, Claude Mobile, Cursor, VS Code, Gemini CLI). OAuth-authenticated by default.\n\nCovers the 17 MCP tools, the session-context ritual (`get_context` / `set_context`, 24h TTL), the **required prompt-gathering checklist** before any `start_design_task` call, brand kits (create from a website URL, `skip_brand_kit`), attachments (file-id + role vs URL form), the 2–10 minute async task lifecycle, the seven `format_category` values including `carousel` (Instagram / LinkedIn / story), design-to-code via `get_moda_canvas`, and the known wrong guesses that break tasks.\n\nBundled recipes: brief-to-deck, customize-for-prospect, bulk-variants, pull-existing-canvas, design-to-code, onboard-new-brand, iterate-in-conversation.\n\n### [`moda-api`](./skills/moda-api/SKILL.md)\n\nFor server-side integrations authenticated with a `moda_live_…` API key — scheduled jobs, CI pipelines, webhook receivers, backend workers. No human in the loop.\n\nCovers Bearer auth and the 13 scopes, `Moda-Version: 2026-05-01` pinning, the canonical Task envelope (`{id, kind, status, result, error, progress, links, retry_after_ms}`), prefixed-ID strictness in bodies vs tolerance in path parameters, cursor pagination, the typed error envelope with `request_id`, `idempotency_key` on `POST /v1/tasks`, `Prefer: wait` caps and when it's useful (brand-kit creation, not design tasks), `callback_url` webhook verification, and the synchronous export endpoint with its `409 Conflict + Retry-After: 10` \"active task in progress\" state.\n\nBundled recipes: scheduled-generation, bulk-personalization, export-pipeline, webhook-receiver, brief-to-deck-pdf-intake, design-to-code-ci (with TypeScript + Python examples each).\n\n## Principles\n\n- **Second-person, imperative voice.** \"Call `set_context` first.\" Not \"you might want to.\"\n- **Skills are summons, not substitutes.** This repo compresses the load-bearing facts; [`docs.moda.app`](https://docs.moda.app) is the source of truth. Every reference links back.\n- **Every example is canonical.** `moda_live_…` keys, `Moda-Version: 2026-05-01` on every write, every ID in a JSON body is prefixed (`cvs_…`, `task_…`, `bk_…`, `file_…`).\n- **Status vocabulary is surface-specific.** The MCP tools (`get_task_status`) use `queued` / `running` / `completed` / `failed` / `cancelled`. The canonical REST API (`GET /v1/tasks/{id}`) uses `queued` / `running` / `succeeded` / `failed` / `canceled` / `expired`. Each skill uses the vocabulary of its surface — don't mix them up.\n- **Every reference file ends with a \"Common wrong guesses\" section.** Bare UUIDs in bodies, `format_category='pdf'` for an Instagram post, treating a `not_ready` export as an error, polling without `retry_after` — these are the real failure modes agents repeat.\n\n## Troubleshooting\n\n**MCP server not connecting**\n\n- **Claude Desktop**: Check Moda appears under **Settings → Connectors**. Re-add if missing; restart the app.\n- **Claude.ai (browser)**: Check [claude.ai/settings](https://claude.ai/settings) → **Connectors**. Remove and re-add.\n- **Claude Code**: `claude /mcp` to list servers. `claude mcp remove moda` and re-add.\n- **Claude Mobile**: Connectors sync from claude.ai. Add there first, then restart the mobile app.\n- **Cursor**: Check **Cursor Settings → MCP**. Try restarting the server from the panel.\n- **VS Code**: Confirm the stanza is in user or workspace `settings.json`. Restart VS Code after changes.\n\nFull MCP setup + troubleshooting lives in the canonical docs: [docs.moda.app/mcp/setup](https://docs.moda.app/mcp/setup).\n\n**Skills not showing up**\n\n- Confirm install target: `npx skills add moda-design/skills --list` shows both skills.\n- Claude Code reads `~/.claude/skills/` (user) or `./.claude/skills/` (project). Verify the files are there.\n- Skills load when the conversation matches their `description` — if yours doesn't match, try prompting explicitly: \"use the moda-mcp skill to ...\"\n\n**`callback_url` rejected on a design task**\n\nThe `callback_url` parameter is **API-key-auth only**. OAuth-authenticated MCP callers get `400` (\"callback_url is only supported for API-key authenticated callers\"). Use polling from the MCP surface, or issue the task from a server with an API key.\n\n## Canonical Moda docs\n\n- [MCP overview](https://docs.moda.app/mcp) · [Agent skill install guide](https://docs.moda.app/mcp/agent-skill) · [Setup](https://docs.moda.app/mcp/setup) · [Tools reference](https://docs.moda.app/mcp/tools) · [Creating designs](https://docs.moda.app/mcp/create-designs) · [Design-to-code](https://docs.moda.app/mcp/design-to-code) · [MCP authentication](https://docs.moda.app/mcp/authentication)\n- [REST API overview](https://docs.moda.app/api) · [Authentication](https://docs.moda.app/api/authentication) · [Versioning](https://docs.moda.app/api/versioning) · [Webhooks](https://docs.moda.app/api/webhooks)\n- Plain-text for any LLM: [`llms.txt`](https://docs.moda.app/llms.txt) · [`llms-full.txt`](https://docs.moda.app/llms-full.txt)\n\n## Issues & feedback\n\nFile issues at [github.com/moda-design/skills/issues](https://github.com/moda-design/skills/issues). Product feedback on Moda itself goes to [support@moda.app](mailto:support@moda.app).\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n",
  "bytes": 12012,
  "sha": "9595ab07d57aea87fb06a1e511dc26c95a4e1534ed72ddfe1156f2e42ab9a708",
  "repo_slug": "moda-design/agent-plugins",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_moda_design_agent_plugins_6b0efecf/readme"
}