ClaudeMarketing/docs/reference/FULL_SYSTEM_ANALYSIS.md

Fully Autonomous Marketing Team — Complete System Analysis

Source: "I Built a Fully Autonomous Marketing Team with Claude Code & Claude Skills" by Andy (AndyNoCode) Video: https://www.youtube.com/watch?v=iVbsl60t0oA Demo Brand: Cold Brew Coffee Co. Creator's Account: proxa_official (Instagram), Dark Eve (YouTube)

---

1. Complete Folder/File Structure

Cold Brew Coffee Co/
├── .claude/                          # Claude Code configuration
├── assets/                           # Creative references / mood board
│   ├── coffee_can.png.jpeg           # Branded cold brew can with water droplets
│   ├── coffee_glass.png.jpeg         # Iced coffee in glass
│   └── morning_cafe.png.jpeg         # Warm cafe lifestyle scene
├── knowledge/                        # Brand brain — 3 files
│   ├── brand_identity.md             # 128 lines — personality, tone, voice, emoji/hashtag strategy
│   ├── platform_guidelines.md        # 142 lines — per-platform specs, formatting, caption rules
│   └── product_campaign.md           # 199 lines — product details, features, campaign direction
├── node_modules/                     # NPM dependencies
│   └── @tavily/                      # Tavily AI SDK (v0.7.2)
├── outputs/                          # All generated content
│   ├── market_research_2025/         # Research agent test output
│   │   ├── cold_brew_market_research_2025.html
│   │   └── cold_brew_market_research_2025.md
│   ├── remotion_test_video/          # Video agent test output
│   │   └── cold_brew_ad.mp4          # 15s test video, 2MB
│   ├── test_playwright_ad/           # Static ad agent test output
│   │   └── ads/
│   │       ├── coffee_can.png
│   │       ├── lifestyle_morning.png
│   │       ├── styles.css
│   │       └── instagram_ad.png      # 1080x1080 final ad
│   └── test_job_payload_1_20260315/  # Full pipeline run output
│       ├── ads/
│       │   ├── ad_layout.json
│       │   ├── ad.html
│       │   ├── styles.css
│       │   └── instagram_ad.png      # 1080x1080, 949.5KB
│       ├── copy/
│       │   ├── instagram_caption.txt
│       │   ├── threads_post.txt
│       │   ├── youtube_metadata.json
│       │   └── copy_output.json
│       ├── video/
│       │   ├── scene_plan.json
│       │   └── video_ad.mp4          # 20s, 600 frames, 2.15MB
│       ├── interactive_report.html   # Campaign Intelligence Dashboard
│       ├── media_urls.json           # Supabase public URLs
│       ├── Publish test_job_payload_1 2026-03-15.md  # Publishing manifest
│       ├── research_brief.md
│       └── research_results.json
├── pipeline/
│   └── publish_now.js                # Node.js publishing script
├── remotion-ad/                      # Remotion video project
│   ├── public/
│   ├── src/                          # Video compositions, SVG components
│   ├── .gitignore
│   ├── entry1.mjs
│   ├── package.json
│   └── package-lock.json
├── skills/                           # All 5 agent skills
│   ├── ad-creative-designer/
│   │   └── SKILL.md                  # 191 lines (later extended to 331 lines with Steps 7-9)
│   ├── copywriter-agent/
│   │   └── SKILL.md                  # 261 lines
│   ├── distribution-agent/
│   │   └── SKILL.md                  # 352 lines
│   ├── marketing-research-agent/
│   │   └── SKILL.md                  # 146 lines
│   └── video-ad-specialist/
│       └── SKILL.md                  # 167 lines
├── .env                              # Real API keys (gitignored)
├── .env.example                      # Template showing required keys
├── .gitignore                        # Excludes .env and node_modules/
├── CLAUDE.md                         # Project source of truth for Claude Code
├── package.json                      # 18 lines, NPM project config
├── package-lock.json
├── render_ad_test.js                 # 36 lines, Remotion render test script
├── tavily_results.json               # Cached Tavily research results
├── tavily-search.js                  # Tavily search script
└── Ultimate Claude Skills & Plugins Prompt.md  # 601 lines — skill creation framework

