Files

T

Trey t 3abe46fba6 feat: scaffold Next.js 15 project with TypeScript and Tailwind

2026-03-23 11:51:32 -05:00

30 KiB

Raw Permalink Blame History

Best Practices Guide: Building an AI Marketing Pipeline with Claude Code

Purpose: A comprehensive reference for building a multi-agent marketing content system using Claude Code skills. Synthesized from the AndyNoCode video analysis, official Anthropic documentation, open-source projects, and industry best practices.

Architecture Overview
Project Structure & CLAUDE.md
Knowledge Files — The Brand Brain
Skill Authoring Best Practices
Agent Design — The 5-Agent Pipeline
Tool Integrations & Setup
Inter-Agent Communication
Publishing & Distribution
Testing & Iteration
Cost Optimization
Security & Secrets Management
Alternative Frameworks & Comparisons
Key Resources & Sources

1. Architecture Overview

The Pipeline Pattern

The most effective architecture for AI marketing systems is a sequential pipeline where each agent has a single responsibility and passes structured output to the next:

Research → Creative (Static + Video) → Copy → Distribution

This maps to the "Pipeline/Sequential" multi-agent pattern documented across industry best practices. Each agent:

Has a dedicated SKILL.md defining its behavior
Reads from shared knowledge files for brand consistency
Outputs machine-readable structured data (JSON) for downstream agents
Operates within a gate-protected publishing workflow

Why Claude Code Skills (vs. Other Frameworks)

Approach	Strengths	Weaknesses
Claude Code Skills	Native integration, progressive disclosure, low overhead, SKILL.md standard works across tools	Tied to Claude ecosystem, token-based costs
CrewAI	Python-native, good for complex delegation, 600+ inbound leads case study	Heavier setup, separate runtime
LangGraph	Flexible graph-based orchestration, good for complex routing	More complex, steeper learning curve
AutoGen	Multi-model support, conversation-based	More enterprise-focused, complex config

Recommendation: For a marketing pipeline, Claude Code skills offer the simplest path because the skills are just markdown files, they load progressively (saving tokens), and they integrate directly with the IDE and terminal. Use CrewAI or LangGraph if you need more complex agent delegation patterns or multi-model support.

2. Project Structure & CLAUDE.md

Recommended Folder Structure

your-brand/
├── .claude/                          # Claude Code configuration
├── assets/                           # Creative references (mood board)
│   ├── logo.png
│   ├── product-hero.png
│   └── lifestyle-shots/
├── knowledge/                        # Brand brain — the 3 essential files
│   ├── brand_identity.md
│   ├── platform_guidelines.md
│   └── product_campaign.md
├── outputs/                          # All generated content (per-campaign)
│   └── {task_name}_{date}/
│       ├── ads/
│       ├── copy/
│       ├── video/
│       └── Publish {task_name} {date}.md
├── pipeline/                         # Automation scripts
│   └── publish_now.js
├── remotion-ad/                      # Remotion video project
│   ├── src/
│   └── package.json
├── skills/                           # All agent skills
│   ├── marketing-research-agent/
│   │   └── SKILL.md
│   ├── ad-creative-designer/
│   │   └── SKILL.md
│   ├── video-ad-specialist/
│   │   └── SKILL.md
│   ├── copywriter-agent/
│   │   └── SKILL.md
│   └── distribution-agent/
│       └── SKILL.md
├── .env                              # Real API keys (gitignored)
├── .env.example                      # Template for collaborators
├── .gitignore
├── CLAUDE.md                         # Project source of truth
├── package.json
└── Ultimate Claude Skills & Plugins Prompt.md  # Skill creation framework

CLAUDE.md — The Source of Truth

Your CLAUDE.md is the most important file. It tells Claude what the project is, how folders are structured, what files are available, and what rules to follow. Without it, Claude is just guessing.

Best practices from official docs:

A well-structured CLAUDE.md with module boundaries reduces per-agent exploration costs significantly
Include a sub-agent routing decision framework specifying when to use parallel vs. sequential dispatch
Keep it focused — don't duplicate what's in knowledge files

Recommended CLAUDE.md structure:

# Project Overview
This project implements an AI-powered Social Media Content Automation System.
The system uses five specialized AI agents to research, generate, render, and
distribute marketing content for [YOUR BRAND].

