hypersocialinc/shots

/shots

Claude Code & Agent Skill to generate Upload-ready App Store screenshots that drive installs — powered by GPT-Image 2.

Demo — from App Store URL to finished screenshots

Type /shots in Claude Code. Paste your App Store URL to scrape your listing, let the skill research your app, market, theme, colors, and competitors, add your own screenshots to .shots/app-screenshots/, drop inspo into .shots/inspo/, and get scroll-stopping App Store screenshots in minutes — not days.

⚠️ API Key Required You need either:

• OPENAI_API_KEY with image generation enabled (GPT Image 2 access), OR
• FAL_KEY for fal.ai generation

Optional: SEARCHAPI_KEY from SearchAPI.io (free trial available) enables scraping your or other apps’ existing App Store screenshots to use as reference.

Install

Install the Shots skill to your AI coding agent:

# Install to your current project
npx skills add hypersocialinc/shots

# Install globally (available in all projects)
npx skills add hypersocialinc/shots --global

# Install to specific agents
npx skills add hypersocialinc/shots --agent claude-code cursor

Works with Claude Code, Cursor, Codex, Cline, and 40+ other AI coding agents.

Examples

Platform Support

Pricing

~$0.50 per generation (3 screenshots) · ~$0.17 per screenshot

Output image tokens account for ~95% of the cost and are fixed per composite size — prompt length and reference images are negligible. Based on real generation data and OpenAI GPT Image 2 pricing:

Commands

Everything runs through a single /shots command. Sub-flows are triggered conversationally:

You can also trigger sub-flows mid-conversation by saying “revise”, “translate to Japanese”, “scrape”, etc. Benefit headlines are crafted from a saved strategy brief during the create flow.

How It Works

Shots is a research-first screenshot generation system that produces conversion-optimized App Store and Google Play assets:

1. Initialize Workspace

Sets up a .shots/ directory in your project with config schema, manifest tracking, and folders for reference images.

2. Research Your App

Automatically gathers context from multiple sources:

• App Store scraping — Pulls metadata, ratings, description, and existing screenshots from your listing (iTunes API + optional SearchAPI for device-grouped screenshots)
• Repository analysis — Reads your README, package.json, and source code to understand your product
• Visual references — Inspects screenshots you drop into .shots/app-screenshots/ and inspiration images in .shots/inspo/
• Competitor mapping — Identifies 3-5 direct competitors and analyzes their positioning, visual themes, and review language

SearchAPI Integration: When SEARCHAPI_KEY is set, the scraper fetches device-grouped screenshots (iPhone, iPad, etc.) from the App Store, providing richer visual references than the iTunes API alone. Sign up at searchapi.io — free trial available.

3. Build Strategy Brief

Saves a reusable research artifact (strategyBrief in config.json) containing:

• App summary, target audience, market maturity
• Positioning (core promise, differentiator, proof points)
• Competitor analysis with visual/copy patterns
• Voice and language bank (tone, market words, taboo phrases)
• Visual theme (style family, mood, palette, motifs)
• Panel arc structure (Value → Flow → Trust narrative)

4. Craft Benefit Headlines

Generates 6-8 problem-first benefit statements ranked for install intent (transformations, not features). Headlines are saved to config.json and reused across revisions/translations.

5. Generate Image Composites

Creates wide panoramic composites via OpenAI’s GPT Image 2 (direct API or fal.ai) using:

• Saved strategy brief and benefits (not regenerated each time)
• Reference images for visual consistency
• Platform-specific dimensions (iPhone: 3456×2400, iPad: 6144×2732, Android: 3240×1920)
• Verbatim quote-based prompting for >95% text accuracy

6. Crop Into Panels

Automatically splits composites into 3 upload-ready individual screenshots with crop-safe boundaries (no text cutoff or visible seams).

7. Iterate or Translate

• Revise: Make surgical changes to existing shots while preserving strategy and visual identity
• Translate: Localize screenshot copy into other languages/locales without rebuilding visuals

All generated assets are versioned in timestamped run directories under .shots/runs/ (gitignored).

Requirements

• Node.js 18+
• OPENAI_API_KEY or FAL_KEY
• SEARCHAPI_KEY (optional) — improves App Store screenshot scraping with device grouping

Project Structure

skills/shots/
  SKILL.md                # Router, shared setup, config contract
  reference/
    create.md            # Create flow
    strategy.md          # Research + strategy brief + benefits
    prompting.md         # GPT Image 2 prompt contract
    revise.md            # Revision flow
    translate.md         # Localization flow
    scrape.md            # App Store scrape flow
  scripts/                # generate.mjs, crop.mjs, scrape.mjs
.shots/                   # Per-project workspace (created at runtime)
  config.json             # Scaffold-generated app/workflow schema
  runs/                   # Generated output (gitignored)

Show Us What You Made

Using Shots for your app? We’d love to see it! Open a PR adding a link to your App Store or Google Play listing and we’ll feature it here.