---

2. Every Agent and What It Does

Agent 1: Marketing Research Agent

Skill file: skills/marketing-research-agent/SKILL.md (146 lines) Pipeline position: First stage — feeds all downstream agents Trigger phrases: "research a market", "generate campaign insights", "find ad hooks", "start the pipeline"

What it does:

1. Collects niche/topic, optional audience, and campaign goal
2. Runs 5 targeted Tavily queries covering: trends, competitors, pain points, ad hooks, viral content
3. Synthesizes findings across 5 categories
4. Outputs machine-readable JSON with: content_topics, marketing_angles, keywords, video_concepts, ad_hooks
5. Provides plain-language handoff summary pointing to next agent

Key design: The video_concepts objects map directly to the Video Ad Specialist's input format. Output is structured data, not just text — downstream agents consume it programmatically.

Output files:

• research_results.json — structured JSON for other agents
• research_brief.md — human-readable markdown report
• interactive_report.html — Campaign Intelligence Dashboard with charts, competitor analysis, keyword lists

Agent 2: Video Ad Specialist

Skill file: skills/video-ad-specialist/SKILL.md (167 lines) Pipeline position: Third stage (after research) Category: creative-production (v1.0.0) Trigger phrases: "create a video ad", "generate ad scenes", "build a video campaign", "make a Remotion video"

What it does:

1. Gathers inputs (product, goal, platform, length)
2. Reads knowledge files first (CRITICAL rule) — brand_identity.md, product_campaign.md, platform_guidelines.md
3. Generates creative brief with ad strategy (types: product_showcase, problem_solution, testimonial, limited_offer, lifestyle, meme_style)
4. Creates scene-by-scene breakdown with platform-specific pacing
5. Outputs scene JSON in Remotion-ready structure
6. Wraps around the Remotion Best Practices official skill — this skill handles the brand, Remotion handles the craft

Platform-specific pacing:

• Instagram Reels: Hook ~2s, Product ~5s, Benefit ~3s, CTA ~2s = 10-12s total
• YouTube Shorts: Similar with slightly longer holds

Audit checklist enforced:

• Hook starts with motion at frame 0 (not static)
• Hook copy ≤6 words
• CTA scene exists, 2-3s minimum
• Logo + CTA visible in final scene
• No scene holds static >1.5s (except CTA)
• Ratio variants via props, not hardcoded px
• Text overlay: 5 words max

Output files:

• scene_plan.json — scene structure for Remotion
• video_ad.mp4 — auto-rendered (no manual Remotion Studio step)

Agent 3: Ad Creative Designer

Skill file: skills/ad-creative-designer/SKILL.md (191→331 lines after extension) Pipeline position: Second stage (after research) Trigger phrases: "create an ad", "design a social ad", "generate ad layout", "make an image creative", "build a static ad"

What it does (9-step workflow):

1. Gather Inputs — product, campaign goal, platform, image assets, layout type
2. Select Ad Layout Type — three types:
   • Product Focus: headline top, product image center, CTA bottom
   • Split Layout: image left, copy right (or reversed)
   • Lifestyle: full-bleed background, text overlay
3. Steps 3-6: Generate design JSON with layout, typography, spacing, colors
4. Step 7 — HTML Rendering: Layout-specific HTML templates, CSS with typography scale (72px headline, 36px subtext, 12px CTA), 1080x1080 container, pulls brand colors from brand_identity.md
5. Step 8 — Playwright Screenshot: Headless Chromium, file:// path, networkidle wait, exact 1080x1080 clip
6. Step 9 — Output Storage: outputs/TASKNAME_DATE/ads/, task not complete until all 3 files exist

Three-step workflow: Generate (NanoBanana MCP) → Design (HTML/CSS) → Capture (Playwright)

Copy constraints:

• Headline: 3-4 words
• CTA: must start with action verb
• Instagram Stories safe zone: no text in top/bottom 15%

Output files:

• ad_layout.json — design spec
• ad.html + styles.css — rendered ad layout
• instagram_ad.png — 1080x1080 pixel-accurate screenshot