# System Architecture
Five agents running in sequence:
1. Marketing Research Agent — web research via Tavily
2. Ad Creative Designer — static ads via NanoBanana + Playwright
3. Video Ad Specialist — video ads via Remotion
4. Copywriter Agent — platform-specific copy
5. Distribution Agent — Supabase upload + API publishing

# Folder Structure
- assets/ — brand images, logos, product shots (mood board)
- knowledge/ — brand identity, platform guidelines, product/campaign info
- skills/ — all 5 agent skills (each has SKILL.md)
- outputs/ — generated content per campaign
- pipeline/ — publishing automation scripts
- remotion-ad/ — Remotion video project

# Knowledge Files (READ FIRST)
Every agent MUST read these before generating ANY content:
- knowledge/brand_identity.md — tone, voice, personality, CTA patterns
- knowledge/platform_guidelines.md — per-platform specs and formatting
- knowledge/product_campaign.md — product details, features, campaign direction

# Pipeline Execution Order
research → static_ad → video_ad → copywriting → distribution

# Output Convention
outputs/{task_name}_{YYYYMMDD}/
  ├── ads/ (static ad files)
  ├── copy/ (platform-specific copy)
  ├── video/ (Remotion output)
  └── Publish {task_name} {date}.md

# Safety Rules
- No live API posting without explicit user approval
- Distribution agent uses gate-protected publishing
- All media must be uploaded to Supabase before Instagram API calls

3. Knowledge Files — The Brand Brain

Why This Matters

The #1 differentiator between generic AI output and on-brand content is knowledge files. Every agent reads these before generating anything. This is the "CRITICAL: Before Generating" pattern used in the AndyNoCode system.

From the official best practices: "Only add context Claude doesn't already have. Challenge each piece: Does Claude really need this explanation?"

brand_identity.md (~100-150 lines)

Purpose: Personality, tone, voice, CTA patterns, emoji/hashtag strategy.

Template structure:

# Brand Identity: [Your Brand]

