Abhi5415/pinterest-pin

Pinterest Pin (Autonomous)

Fully autonomous end-to-end workflow for producing and publishing SEO-optimized Pinterest pins (1000x1500 PNG) for @claridoapp. Auto-selects topics, generates content, validates text against layout limits, renders via Remotion, visually reviews via agent, publishes via Chrome automation, and emails results. No human approval gates.

Invoked by the user with /pinterest-pin or when asked to create Pinterest content.

The full method with render specs, props format, and SEO guidelines is in docs/pinterest-pin-method.md. Read that file before starting.

Autonomous Workflow

All phases run without user intervention. The visual review agent is the critical quality gate replacing human review.

Phase 1: Topic Selection (auto, no approval)

The user may invoke this skill in two ways:

• With a topic: User provides a specific concept, keyword, or idea. Skip auto-selection and use it.
• Without a topic: Auto-select using the priority logic below.

Two modes, selected automatically:

Blog-driven (priority)

1. Read ALL content/pinterest/*/brief.md files to see which topics already have pins.
2. Read ALL blog posts at ~/dev/clarido-landing-page/content/blog/ to find published articles.
3. Cross-reference: identify blog posts that don't yet have a matching Pinterest pin.
4. For each unmatched blog post, queue a pin. Choose Tips or Comparison format based on the blog content (default to Tips unless the concept is inherently comparative like "rumination vs reflection").
5. Log the reasoning: "Found N blog posts without pins: [list]. Producing pins for: [list]."

Keyword-opportunity (fallback)

When ALL blog posts already have pins:

1. Select from the 30-concept topic bank (same as blog production — see Phase 1 of the blog-production skill for the full list).
2. Pick the topic with the strongest search opportunity that complements existing pin coverage.
3. Default to Tips format unless the concept is inherently comparative.
4. Log the reasoning: "All blog posts have pins. Selected [topic] because [rationale]."

Proceed immediately. Do NOT present topics or wait for approval.

Phase 2: Content Generation + Pre-Render Validation (auto)

For each pin in the batch:

2a. Generate SEO Fields & Visual Content

5. Write SEO-optimized content:

   • Pin title: ≤100 chars, primary keyword first, benefit-focused
   • Pin description: ~150-200 chars, natural keywords, CTA at end ("Save this for later")
   • Alt text: ~100-150 chars, descriptive + keyword
   • Link: Always use the matching blog post URL (e.g., https://clarido.app/blog/slug). Only fall back to https://clarido.app if no blog post exists for this topic. Published pins cannot have their destination URL edited after posting.
   • Visual content: Tips format (4-5 numbered items with headline, description, citation) or Comparison format (left/right titles, descriptions, 1 section with bullets)

6. Create content folder (content/pinterest/YYYY-MM-DD_HHMM_slug/) and save brief.md.

2b. Pre-Render Text Validation

Before rendering, validate ALL text fields against character limits derived from the Remotion component layouts. This catches overflow before spending time on illustration generation and rendering.

Tips format limits (from PinterestTipsPin/index.tsx — 1000px wide canvas, 44px side padding):

| Field | Max Chars | Derivation | |-------|-----------|------------| | title | 55 | 40px uppercase, ~32 chars/line at this font size, 2 lines max before pushing illustration down | | subtitle | 25 | 18px uppercase with letter-spacing 4 inside a small yellow pill | | tip.headline | 30 | 28px bold, single line in the space beside the 48px number badge | | tip.description | 85 | 22px, 2 lines in the remaining horizontal space after badge + gap | | tip.citation | 30 | 17px italic, "Author, Year" format — single line | | Tips count | 4-5 | Flex layout distributes evenly with justifyContent: space-between; 6+ overflows the canvas |

Comparison format limits (from PinterestComparisonPin/index.tsx — two half-width columns with gap and divider):

| Field | Max Chars | Derivation | |-------|-----------|------------| | leftTitle / rightTitle | 15 | 38px uppercase in a half-width column (~456px usable) | | leftDescription / rightDescription | 55 | 22px centered text, 2 lines max in half column | | section.header | 20 | 20px uppercase with letter-spacing 4 inside yellow pill | | Bullet items (leftItems / rightItems) | 50 | 24px in half column, 2 lines max | | Items per section | 5 max | More items overflow the canvas below the footer |

Validation loop (max 2 retries):

7. Check every field against its character limit.
8. If any field exceeds its limit: shorten the text while preserving meaning. Log which fields were shortened.
9. Re-check. If still exceeding after 2 retries, truncate to limit with ellipsis and log a warning.

2c. Asset Generation & Rendering

10. Write illustrations.json to {content-folder}/assets/illustrations.json:

    • Tips format: 1 illustration
    • Comparison format: 2 illustrations

    [{"name": "pin-{concept}-icon", "prompt": "Scene description for illustration"}]
    

11. Generate illustrations (run from repo root):

    pipenv run python3 scripts/tiktok/illustrations.py {content-folder}/assets/illustrations.json {content-folder}/assets/illustrations/
    

12. Copy illustrations to Remotion public: cp {content-folder}/assets/illustrations/*.png videos/public/

13. Write props.json to content folder. Icon filenames must match the generated illustration names exactly.

14. Render the still:

    cd videos && npx remotion still PinterestTipsPin out/{slug}.png --props=../{content-folder}/props.json
    

    (or PinterestComparisonPin for comparison format)

15. Copy PNG back to content folder.

For batch mode: Parallelize steps 10-15 across all pins in the batch (illustration generation, rendering). Each pin is independent.

Phase 3: Visual Review Agent (critical quality gate)

For each rendered pin, launch a separate Opus agent to evaluate the rendered PNG. This replaces human visual review.

16. Launch the visual review agent using the Agent tool with subagent_type: "general-purpose" and model: "opus". Pass the following prompt:

You are a visual quality reviewer for Pinterest pin images. Review this rendered pin and determine if it meets publication quality standards.

## Files to Read

1. **Rendered PNG**: `{path-to-rendered-png}` — Read this file (it's an image, the Read tool supports images)
2. **Brief**: `{path-to-brief.md}` — Read for context on what this pin should contain
3. **Props**: `{path-to-props.json}` — Read for the exact text that should appear on the pin

## Brand Guidelines

- Simple white character with black outlines, gray watercolor shading
- Yellow (#FFD60A) as the ONLY color accent
- Clean, minimal, conceptual illustrations (not literal/photographic)
- Off-white/cream background (#FAFAF8)
- Professional, polished, save-worthy quality

## Review Criteria

Evaluate each criterion and rate as PASS or FAIL:

### CRITICAL (any failure = overall FAIL)

1. **Text Readability**: All text must be fully visible, not truncated, not cut off at edges, not overlapping other elements. Every word in the props.json must be readable on the pin.

2. **Layout Balance**: Proper spacing between all elements. Illustration positioned correctly (not overlapping text, not pushed off-canvas). No content overflowing below the footer or off the sides. Tips/bullets evenly distributed.

### IMPORTANT (2+ failures = overall FAIL)

3. **Illustration Quality**: The illustration should match the pin's concept (e.g., a pin about "brain dumping" should show someone writing/journaling, not an unrelated scene). Must follow brand style (white character, black outlines, gray shading, yellow accents only). Should be recognizable at thumbnail size (Pinterest users browse small).

4. **Overall Professional Quality**: The pin should look polished, intentional, and save-worthy. No rendering artifacts, no misaligned elements, no awkward whitespace gaps. Would a real Pinterest user save this?

## Output Format

Respond with EXACTLY this structure:

VERDICT: PASS or FAIL

TEXT_READABILITY: PASS/FAIL — [1-sentence explanation]
LAYOUT_BALANCE: PASS/FAIL — [1-sentence explanation]
ILLUSTRATION_QUALITY: PASS/FAIL — [1-sentence explanation]
PROFESSIONAL_QUALITY: PASS/FAIL — [1-sentence explanation]

ISSUES: [If FAIL, list specific issues that need fixing. Be precise: "title text is truncated after word X", "illustration overlaps the first tip", "bullet 3 text overflows to a third line". If PASS, write "None".]

FIX_SUGGESTIONS: [If FAIL, list specific fixes: "Shorten title to X characters", "Revise illustration prompt to show Y instead of Z". If PASS, write "None".]

17. Parse the agent's response:
    • Extract the VERDICT (PASS or FAIL)
    • If PASS: proceed to Phase 4
    • If FAIL: enter the retry loop

Retry Loop (max 3 total attempts)

18. On FAIL, apply fixes based on the agent's FIX_SUGGESTIONS:

    | Failure Type | Fix Action | |-------------|------------| | Text truncation/overlap | Shorten the offending field in props.json, re-validate against char limits, re-render (~5s) | | Illustration wrong concept/style | Revise the prompt in illustrations.json, regenerate illustration (~30s), copy to videos/public/, re-render | | Layout overflow | Reduce content (fewer tips, shorter bullets), update props.json, re-render | | Both text and illustration issues | Fix text first (faster), then illustration if still failing |

19. After fixing, re-render and re-launch the visual review agent.

20. After 3 failed attempts: skip this pin. Log the failure with the agent's last feedback summary. Continue to the next pin in the batch. Report all failures in the final email.

Phase 4: Publishing via Chrome Automation (sequential)

Publish each pin that passed visual review. One pin at a time (Chrome can only handle one tab interaction at once).

Prerequisites: Load Chrome tools via ToolSearch before using them.

21. Upload image to Supabase (the post_pin.py script uploads to Supabase before hitting the API 403):

    pipenv run python3 scripts/pinterest/post_pin.py {image-path} \
        --title "..." --description "..." --alt-text "..." --link "..."
    

    Note the Supabase public URL from the output.

22. Get browser tab context: Call tabs_context_mcp with createIfEmpty: true.

23. Create a new tab and navigate to https://www.pinterest.com/pin-creation-tool/.

24. Click "Save from URL" link (visible at bottom of the upload area).

25. Type the Supabase public URL into the "Enter website" field and press Enter.

26. Wait 3 seconds for Pinterest to fetch and display the image thumbnail.

27. Click the image thumbnail to select it (checkmark appears).

28. Click "Add 1 Pin" button (bottom right).

29. Fill in SEO fields on the pin editor page:

    • Title: Use form_input on the title textbox ref.
    • Description: This is a contenteditable <div> (combobox), NOT a standard input. Use left_click on the field, then type to enter the text.
    • Alt text: Click the "Add alt text" button first to reveal the field, then use form_input on the revealed textarea ref.
    • Fix the link: Use form_input with the destination link ref to replace the auto-populated Supabase URL with the blog post URL (e.g., https://clarido.app/blog/slug). Do NOT use cmd+a to select. Use read_page with filter: "interactive" to find the link textbox ref, then form_input to set the value.

30. Verify with a screenshot, then click Publish button (red, top right).

31. Confirm success: Pinterest shows "You created a Pin!" modal. Click "See your Pin" to get the pin URL. Save the URL to the pin's brief.md.

32. Clean up Supabase: Delete the temporary image file after publishing.

33. Repeat steps 21-32 for each remaining pin in the batch.

Phase 5: Email Notification (auto)

After the entire batch completes (all pins published or skipped), send a single summary email.

34. Send email via mcp__google-workspace__send_gmail_message:

    • To: [email protected]
    • CC: [email protected]
    • Subject: {N} Pinterest Pins Published — {YYYY-MM-DD}
    • Body (plain text):

      {N} Pinterest pins published for @claridoapp.
      
      PUBLISHED:
      1. {Pin Title}
         Pinterest: {pin URL}
         Links to: {blog URL}
         Format: {Tips/Comparison}
         Visual review: passed on attempt {1/2/3}
      
      2. ...
      
      FAILED (if any):
      1. {Pin Title}
         Reason: {agent's last feedback summary}
         Draft saved: {content folder path}
      
      ---
      Sent by Clarido Marketing Automation
      

35. Report to user — Share the batch summary: number published, number failed, Pinterest URLs, and confirmation that the email was sent.

Batch Orchestration

When invoked without a specific topic, the skill finds ALL gaps (blog posts without matching pins) and produces them in batch:

• Content generation, illustration, rendering, visual review: Parallel across pins (each pin is independent)
• Chrome publishing: Sequential (one tab, one pin at a time)
• Estimated throughput: ~12-15 min for 3 pins, ~20-25 min for 5 pins

When invoked with a specific topic, produce a single pin end-to-end.

Content Folder Structure

content/pinterest/YYYY-MM-DD_HHMM_slug/
├── brief.md              # SEO fields, tips/comparison content, keywords
├── assets/
│   ├── illustrations/    # 1-2 PNGs (brand style icons)
│   └── illustrations.json
├── props.json            # Remotion render props
├── performance.md        # Analytics (filled after posting)
└── slug.png              # Final 1000×1500 image

Publishing Workarounds

The Pinterest API app is on Trial access, which blocks pin creation in production (403 error). The Chrome automation "Save from URL" flow is the workaround.

What Does NOT Work (Don't Waste Time)

• Fetching external URLs via JavaScript on Pinterest's page: CORS blocks it.
• Base64 injection: PNG is ~500KB base64 (~510K chars). Too large.
• Clicking the file upload drop zone: Opens native macOS file dialog — Chrome extension can't interact with OS-level UI.
• Local HTTP server: Mixed content (Pinterest HTTPS, localhost HTTP).
• upload_image tool: Screenshots are viewport-resolution JPEG, not the original 1000x1500 PNG.

Critical Details

• Two Remotion components: PinterestTipsPin and PinterestComparisonPin — registered in Root.tsx under <Folder name="Pinterest">
• Render as still: Use npx remotion still, NOT npx remotion render
• Canvas size: 1000x1500 (Pinterest optimal 2:3 ratio) — NOT 1080x1920
• Icon filenames: Must match exactly between illustrations.json names, props.json icon fields, and files in videos/public/
• Image size: Illustrations generated at 1024x1536 portrait — do NOT use 1024x1024
• SEO is king: Pinterest is search-first. Keywords in title, description, AND alt text. No hashtags.
• Run end-to-end: Generate illustrations, render, review, publish, email — don't stop at code
• Published pins can't have their URL edited — Always set the correct blog URL at creation time
• Pinterest API auth: If you get a 401, run pipenv run python3 scripts/pinterest/refresh_token.py

Key Files

• Method doc: docs/pinterest-pin-method.md
• Tips component: videos/src/PinterestTipsPin/index.tsx
• Comparison component: videos/src/PinterestComparisonPin/index.tsx
• Publish script: scripts/pinterest/post_pin.py
• Board listing: scripts/pinterest/get_boards.py
• Illustration generator: scripts/tiktok/illustrations.py
• Brand reference images: assets/illustrations/overwhelmed-filing-cabinet.png, floating-yellow-balloon.png, planting-yellow-seedling.png