Agent 4: Copywriter Agent

Skill file: skills/copywriter-agent/SKILL.md (261 lines) Pipeline position: Fourth stage (after creative agents) Trigger phrases: Related to writing captions, descriptions, platform-specific copy

What it does:

• Handles all marketing copy: captions, descriptions, platform-specific writing
• Knows brand voice from knowledge folder
• Knows platform formats from guidelines
• Generates separate files per platform
• YouTube metadata includes: title, description, tags (as JSON)

Output structure: outputs/{task_name}_{date}/copy/

Output files:

• instagram_caption.txt — Hook + value/vibe + CTA + hashtags
• threads_post.txt — Witty, conversational, 500 chars max
• youtube_metadata.json — title, description, tags
• copy_output.json — consolidated copy data

Agent 5: Distribution Agent

Skill file: skills/distribution-agent/SKILL.md (352 lines) Pipeline position: Final stage — consumes outputs from Research + Copywriter agents

6-step workflow:

1. Gather inputs — locates media files, research JSON, and copy outputs in campaign folder
2. Upload to Supabase — all media → campaign-uploads bucket with unique filenames ({task_name}/{date}_{filename}), saves media_urls.json map
3. Assemble metadata — pulls captions/titles/tags from copy outputs, validates against brand + platform guidelines
4. Scheduling advisory — recommends posting windows per platform, cross-referenced with research audience data
5. Write Publish MD — generates Publish <task_name>-<date>.md with full metadata, URLs, schedule, and checklist
6. Execute publishing (gate-protected) — only fires when user explicitly names the Publish MD file; Instagram uses two-step container→publish flow; YouTube uses OAuth; Threads logs manual note (no public API)

Safety: No posting without explicit user approval. Gate-protected publishing.

Output files:

• media_urls.json — Supabase public URLs
• Publish <task_name> <date>.md — publishing manifest with URLs, copy, metadata, scheduling
• Published content via pipeline/publish_now.js

---

3. All External Tools and How They Connect

Core Development Tools

Tool	Purpose	Details
Claude Code	IDE agent orchestration	v2.1.76, Sonnet 4.6 / Claude Pro
Antigravity	VS Code-based IDE	"Open Agent Manager" feature, multi-model support
Claude.ai	Planning/brainstorming	Used to draft skill descriptions before building in Claude Code

Content Generation Tools

Tool	Purpose	How Connected
Remotion	Programmatic video rendering	Official Claude skill (remotion-best-practices) + custom video-ad-specialist skill wrapping it. React-based. Uses useCurrentFrame, interpolate, spring, <Series.Sequence>. Font: @remotion/google-fonts/Inter
NanoBanana MCP	AI image generation	Called by ad-creative-designer skill to generate product/lifestyle images using brand knowledge as reference
Playwright	HTML→PNG screenshot	Node.js library, headless Chromium. Captures HTML ad layouts at exact 1080x1080 pixels with networkidle wait
Tavily AI	Web search/research API	@tavily/core v0.7.2. 1,000 free credits/month. Marketing-research-agent runs 5 targeted queries per execution

Publishing/Storage Tools

Tool	Purpose	Configuration
Supabase Storage	Media file hosting	Public bucket: campaign-uploads. Files must be at publicly accessible URLs for Instagram API. Service role key (not anon key) for server-side uploads
YouTube Data API	Video upload	OAuth 2.0 required for publishing (API key alone = read-only)
Instagram Graph API	Image/video posting	Two-step flow: create container → publish. Requires instagram_business_basic + instagram_business_content_publish permissions. Tokens expire every 60 days
Threads API	Text post publishing	Uses THREADS_ACCESS_TOKEN. No public upload API at time of video

Optional/Mentioned Tools

Tool	Purpose
BullMQ + Redis	Automated queuing and scheduled execution (optional extension)
Rasterize.io	Mentioned as having limitations with transparent backgrounds (workaround: CSS round-frame approach)
Google Antigravity AI Chat	Used for individual agent testing to save Claude Code tokens

---

4. Environment Variables Required

# .env.example

