Shots

Shots

Shots runs through hosted MCP tools. Durable state lives in Convex, generated screenshots and icons are uploaded to the Shots CDN, and completed jobs return CDN URLs plus stable ids.

The hosted MCP server instructions are the source of truth for tool names, arguments, billing recovery, polling cadence, app setup, and review URLs. Use help.schema, help.examples, and help.search before guessing command args.

Use The References

• Create screenshot campaigns: reference/create.md
• Write screenshot prompts: reference/prompting.md
• Visual inspiration and style examples: reference/inspiration.md
• Research positioning and ASO copy: reference/strategy.md
• Generate app icons: reference/icons.md
• Revise screenshots: reference/revise.md
• Translate screenshots: reference/translate.md
• Lookup App Store listings: reference/scrape.md

Intent Router

Local Project Rules

• The user's app repo is the source of product truth. The Shots plugin files are only tool documentation; never infer the target app identity from them.
• For a new app record, the agent must know the app name, what it does, App Store URL if published, and target platform before calling apps.upsert or apps.import.
• Inspect local files, saved app context, and existing media before asking the user, but do not guess when ambiguity changes the product or creative direction. Ask for missing positioning, audience, real UI truth, style preferences, or approval when needed.
• Before screenshot generation, require at least one real app UI reference: uploaded app_screenshot, a reference image showing actual app UI, or scraped App Store screenshots. An icon, palette, or written description alone is not enough.
• If the user provides local image files, or you discover useful local screenshots/assets in the repo, upload them first and use the returned media IDs. Do not put local paths in the prompt and assume the image model can see them.
• Codex/local-agent screenshot generation is explicit-reference-first. Inspect available media, choose the exact references for each panel, pass them as referenceMediaIds, and describe each reference's job in the prompt. Do not rely on Studio/backend default reference selection for quality; that fallback exists for non-agent UI flows.
• For unpublished apps, inspect local screens, navigation, theme tokens, preview fixtures, docs, and screenshots. Save durable findings to the app record so Studio and future sessions share the same context.
• Before generating a screenshot set, present a markdown table with one row per screenshot and wait for approval or edits.
• Do not choose a public gallery app as inspiration from a vague request like "try a new style" or "different style." Use gallery inspiration only when the user names/provides an inspiration source or explicitly approves the exact gallery app/screenshot in the plan. Gallery-inspiration generation should stay on medium quality.
• If the user asks for a new or different style without specifics, ask for style preferences or propose 2-4 concrete directions and get approval before generating.
• If the user asks for a small change to an existing generated screenshot, skip a new campaign plan and use screenshots.revise instead.

Local Upload Helper

Use media.import_url for HTTPS images. For local files, use the bundled helper:

node <plugin-root>/scripts/upload-asset.mjs --file ./path/to/image.png --app-id <appId> --kind reference

Resolve <plugin-root> as the plugin root directory. From this SKILL.md, the helper is at ../../scripts/upload-asset.mjs.

Useful kind values:

• app_screenshot for real product UI
• icon for the app icon
• inspo for user-provided mood references
• reference for general brand or product references

The helper calls POST https://shots.run/api/upload by default. The endpoint is intentionally open and unauthenticated; it only needs appId and enforces server-side upload safety checks. Do not skip local uploads because R2 or cloud credentials are unavailable.

If an upload fails, stop and call feedback.report with category: "bug", the HTTP status or error message in details, and relatedTool: "upload-asset" plus the appId. Do not generate while treating a required local reference as unavailable unless the user explicitly approves continuing without it.

App Icon Discovery

If the user gives an App Store URL or app id, prefer apps.import; it imports the public icon and saves it as an app icon asset.

If there is no App Store URL, inspect the local app repo and upload the best source icon with --kind icon:

• iOS/Xcode: *.xcassets/AppIcon.appiconset/Contents.json, then referenced PNGs
• Expo: app.json, app.config.*, expo.icon, ios.icon, android.icon
• React Native: iOS app icon sets and Android mipmap-* assets
• Web/PWA fallback: public/manifest.json, public/icon.png, favicons

Quality Bar

• Screenshots are ads, not documentation. Each panel needs a user-facing promise and a specific UI moment that proves it.
• Use real UI facts in prompts: screen names, layout, visible data, controls, states, and emotional payload.
• Treat visible product UI as closed-world. Critical user direction overrides references; otherwise preserve reference UI and never invent plausible rows, controls, labels, values, or states the references do not show.
• Keep references selective. Pass only the images that a specific screenshot actually needs.
• Prefer selected/promoted App Store screenshots for product and campaign continuity when they are relevant. Do not pass recent unpromoted generations as references unless the user selects them or asks to continue from them.
• Do not request fake App Store chrome, gutters, dividers, rounded screenshot borders, or fictional product UI.

Feedback Reporting

Use feedback.report to notify the Shots team about product feedback, feature ideas, unsupported workflows, confusing behavior, user frustration or delight, repeated generation or revision quality issues, and tool or infrastructure errors.

Report when:

• The user directly says something is broken, confusing, annoying, useful, or delightful.
• The user asks for a workflow Shots does not support, such as bulk applying one revision to a whole set.
• You infer a feature idea from the user's goal or repeated workaround.
• A generated or revised screenshot still looks wrong after multiple tries.
• Billing, authentication, setup, upload, or gallery inspiration behavior confuses the user.
• Any MCP tool call returns an unexpected error, including HTTP errors from the upload helper, isError: true responses from Shots commands, or other infrastructure failures. Use category: "bug" with severity: "high", include the error message or HTTP status in details, and set relatedTool or relatedCommand to identify the failing operation.

Include any relevant appId, mediaId, jobId, relatedTool, or relatedCommand. Use a short userQuote when the user's exact words matter, and concise agentContext for what you observed or tried.

After reporting a derived idea or issue, briefly tell the user you notified the Shots team. Do not imply this creates a support ticket, guaranteed fix, or personal follow-up.