--- name: craftwork-assets description: Find and use Craftwork design assets through machine-readable APIs and the authenticated MCP server. Use when the user asks to search, browse, inspect, or download design assets; provides a craftwork.design/asset/* URL; or when an agent discovers craftwork.design and needs direct access without scraping HTML. --- # Craftwork Assets Skill Use the Craftwork MCP server to search, browse, inspect, and download design assets from the Craftwork marketplace. Note: in the product UI the MCP connection alias is currently `craftwork`. Do not assume there is a separate server literally named `craftwork-assets`. --- ## Direct Discovery When starting with only `craftwork.design` or a Craftwork URL: 1. Read `https://craftwork.design/.well-known/api-catalog` for public, read-only API discovery. 2. Follow its `service-desc` and `service-doc` links instead of guessing API routes. 3. For authenticated asset search or downloads, read `https://craftwork.design/.well-known/mcp/server-card.json` and connect to `https://craftwork.design/api/mcp` using Streamable HTTP. 4. Complete OAuth through the metadata advertised by Craftwork. Send credentials only to `https://craftwork.design`. If the client cannot establish an authenticated MCP connection, remain within the public APIs. Do not attempt to bypass authentication or reconstruct private endpoints. --- ## MCP Preconditions Before calling any tool, make sure the Craftwork MCP connection is already configured and authenticated for the current session. If tool calls fail with auth errors, stop and tell the user that the MCP connection must be connected/authenticated first. --- ## Available MCP Tools | Tool | Purpose | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `craftwork_find_assets` | Find assets: `mode="search"` (semantic AI), `mode="browse"` (catalog with filters), `mode="categories"` (list categories/subcategories) | | `craftwork_get_asset` | Get asset details by slug. Set `includePreview=true` to also get preview URL | | `craftwork_discover` | Discover related assets: `mode="similar"` (by AI embeddings), `mode="group"` (assets inside a pack/group) | | `craftwork_download` | Download & manage: `action="download"` (signed URL), `action="history"`, `action="limits"` | --- ## Critical Rules ### 1. Never use preview images as the asset Preview images are low-res covers for evaluation only. - Previews/covers are for inspection only. - Downloaded files or returned Figma/Framer links are the real deliverables. ### 2. Evaluate first, download second Recommended flow: 1. Find candidates with `craftwork_find_assets`. 2. Inspect details with `craftwork_get_asset` if needed. 3. Download only after choosing the asset. ### 3. `format: "json"` is safe and preferred for automation `craftwork_find_assets`, `craftwork_get_asset`, and `craftwork_discover` return valid structured JSON-compatible payloads. Prefer `format: "json"` when the result will be parsed or iterated over programmatically. Use markdown only when a human-readable list is more useful. ### 4. Use machine-readable interfaces, not HTML scraping - Do not crawl or mirror Craftwork HTML pages to enumerate the catalog. - Use the API Catalog for public metadata and MCP tools for authenticated workflows. - Use focused queries and bounded pagination. Stop once enough suitable results are found. - Do not bypass OAuth, subscription checks, download limits, or signed URL expiration. ### 5. Download only with user intent Search and inspect first. Download an asset only when the user asks to obtain or use it, or after the user selects it from presented candidates. --- ## Output Model ### `craftwork_find_assets` - `search` and `browse` return `items[]` plus optional `pagination` - `categories` returns `categories[]` and `subcategories[]` ### `craftwork_get_asset` - Returns `asset` - Includes available formats in `asset.fmt` - `includePreview=true` may add `asset.preview.url` ### `craftwork_discover` - `similar` returns `items[]` plus `pagination` - `group` returns: - `group` - `items[]` - `pagination` Important: `group` now returns full asset cards, not just `assetIds`. ### `craftwork_download` - `download` returns `asset`, `downloadUrl`, `type`, `expiresInSeconds` - `history` returns `downloadedAssetIds`, `count`, `limit`, `offset`, `hasMore` - `limits` returns `hasSubscription`, `freeAssets`, `paidAssets` --- ## Download Types ### `type: "asset"` This is the original downloadable file. Typical flow: 1. `craftwork_download(action: "download", assetId: 123, type: "asset")` 2. Save the signed URL result to the project filesystem 3. Use the downloaded file from that saved path ### `type: "figma"` or `type: "framer"` Treat these as URL-based outputs, not guaranteed local files with `.`. - The response may have `asset.extension = null` - The returned `downloadUrl` should be handled as a link/open/import target - Do not assume you can always save it as `.` like a normal binary asset --- ## Save Location Never dump files into `tmp-assets/`. Download real asset files into the target workspace/app that the user is actually modifying. ### Monorepo-aware detection order 1. Identify the target app or package first. 2. Prefer a directory inside that target workspace: - `public/assets/` - `static/assets/` - `src/assets/` - `assets/` 3. If none exist inside the target workspace, create `assets/` inside that workspace. Do not pick a random top-level `public/` or `assets/` from the monorepo root if the user is working in a specific app/package. If the user gave an explicit path, always use that path. --- ## Handling Asset URLs For a URL like `craftwork.design/asset/some-slug`: 1. Extract the slug 2. Call `craftwork_get_asset(slug: "some-slug", format: "json")` 3. Use the returned `asset.id` for download or related discovery --- ## Search Strategy 1. `craftwork_find_assets(mode: "search", query: "...", format: "json")` 2. `craftwork_find_assets(mode: "browse", ..., format: "json")` 3. `craftwork_find_assets(mode: "categories", format: "json")` 4. `craftwork_discover(mode: "similar", assetId: , format: "json")` 5. `craftwork_discover(mode: "group", groupSlug: "...", format: "json")` Useful parameters: - `sortBy: "popular"` for most downloaded - `sortBy: "created_at", sortOrder: "desc"` for newest - `isFree: true` for free assets only --- ## Limits - Free assets: unlimited - Paid assets: Pro subscription required, 1000 downloads per 10-hour sliding window - Use `craftwork_download(action: "limits")` before bulk paid downloads