# Tavily AI -- Web Research
TAVILY_API_KEY=tvly-YOUR_API_KEY

# YouTube Data API
YOUTUBE_API_KEY=YOUR_YOUTUBE_API_KEY                    # Read-only operations
YOUTUBE_CLIENT_ID=YOUR_YOUTUBE_CLIENT_ID                # OAuth 2.0 (required for uploads)
YOUTUBE_CLIENT_SECRET=YOUR_YOUTUBE_CLIENT_SECRET         # OAuth 2.0
YOUTUBE_REFRESH_TOKEN=YOUR_YOUTUBE_REFRESH_TOKEN         # Long-lived token

# Instagram Graph API
INSTAGRAM_ACCOUNT_ID=YOUR_INSTAGRAM_PROFESSIONAL_ACCOUNT_ID    # Numeric Professional Account ID
INSTAGRAM_ACCESS_TOKEN=YOUR_INSTAGRAM_USER_ACCESS_TOKEN        # Expires every 60 days!

# Threads API
THREADS_ACCESS_TOKEN=YOUR_THREADS_ACCESS_TOKEN

# Supabase -- Media Storage
SUPABASE_URL=YOUR_SUPABASE_PROJECT_URL                  # e.g., https://xxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY=YOUR_SUPABASE_SERVICE_ROLE_KEY # Server-side only! Bypasses RLS

---

5. End-to-End Workflow

Phase 1: Setup (One-Time)

1. Create project folder with assets/, knowledge/, skills/ structure
2. Populate assets/ with brand images (mood board)
3. Write 3 knowledge files: brand_identity.md, platform_guidelines.md, product_campaign.md
4. Write CLAUDE.md — declares system architecture, agents, responsibilities, folder structure
5. Create the "Ultimate Claude Skills & Plugins Prompt.md" (601-line skill creation framework)
6. Install dependencies: npm install @tavily/core, set up Playwright, set up Remotion project
7. Configure Supabase: create campaign-uploads public bucket
8. Set up API credentials in .env

Phase 2: Skill Creation (One-Time per Agent)

For each of the 5 agents:

1. Plan in Claude.ai — use Sonnet 4.6 to brainstorm skill details via interactive Q&A
2. Draft key details — purpose, inputs, outputs, workflow, trigger phrases
3. Build in Claude Code — prompt: "Help me create an agent skill. I will give you the key details. Use @'Ultimate Claude Skills & Plugins Prompt.md' to create it."
4. Paste key details — Claude reads the framework doc + key details, generates SKILL.md
5. Test individually — run each agent alone (optionally in Google Antigravity to save tokens)
6. Iterate — refine skill files based on test results

Phase 3: Pipeline Execution (Per Campaign)

Single Job Payload (JSON) → Claude Code
         │
         ▼
┌─────────────────────────┐
│  1. RESEARCH AGENT      │ ← Tavily API (5 web queries)
│     Outputs:            │
│     - research_results.json (machine-readable)
│     - research_brief.md
│     - interactive_report.html (dashboard)
└──────────┬──────────────┘
           │ JSON consumed by ↓
┌──────────┴──────────────┐
│  2. AD CREATIVE DESIGNER│ ← NanoBanana MCP (image gen)
│     Outputs:            │   ← Playwright (HTML→PNG)
│     - ad_layout.json    │
│     - ad.html + styles.css
│     - instagram_ad.png  │
└──────────┬──────────────┘
           │
┌──────────┴──────────────┐
│  3. VIDEO AD SPECIALIST │ ← Remotion (video rendering)
│     Outputs:            │
│     - scene_plan.json   │
│     - video_ad.mp4      │ (auto-rendered, no manual step)
└──────────┬──────────────┘
           │
┌──────────┴──────────────┐
│  4. COPYWRITER AGENT    │
│     Outputs:            │
│     - instagram_caption.txt
│     - threads_post.txt  │
│     - youtube_metadata.json
└──────────┬──────────────┘
           │
