--- id: preview-deck-operate name: Preview Deck — operate description: | Use this skill to build, edit, and ship App Store and Google Play screenshots through Preview Deck via its HTTP agent API. Triggers on prompts about App Store / Play Store screenshots, Preview Deck projects, screenshot creatives, and any "make me a review URL for these screenshots" workflow. triggers: - create app store screenshots - make play store screenshots - use preview deck - turn these screenshots into app store creatives - edit the preview deck project - update the screenshots and give me a review link - design app store assets - design google play assets homepage: https://app.previewdeck.com docs: https://app.previewdeck.com/agents/api schema_endpoints: - https://app.previewdeck.com/api/agent/v1/schema/document - https://app.previewdeck.com/api/agent/v1/schema/job --- # Preview Deck — operate ## When to use This skill applies whenever the user asks an AI agent to build, edit, or ship App Store / Google Play screenshots and gives the agent access to a Preview Deck account. It does NOT cover screenshot-content strategy (e.g. "what story should I tell on screen 2?") — that's an external concern in phase 1. Trigger on prompts such as: - "create app store screenshots" - "make play store screenshots" - "use preview deck" - "turn these screenshots into app store creatives" - "edit the preview deck project" - "update the screenshots and give me a review link" - "design app store assets" - "design google play assets" ## Prerequisites The agent must collect from the user: 1. A Preview Deck API key (created at `https://app.previewdeck.com/settings/api-keys`). 2. Source screenshots and any imagery the user wants composited. 3. A short description of the App Store or Play Store story to tell. ## Capabilities - **Verify API key** — Confirm the supplied API key is valid before doing anything else. `GET /api/agent/v1/me` _(scope: projects.read)_ - **Create project** — Start a fresh Preview Deck project with a base device family. `POST /api/agent/v1/projects` _(scope: projects.write)_ - **Read canonical document** — Fetch the full editor document, including all overrides, before mutating. `GET /api/agent/v1/projects/{id}/document` _(scope: projects.read)_ - **Read resolved family view** — Fetch the override-resolved view for a single family. Preferred for rendering or screenshot-by-screenshot reasoning. `GET /api/agent/v1/projects/{id}/view?familyId={familyId}` _(scope: projects.read)_ - **Upload an asset** — Issue a signed upload URL for a new screenshot or overlay image. Agents must NEVER inject arbitrary URLs. `POST /api/agent/v1/projects/{id}/assets/uploads` _(scope: assets.write)_ - **Submit a mutation job** — Queue a full-document replacement. The job runs async; poll until terminal. `POST /api/agent/v1/projects/{id}/jobs` _(scope: projects.write)_ - **Poll a job** — Read job status. Statuses: queued, running, succeeded, failed. `GET /api/agent/v1/jobs/{jobId}` _(scope: projects.read)_ - **Fetch live JSON schemas** — Retrieve the EditorDocumentV1 and AgentMutationJobRequestV1 JSON schemas at runtime instead of hardcoding. `GET /api/agent/v1/schema/document` ## Workflow 1. **Collect prerequisites from the user** — Ask the user for: (1) a Preview Deck API key, (2) the source screenshots/assets, (3) a brief description of the App Store / Play Store story they want to tell. 2. **Verify the API key** — GET /api/agent/v1/me with the key. Stop and report if the request fails. 3. **Create or open a project** — POST /api/agent/v1/projects to create one, or use the projectId the user supplies. 4. **Upload assets through issued URLs** — For every image asset, POST /api/agent/v1/projects/{id}/assets/uploads, then PUT the bytes to the returned signed URL. NEVER inline arbitrary public URLs into the document — they will be rejected as invalid_asset_reference. 5. **Read the latest document** — GET /api/agent/v1/projects/{id}/document. Use the returned document and documentVersion as the canonical base for your edits. For per-family rendering, prefer GET /view?familyId=... 6. **Submit a full-document replacement job** — POST /api/agent/v1/projects/{id}/jobs with { baseDocumentVersion, nextDocument, changeLabel, allowDestructive? }. The endpoint returns 202 + jobId. 7. **Poll until the job reaches a terminal state** — GET /api/agent/v1/jobs/{jobId} until status is succeeded or failed. On success, the response includes a diff, a changeSummary, and a handoffUrl. 8. **Surface the diff and handoff URL to the user** — Always show the user the changeSummary and the handoffUrl so they can review the run in the editor. 9. **Refetch before iterating** — For follow-up edits, refetch the document so your baseDocumentVersion is current. Stale versions return 409 revision_conflict. ## What you MUST do - Ask the user for an API key before any agent API call. - Ask the user for source screenshots / assets before composing the document. - Upload assets only through Preview Deck-issued upload URLs. - Always submit full-document replacement jobs (no patches). - Poll the job until status is succeeded or failed. - Surface the returned diff and handoff URL to the user. - Refetch the latest document before every follow-up mutation. - Ask the user for confirmation before submitting destructive edits (allowDestructive=true). ## What you MUST NOT do - Fetch arbitrary asset URLs and inject them into the document. - Assume browser session auth works for /api/agent/v1/* — only API keys do. - Treat stale documents as safe to overwrite — refetch first. - Bypass the user review step. The handoffUrl exists for that. ## Error semantics | Code | HTTP | Meaning | Recovery | |------|------|---------|----------| | `invalid_api_key` | 401 | Missing, malformed, expired, or revoked key. | Ask the user for a fresh key. | | `insufficient_scope` | 403 | Key lacks the scope this endpoint requires. | Ask the user to mint a new key with the correct scopes. | | `rate_limited` | 429 | Per-minute rate limit hit on this route group. | Back off and retry after one minute. | | `project_not_found` | 404 | Project does not exist or is not owned by this user. | Re-list projects and retry with a valid id. | | `revision_conflict` | 409 | Submitted baseDocumentVersion is stale. | Refetch the document, replay your edits on the new version, resubmit. | | `destructive_change_denied` | 409 | Diff would delete entities and allowDestructive was false. | Confirm with the user, then resubmit with allowDestructive: true. | | `invalid_asset_reference` | 400 | A document asset reference is not namespaced under the project, or was not issued via the upload endpoint. | Issue a new upload URL, upload the bytes, then reference the returned asset. | | `invalid_request` | 400 | Request body failed Zod validation. | Inspect the response.issues array, fix the shape, resubmit. | | `job_failed` | 400 | A queued job entered the failed state. Inspect errorCode/errorMessage on GET /jobs/{jobId}. | Read the failure code and follow that code's recovery. | | `job_timeout` | 400 | Server-side sweeper marked the job failed after exceeding maxDuration. | Refetch the document and resubmit a smaller job (split into multiple). | ## Install ### Codex CLI Adds the Preview Deck skill to your Codex environment. ```bash codex skill add https://app.previewdeck.com/skill.md ``` ### Claude Code Installs the skill into Claude Code. ```bash npx skills add https://app.previewdeck.com/skill.md ``` ### Cursor Adds the skill to Cursor's agent context. ```bash cursor agent install https://app.previewdeck.com/skill.md ``` ### Manual Pipe the skill body into any other agent runtime that accepts markdown skill files. ```bash curl https://app.previewdeck.com/skill.md ``` ## Public docs - [AI agents · Preview Deck](https://app.previewdeck.com/agents) — Use Preview Deck from your AI coding agent. API key auth, async jobs, full-document mutations, and a human review handoff. - [Agent API · Preview Deck](https://app.previewdeck.com/agents/api) — Endpoints, auth, scopes, error semantics, and the exact call flow for AI agents driving Preview Deck. - [Agent design guide · Preview Deck](https://app.previewdeck.com/agents/design-guide) — How to structure projects, families, screenshots, frames, text overlays, image overlays, and gradients well. - [Agent review loop · Preview Deck](https://app.previewdeck.com/agents/review-loop) — How the human reviews agent runs, how the handoff URL behaves, and what to do after feedback. ## Live JSON schemas - https://app.previewdeck.com/api/agent/v1/schema/document — `EditorDocumentV1` - https://app.previewdeck.com/api/agent/v1/schema/job — `AgentMutationJobRequestV1` Both are stable, cacheable, and authoritative. Prefer fetching them at runtime over hardcoding the shape into the agent.