## 1. Brand Personality
[2-3 sentences defining the brand's character]

Core traits:
- [Trait 1 with description]
- [Trait 2]
- [Trait 3]
- [Trait 4]

## 2. Tone & Voice
| Attribute | Guidance |
|-----------|----------|
| Register  | [Casual/Formal/etc.] |
| Energy    | [Upbeat/Measured/etc.] |
| Humor     | [Level and guidelines] |
| Confidence| [How assertive] |
| Length    | [Sentence/paragraph style] |

Write like this: "[Example of good copy]"
Not like this: "[Example of bad copy]"

## 3. CTA Patterns
- Always start CTAs with action verbs
- Approved CTAs: [list]
- Never use: [list]

## 4. Emoji Usage
- Approved emojis: [list with usage context]
- Max per post: [number]

## 5. Hashtag Strategy
- Primary hashtags (always include): [list]
- Secondary (rotate): [list]
- Never use: [list]

platform_guidelines.md (~100-150 lines)

Purpose: Per-platform formatting specs, tone adjustments, dimension requirements.

Template structure:

# Platform Guidelines: [Your Brand]

## 1. Platform Overview
| Platform | Content Type | Primary Tone | Hashtags |
|----------|-------------|--------------|----------|
| Instagram | Image posts, Stories, Reels | [tone] | Required (3-5) |
| YouTube  | Long & short video | [tone] | Via tags/description |
| Threads  | Short text posts | [tone] | Optional |

## 2. Instagram
### Specs
| Format | Dimensions | Aspect Ratio |
|--------|-----------|--------------|
| Feed Post | 1080x1080 px | 1:1 |
| Story | 1080x1920 px | 9:16 |
| Reel | 1080x1920 px | 9:16 |

### Caption Guidelines
- Length: [rules]
- Structure: Hook + Value + CTA + line break + Hashtags
- Emojis: [rules]

## 3. YouTube
### Specs
[dimensions, thumbnail specs, description format]

### Metadata
- Title format: [pattern]
- Description structure: [pattern]
- Tags: [strategy]

## 4. Threads
### Specs
- Text only (images optional), 500 char max
### Tone
- Most conversational platform — witty, punchy

product_campaign.md (~150-200 lines)

Purpose: Product details, selling points, visual references, campaign direction.

# Product & Campaign Knowledge: [Your Brand]

## 1. Product Overview
| Attribute | Details |
|-----------|---------|
| Product Name | [name] |
| Format | [type] |
| Target Audience | [segments] |
| Brand Positioning | [statement] |

## 2. Product Features
[Table of features with descriptions — the "product truths" all content must reference]

## 3. Campaign Direction
[Current campaign goals, messaging themes, visual direction]

## 4. Visual Asset References
[List of available assets in assets/ folder and when to use each]

4. Skill Authoring Best Practices

Official Anthropic Guidelines (Key Points)

From the official skill authoring docs:

Concise is key — The context window is a shared resource. Only add what Claude doesn't already know.
Keep SKILL.md under 500 lines — Move detailed reference to separate files.
Description is critical — Claude decides whether to load a skill based ONLY on the description. Write in third person. Include what it does AND when to use it AND trigger phrases.
Max 1024 characters for description field.
Progressive disclosure — Metadata (always loaded, ~100 words) → SKILL.md body (loaded when relevant) → Supporting files (loaded on demand).
No angle brackets < > in frontmatter (security).
Test with multiple models — What works for Opus may need more detail for Haiku/Sonnet.
Build evaluations BEFORE writing docs — Identify real gaps, don't document imagined ones.

SKILL.md Template for Marketing Agents

---
name: your-agent-name
description: >
  [What it does] + [When to use it] + [Specific trigger phrases].
  Use when the user asks to [action 1], [action 2], or says
  "[trigger phrase 1]", "[trigger phrase 2]", "[trigger phrase 3]".
  Always use this skill when [condition] for [Your Brand].
---

# [Agent Name]

[One-line description of what this agent produces.]

## CRITICAL: Before Generating — Read Knowledge Files

Always reference these files before producing any output:
- knowledge/brand_identity.md — tone, voice, CTA patterns
- knowledge/platform_guidelines.md — platform specs and formatting
- knowledge/product_campaign.md — product features, campaign direction

## Step 1: Gather Inputs

| Input | Example |
|-------|---------|
| [Input 1] | [Example] |
| [Input 2] | [Example] |

If inputs are missing, apply defaults from knowledge files.

## Step 2: [Core Processing]
[Detailed step instructions]

## Step 3: [Generation/Output]
[What to produce and in what format]

## Step 4: [Validation]
[Quality checks before completion]

## Output Convention
All outputs saved to: outputs/{task_name}_{date}/[subfolder]/

## Troubleshooting
- [Common issue 1]: [Solution]
- [Common issue 2]: [Solution]

## Quality Checklist
- [ ] Knowledge files read before generation
- [ ] Output matches brand voice
- [ ] Platform specs followed
- [ ] Files saved to correct output path
- [ ] Handoff summary provided for next agent

The "Ultimate Skills Framework" Approach

The video uses a 601-line "Ultimate Claude Skills & Plugins Prompt.md" as the meta-framework for creating all skills. Key elements:

Plan first with Claude — Use Claude chat (Sonnet is fine) to brainstorm skill details via interactive Q&A
Draft key details — Purpose, inputs, outputs, workflow, trigger phrases
Build in Claude Code — "Help me create an agent skill. Use @'Ultimate Skills Prompt.md' to create it. Key details: [paste]"
Claude builds the SKILL.md following the framework
Test individually before connecting to the pipeline

5. Agent Design — The 5-Agent Pipeline

Agent 1: Marketing Research Agent

Property	Value
SKILL.md	~146 lines
Tool	Tavily AI (`@tavily/core`)
Input	Niche/topic, audience, campaign goal
Output	`research_results.json`, `research_brief.md`, `interactive_report.html`

5 Tavily queries: trends, competitors, pain points, ad hooks, viral content

Output JSON structure:

{
  "content_topics": [...],
  "marketing_angles": [...],
  "keywords": [...],
  "video_concepts": [...],
  "ad_hooks": [...]
}

Best practice: The video_concepts objects should map directly to the Video Ad Specialist's input format. Design your inter-agent JSON schema upfront.

Agent 2: Ad Creative Designer

Property	Value
SKILL.md	~191-331 lines
Tools	NanoBanana MCP (image gen) + Playwright (screenshot)
Input	Campaign brief, brand assets
Output	`ad_layout.json`, `ad.html`, `styles.css`, `instagram_ad.png`

Three-step workflow: Generate → Design → Capture

Call NanoBanana MCP to generate images using brand knowledge as reference
Design HTML/CSS layout (1080x1080 for Instagram, with typography scale: 72px headline, 36px subtext, 12px CTA)
Launch Playwright headless Chromium → screenshot at exact dimensions → save as PNG

Layout types: Product Focus, Split, Lifestyle

Copy constraints: Headline 3-4 words, CTA starts with action verb, Stories safe zone (no text in top/bottom 15%)

Agent 3: Video Ad Specialist

Property	Value
SKILL.md	~167 lines
Tools	Remotion (wraps official skill)
Input	Product info, campaign objective, platform, length
Output	`scene_plan.json`, `video_ad.mp4`

Key design: This skill wraps around the Remotion Best Practices official skill. The Remotion skill handles the technical craft; this skill handles brand strategy.

Strategy types: product_showcase, problem_solution, testimonial, limited_offer, lifestyle, meme_style

Auto-render: Built-in render script — finished video goes straight to outputs folder without manual Remotion Studio steps.

Agent 4: Copywriter Agent

Property	Value
SKILL.md	~261 lines
Tools	Knowledge files only
Input	Research results, campaign brief
Output	`instagram_caption.txt`, `threads_post.txt`, `youtube_metadata.json`, `copy_output.json`

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

Agent 5: Distribution Agent

Property	Value
SKILL.md	~352 lines
Tools	Supabase, YouTube API, Instagram API, Threads API
Input	All outputs from previous agents
Output	`media_urls.json`, `Publish {task_name} {date}.md`

6-step workflow:

Gather inputs from campaign folder
Upload media to Supabase (campaign-uploads bucket)
Assemble metadata from copywriter output
Generate scheduling advisory
Write Publish MD manifest
Execute publishing (gate-protected — requires explicit user approval)

6. Tool Integrations & Setup

Tavily AI — Web Research

Package: npm install @tavily/core (v0.7.2+)
Pricing: 1,000 free API credits/month, no credit card required
Docs: https://docs.tavily.com
GitHub: https://github.com/tavily-ai/tavily-js
Setup: Get API key from dashboard → add to .env as TAVILY_API_KEY

NanoBanana MCP — Image Generation

What: MCP server powered by Google Gemini (Nano Banana 2 / Pro) for AI image generation
Cost: ~$0.04-0.05/image (standard), ~$0.13/image (Pro/2K)
GitHub: https://github.com/YCSE/nanobanana-mcp
Setup: Configure as MCP server in Claude Code settings
Key detail: Works inside Claude conversations — Claude crafts prompts and generates images directly

Remotion — Programmatic Video

Official Claude Skill: Install via Claude Code skill marketplace
Docs: https://www.remotion.dev/docs/ai/claude-code
Key APIs: useCurrentFrame, interpolate, spring, <Series.Sequence>
Auto-render: Build render script into your skill so videos go straight to output folder
Kickstart repo: https://github.com/jhartquist/claude-remotion-kickstart

Playwright — HTML to PNG

Package: npm install playwright
Docs: https://playwright.dev/docs/screenshots

Key pattern:

const browser = await chromium.launch();
const page = await browser.newPage();
await page.setViewportSize({ width: 1080, height: 1080 });
await page.goto(`file://${path}`, { waitUntil: 'networkidle' });
await page.screenshot({ path: 'output.png', clip: { x: 0, y: 0, width: 1080, height: 1080 } });

Supabase Storage — Media Hosting

Why needed: Instagram API requires media at publicly accessible URLs (local files won't work)
Bucket: Create campaign-uploads as PUBLIC bucket
Auth: Use service role key (not anon key) — no user session in server-side pipeline
File naming: {task_name}_{date}_{filename}_{timestamp}.{ext}
Docs: https://supabase.com/docs/guides/storage

YouTube Data API v3

Setup: Google Cloud Console → enable YouTube Data API v3 → create OAuth 2.0 credentials
4 env vars: YOUTUBE_API_KEY (read-only), YOUTUBE_CLIENT_ID, YOUTUBE_CLIENT_SECRET, YOUTUBE_REFRESH_TOKEN
Upload method: youtube.videos.insert() via googleapis npm package
Docs: https://developers.google.com/youtube/v3/quickstart/nodejs

Instagram Graph API

Flow: Create container → wait for FINISHED status → publish container
Permissions: instagram_business_basic + instagram_business_content_publish
Token expiry: Long-lived tokens expire after 60 days — implement refresh logic
Requirement: Only Business/Creator accounts (Personal not supported)
Rate limit: 200 requests/hour/account
Docs: https://developers.facebook.com/docs/instagram-platform

Threads API

Status: Fully available since June 2024, enhanced July 2025 with polls/location/webhooks
Endpoints: /v1.0/{user_id}/threads (create) → /v1.0/{user_id}/threads_publish (publish)
2026 additions: GIF support (Feb 2026), oEmbed without token (Mar 2026)
Docs: https://developers.facebook.com/docs/threads/posts/

7. Inter-Agent Communication

JSON as the Handoff Protocol

Critical insight from industry research: Most "agent failures" are orchestration and context-transfer issues at handoff points, not model capability failures.

Best practice: Design your inter-agent JSON schema upfront. Each agent outputs structured data that downstream agents consume directly — no reformatting needed.

Research Agent → research_results.json
  ↓ consumed by
Ad Creative Designer (reads marketing_angles, ad_hooks)
Video Ad Specialist (reads video_concepts — maps directly to input format)
Copywriter Agent (reads content_topics, keywords, marketing_angles)
  ↓ all outputs consumed by
Distribution Agent (reads media files + copy outputs)

The Job Payload Pattern

Trigger the entire pipeline with a single JSON payload:

{
  "task_name": "spring_campaign_2026",
  "task_date": "2026-03-22",
  "brand": "Your Brand",
  "campaign_goal": "Product launch awareness",
  "execution_order": ["research", "static_ad", "video_ad", "copywriting", "distribution"],
  "platform_targets": ["Instagram", "YouTube", "Threads"],
  "output_folder": "outputs/spring_campaign_2026_20260322",
  "safety_flags": {
    "dry_run": false,
    "simulate_uploads": false,
    "publish_immediately": false
  }
}

8. Publishing & Distribution

The Gate-Protected Publishing Pattern

Never auto-publish. The distribution agent generates a Publish MD manifest with:

Public URLs for all media (from Supabase)
Platform-specific copy (from copywriter)
Metadata (titles, descriptions, tags)
Scheduling recommendations
A checklist for human review

Only publish when the user explicitly approves by naming the Publish MD file.

Instagram Two-Step Flow

// Step 1: Create container
const container = await createMediaContainer({
  image_url: supabasePublicUrl,
  caption: caption,
  access_token: process.env.INSTAGRAM_ACCESS_TOKEN
});

// Step 2: Wait for FINISHED status, then publish
await publishContainer(container.id);

Supabase as the Media Bridge

Instagram's API cannot read local files. The pipeline:

Agent generates media locally
Distribution agent uploads to Supabase public bucket
Gets back public URL
Passes public URL to Instagram/YouTube APIs

9. Testing & Iteration

Test Individually First

From the video: test each agent in isolation before running the full pipeline. Use a cheaper model/tool for individual tests to save tokens:

Research agent: test with a simple niche query
Ad creative: test with minimal JSON inputs
Video: test with a basic 5-scene prompt
Copywriter: test with sample research output
Distribution: test in dry-run mode (simulate_uploads: true)

Evaluation-Driven Development

From official Anthropic best practices:

Run Claude on representative tasks WITHOUT a skill — document failures
Create 3+ evaluation scenarios testing those gaps
Measure baseline performance
Write minimal SKILL.md content to address gaps
Iterate: execute evals, compare to baseline, refine

The Two-Claude Pattern

Work with "Claude A" to create/refine skills, test with "Claude B" (fresh instance):

Complete task with Claude A using normal prompting
Identify reusable pattern
Ask Claude A to create a skill
Test with Claude B on similar tasks
Bring observations back to Claude A for refinement

10. Cost Optimization

Token Management

Use Sonnet 4.6 for skill creation — "not a complex task, don't need Opus"
Test individual agents outside Claude Code — use Claude.ai or alternative tools for isolated tests
Progressive disclosure saves tokens — only skill descriptions are always loaded (~100 words each), full SKILL.md only loads when relevant
Agent Teams multiply tokens linearly — 3 parallel agents ≈ 3-4x tokens of solo session
Keep SKILL.md under 500 lines — move reference material to separate files

Cost Estimates

Tavily: Free tier = 1,000 credits/month
NanoBanana: ~$0.04-0.13/image
Supabase: Free tier includes 1GB storage
YouTube/Instagram/Threads APIs: Free (with rate limits)
Claude Code: Pro subscription + token usage per pipeline run

11. Security & Secrets Management

Environment Variables

# .gitignore
.env
node_modules/

# .env.example (safe to commit)
TAVILY_API_KEY=tvly-YOUR_API_KEY
YOUTUBE_API_KEY=YOUR_KEY
YOUTUBE_CLIENT_ID=YOUR_ID
YOUTUBE_CLIENT_SECRET=YOUR_SECRET
YOUTUBE_REFRESH_TOKEN=YOUR_TOKEN
INSTAGRAM_ACCOUNT_ID=YOUR_ID
INSTAGRAM_ACCESS_TOKEN=YOUR_TOKEN
SUPABASE_URL=YOUR_URL
SUPABASE_SERVICE_ROLE_KEY=YOUR_KEY

Supabase Service Role Key

Use service role key for server-side automation (no user session)
Never expose client-side — bypasses Row Level Security
If you add a frontend later, switch to anon key + RLS policies

Instagram Token Refresh

Long-lived tokens expire after 60 days
Implement automated refresh before expiry
Store refresh timestamps and alert when approaching expiry

12. Alternative Frameworks & Comparisons

Pre-Built Marketing Skills

marketingskills — 35+ marketing skills for Claude Code covering CRO, copywriting, SEO, analytics, growth engineering. Install: npx skills add coreyhaines31/marketingskills
claude-skills — 192+ skills for Claude Code covering engineering, marketing, product, compliance
awesome-agent-skills — 500+ curated skills from official dev teams and community

CrewAI Alternative

CrewAI offers a Python-based multi-agent framework with similar capabilities:

6 specialized agents (Researcher, Writer, Editor, SEO Specialist, etc.)
Autonomous collaboration with delegation
70% reduction in content production time
Built-in Ghost CMS integration for auto-publishing

Best for: Python-native teams, complex delegation patterns, when you need agents to delegate back to each other.

Video Generation Alternatives

Claude-Code-Video-Toolkit — Skills, MCP servers, and tools for video production covering Remotion, Manim, screen recording, YouTube clipping, FFmpeg
claude-remotion-kickstart — Starter project for Claude Code + Remotion
remotion-video-skill — Community Claude Code skill for Remotion

13. Key Resources & Sources

Official Documentation

Claude Code Skills Docs — complete skill creation reference
Skill Authoring Best Practices — official Anthropic guide
The Complete Guide to Building Skills for Claude (PDF) — Anthropic's comprehensive guide
Agent Skills Overview — conceptual background
Anthropic Official Skills Repo — including skill-creator skill
Agent Teams Docs — multi-agent orchestration

Skill Marketplaces & Collections

awesome-agent-skills — 500+ curated skills
awesome-claude-skills — curated list with resources
SkillsMP — Agent Skills marketplace
SkillHub — Claude Skills marketplace
marketingskills — 35+ marketing-specific skills

Tool Documentation

Remotion + Claude Code — official integration guide
Remotion Agent Skills — skill marketplace listing
Tavily JS SDK — web research API
Tavily Docs — full API reference
NanoBanana MCP — Gemini-powered image generation
Playwright Screenshots — HTML-to-image guide
Supabase Storage — file hosting
Instagram Graph API — content publishing
YouTube Data API v3 — Node.js quickstart
Threads API — posting endpoint

Guide compiled March 2026. Verify all URLs and API versions before implementation.

30 KiB Raw Permalink Blame History