┌──────────┴──────────────┐
│  5. DISTRIBUTION AGENT  │ ← Supabase (media upload)
│     Steps:              │ ← YouTube API (video publish)
│     - Upload to Supabase│ ← Instagram API (image publish)
│     - Assemble metadata │ ← Threads API (text publish)
│     - Schedule advisory │
│     - Write Publish MD  │
│     - Execute (gated)   │
└─────────────────────────┘

Phase 4: Publishing (Human-Gated)

1. Review outputs in outputs/<task_name>_<date>/ folder
2. Check Supabase — files visible in campaign-uploads bucket
3. Review Publish <task_name> <date>.md — contains all URLs, copy, metadata, schedule
4. Approve with explicit confirmation prompt
5. pipeline/publish_now.js executes API calls to YouTube, Instagram, Threads

---

6. Knowledge File Contents

brand_identity.md (128 lines)

• Brand personality: Bold, witty, unapologetically premium
• Core traits: Playful & witty, Approachable & casual, Premium without pretension, Lightly humorous
• Tone & Voice table:
  • Register: Casual — write like a human, not a press release
  • Energy: Upbeat, punchy, forward-moving
  • Humor: Light and occasional; never forced
  • Confidence: Speak with conviction; avoid hedging
  • Length: Short sentences. Short paragraphs. White space is your friend.
• Example good copy: "Your 5AM just got a serious upgrade."
• Emoji usage, hashtag strategy, CTA patterns

platform_guidelines.md (142 lines)

• Platform overview table: Instagram, Threads, YouTube
• Instagram specs: Feed 1080x1080 (1:1), Story 1080x1920 (9:16), Reel Cover 1080x1920
• Instagram captions: 1-3 sentences, structure: Hook + Value/Vibe + CTA + line break + Hashtags
• Approved hashtags: #ColdBrewCoffee #ColdBrew #MorningGoal #BrewDifferent #CoffeeCulture
• Threads specs: Text only (images optional), 500 char max, witty/casual, no hard CTA required
• YouTube specs: Long & short video, informative/energetic/premium tone, tags in description

product_campaign.md (199 lines)

• Product: Cold Brew Coffee, ready-to-drink format
• Target audience: Busy professionals, coffee enthusiasts, morning routine seekers
• Brand positioning: Premium coffee experience, accessible at home
• Product features table with descriptions
• Campaign creative direction, visual asset references

---

7. CLAUDE.md Contents

# Project Overview

This project implements an "AI-powered Social Media Content Automation System"
built with Claude Code inside the Antigravity IDE.

The system uses specialized AI agents to generate, render, and distribute
marketing content for a demo brand.

The demo brand used in this project is "Cold Brew Coffee Co."

# System Architecture

The system consists of agents:

1. "Video Ad Agent"
2. "Image Ad Agent"
3. "Distribution Agent"
(Later expanded to include Research Agent and Copywriter Agent)

Each agent uses a combination of "custom skills, knowledge files, and APIs"
to perform its tasks.

# Agents and Responsibilities

## 1. Video Ad Agent
Purpose: Generate short-form video advertisements using "Remotion".
Skills Used:
- Remotion Best Practices (official skill)
- Video Ad Specialist (custom skill)

(Additional agents documented similarly)

Note: The CLAUDE.md starts with 3 agents declared and is updated as more are built throughout the video.

---

8. Ultimate Claude Skills & Plugins Prompt.md (601 lines)

This is the meta-framework used to create all 5 agent skills. Key sections:

Skill folder structure:

your-skill-name/
├── SKILL.md        # REQUIRED. The brain of the skill.
├── scripts/        # Optional. Executable Python/Bash code.
├── references/     # Optional. Docs Claude loads when needed.
└── assets/         # Optional. Templates, fonts, icons.

Three-level progressive disclosure:

Level	What	When Loaded	Token Cost
1	YAML frontmatter (name + description)	Always, every conversation	~100 words
2	SKILL.md body (full instructions)	When Claude decides skill is relevant	~500 lines ideal
3	Bundled files in scripts/references/assets/	Only when explicitly needed	Unlimited

YAML frontmatter rules:

• No underscores in names (kebab-case only)
• Cannot start with claude or anthropic (reserved)
• Description must include WHAT + WHEN + trigger phrases
• No XML angle brackets < > in frontmatter (security)
• Max 1024 characters for description
• Be "pushy" — Claude tends to under-trigger

Description formula:

[What it does] + [When to use it] + [Specific trigger phrases] + [File types if relevant]

Required sections in SKILL.md body:

• When to Use This Skill
• CRITICAL: Before Generating — Read Knowledge Files
• Step-by-step workflow
• Troubleshooting
• Quality Checklist

Cheat sheet rules:

• File MUST be named SKILL.md (not SKILL.MD or skill.md)
• Test three things: Triggering + Functionality + Performance
• Use progressive disclosure (short SKILL.md + references/ for deep docs)

---

9. Job Payload Format (Pipeline Input)

The pipeline is triggered by a JSON job payload containing:

{
  "task_name": "test_job_payload_1",
  "task_date": "2026-03-15",
  "purpose": "Full pipeline execution test",
  "pipeline_execution_rules": {
    "execution_order": ["research", "static_ad", "video_ad", "copywriting", "Distribution"]
  },
  "platform_targets": ["Instagram", "YouTube"],
  "output_folder": "outputs/test_job_payload_1_20260315",
  "safety_flags": {
    "dry_run": true,
    "simulate_uploads": true,
    "publish_immediately": false
  },
  "completion_checklist": [
    "Research outputs saved: research_results.json, research_brief.md, interactive_report.html",
    "Static ad outputs saved: ad_layout.json, ad.html, styles.css, instagram_ad.png",
    "Video ad outputs saved: scene_plan.json, video_ad.mp4",
    "Copy outputs saved: instagram_caption.txt, threads_post.txt, youtube_metadata.json",
    "Distribution outputs saved: media_urls.json, Publish MD"
  ]
}

---

10. Supabase Configuration

• Project: "marketing system" (FREE tier)
• Region: Southeast Asia (Singapore), ap-southeast-1, t4g.nano
• URL: https://zpthrcqdcmueifnqyvgh.supabase.co
• Storage bucket: campaign-uploads (PUBLIC)
  • No file size restriction (default 50MB)
  • Any MIME type allowed
  • Public = allows YouTube/Instagram APIs to reach uploaded files
• Auth: Service role key (not anon key) — no user session in server-side pipeline
• File naming: {task_name}_{date}_{filename}_{timestamp}.{ext}

---

11. Pipeline Execution Metrics

Phase	Duration
Skill creation (each)	~47s - 1m 29s
Pipeline planning	2m 25s
Full pipeline execution	8m 41s
Publishing to all platforms	1m 4s

---

12. Published Output Examples

• YouTube: https://www.youtube.com/watch?v=5dQerc75vC4 — "Upgrade Your Morning with Cold Brew Coffee | Cold Brew Coffee Co."
• Instagram: Post ID 18895081516880196 on @proxa_official
• Threads: Post ID 17951637362078664

---

13. Partially Visible / Flagged Items

1. Steps 3-6 of ad-creative-designer — not fully visible in frames; appear to handle JSON layout generation, color/typography selection, and element positioning
2. platform_guidelines.md YouTube section — the YouTube-specific formatting rules were cut off after the Threads section
3. CLAUDE.md full contents — only the top ~30 lines and system architecture section were visible; the complete file likely has more agent documentation
4. NanoBanana MCP configuration — referenced as the image generation tool but setup/API details not shown
5. pipeline/publish_now.js — the actual Node.js publishing script contents were not shown, only its execution
6. Threads API setup — mentioned as having "no public API" in some frames but was successfully published to in the final demo (ID: 17951637362078664)
7. 24-page PDF document — "Agent Skills Key Details and Description" was shown briefly; only pages 1-2 and 8 were readable. Contains detailed specs for all skills
8. Google Antigravity AI Chat — used for individual agent testing to save Claude Code tokens; appears to be an alternative AI IDE/chat tool
9. Remotion Best Practices — referenced as an "official" / "globally installed" Claude skill but its contents were not shown
10. BullMQ + Redis integration — mentioned as optional extension for automated queuing but not implemented in the demo