marketing-os-starter

# Marketing OS Starter > Skill by [ara.so](https://ara.so) — Marketing Skills collection. ## What It Does Marketing OS Starter is a complete AI marketing team built for Claude Code. It includes 4 specialized agents (Orchestrator, Researcher, Strategist, Copywriter), 5 marketing skills, and battle-tested frameworks that turn research into creative briefs into finished copy — all with persistent memory that compounds across sessions. The system runs on structured agent handoffs (JSON schemas), enforces brand voice automatically, and applies proven frameworks like the 6 Hook Formulas and BOFU Domination to every piece of output. ## Installation ```bash # Clone the repository git clone https://github.com/ericosiu/marketing-os-starter.git my-marketing-os cd my-marketing-os ``` The project structure: ``` marketing-os-starter/ ├── CLAUDE.md # Main context file - your agency priorities ├── .claude/ │ ├── agents/marketing-os/ # 4 specialist agents │ │ ├── orchestrator.md │ │ ├── researcher.md │ │ ├── strategist.md │ │ └── copywriter.md │ ├── skills/ # 5 marketing skills │ │ ├── research.md │ │ ├── campaign-brief.md │ │ ├── copywriting.md │ │ ├── social-content.md │ │ └── email-sequence.md │ └── rules/ # Intent routing │ └── proactive-marketing.md ├── brands/ # Agency + client brand files │ └── your-agency/ │ ├── BRAND.md │ ├── voice.md │ └── clients/ ├── memory/ # Persistent memory │ └── marketing-os/ │ ├── brand-voice.md │ ├── campaign-history.md │ ├── marketing-wisdom.md │ └── working.md ├── schemas/ # JSON contracts for handoffs │ ├── audience-profile.json │ ├── creative-brief.json │ └── copy-deliverable.json └── examples/ # Sample outputs ``` ## Initial Configuration ### 1. Configure CLAUDE.md This is the brain of your system. Claude reads it at the start of every session. ```markdown # Your Agency Context **Agency**: [Your Agency Name] **Primary Service**: [What you do] ## Priorities (Next 12 Months) 1. [Priority 1] 2. [Priority 2] 3. [Priority 3] ## Standards **Minimum ROI Bar**: [X]x ROAS or [Y]% conversion lift **Never Accept**: "Awareness" campaigns without revenue tracking ## Client Portfolio - **[Client Name]**: [Brief description] - **[Client Name]**: [Brief description] ``` ### 2. Set Up Your Agency Brand Edit `brands/your-agency/BRAND.md`: ```markdown # [Your Agency Name] ## Overview [2-3 sentence value proposition] ## What We Do - [Service 1] - [Service 2] - [Service 3] ## Public Client Examples - [Client success story 1] - [Client success story 2] ``` Edit `brands/your-agency/voice.md`: ```markdown # Voice Guidelines ## Tone - Direct and data-driven - No jargon or corporate speak - Numbers over adjectives ## Always Use - Specific metrics (e.g., "3.4x ROI" not "great results") - Active voice - Short sentences ## Never Use - leverage, synergize, value-add, paradigm - "excited to announce" - Corporate platitudes ## Examples That Nail Our Voice ### Good "We cut their CAC from $847 to $312 in 6 weeks. Here's the breakdown." ### Bad "We're excited to share that our innovative approach helped drive meaningful results." ``` ### 3. Add Your First Client Copy the example client template: ```bash cp -r brands/your-agency/clients/example-client brands/your-agency/clients/acme-corp ``` Edit `brands/your-agency/clients/acme-corp/BRAND.md`: ```markdown # Acme Corp ## Company Overview - **Industry**: [SaaS/E-commerce/etc] - **Target Market**: [B2B/B2C, company size, role] - **Product**: [What they sell] ## Voice [How this specific client speaks - may differ from agency voice] ## Past Campaigns None yet. ``` ## Key Commands and Workflows ### Running a Complete Campaign Pipeline Start Claude Code and describe your need naturally: ``` "I need to promote Acme Corp's new analytics feature to marketing directors at B2B SaaS companies. Budget $5K, 45-day timeline." ``` The Orchestrator will automatically: 1. Invoke **Researcher** → produces `audience-profile.json` 2. Invoke **Strategist** → produces `creative-brief.json` 3. Invoke **Copywriter** → produces finished copy ### Manual Skill Invocation You can also call skills directly: ``` /research Target audience: Marketing directors at B2B SaaS companies (50-500 employees) Focus: Pain points around marketing attribution ``` ``` /campaign-brief Audience: [reference research output] Goal: 30 demo requests Timeline: 45 days Budget: $5K ``` ``` /copywriting Brief: [reference brief output] Deliverables: 5 LinkedIn posts, 1 landing page hero ``` ``` /social-content Topic: Marketing attribution mistakes Platform: LinkedIn Quantity: 5 posts Target: Marketing directors ``` ``` /email-sequence Type: Nurture sequence Segment: Ghost users (signed up, 0 actions) Length: 5 emails over 2 weeks Goal: First dashboard connection ``` ## Agent Handoff Pattern Agents communicate through structured JSON. Example flow: **Researcher Output** (`memory/marketing-os/campaigns/acme-q2/audience-profile.json`): ```json { "target_audience": { "role": "Marketing Director", "company_size": "50-500 employees", "industry": "B2B SaaS" }, "pain_points": [ { "pain": "Attribution reporting takes 2-3 days to compile", "evidence": "14 Reddit posts in r/marketing, 23 G2 reviews", "quote": "I spend more time building reports than reading them" } ], "voice_of_customer": { "actual_phrases": [ "I spend more time building reports than reading them", "My CEO thinks marketing is a cost center because I can't prove otherwise" ] } } ``` **Strategist Reads** the audience profile and outputs (`creative-brief.json`): ```json { "campaign_name": "Acme Attribution Fix", "core_message": "Stop spending 2 days building reports. See real-time attribution in 15 minutes.", "proof_points": [ "14 Reddit posts confirm this pain point", "Average time saved: 2.3 days per month" ], "growth_playbook": "Playbook 6: Marketing Mistakes Content", "hook_formula": "Harsh Reality", "deliverables": { "landing_page_hero": 1, "linkedin_posts": 5, "email_sequence": 3 } } ``` **Copywriter Reads** the brief and produces final copy with the selected hook formula applied. ## Working with Memory Files ### Campaign History After each campaign, the Strategist logs results to `memory/marketing-os/campaign-history.md`: ```markdown ## Campaign: Acme Attribution Fix - **Date**: 2026-05-15 - **Channel**: LinkedIn + Landing Page - **Result**: 47 demo requests, 12 closed deals - **What Worked**: "Harsh Reality" hook + specific time-saved stat - **What Didn't**: Generic "learn more" CTA underperformed vs "See your attribution now" ``` This memory prevents repeating failed approaches and reinforces what works. ### Brand Voice Evolution As you approve copy, add winning examples to `memory/marketing-os/brand-voice.md`: ```markdown ## Approved Headlines (2026-05) ### Hook: Harsh Reality "Harsh reality: your marketing attribution is lying to you." - **Campaign**: Acme Q2 - **Performance**: 8.2% CTR (2.3x average) ### Hook: Contrarian Challenge "Everyone says 'just pick an attribution model.' That's surface-level thinking." - **Campaign**: Acme Q2 - **Performance**: 6.7% CTR ``` After 5-10 campaigns, the Copywriter matches your voice without explicit direction. ### Task Queue `memory/marketing-os/working.md` tracks the current pipeline: ```markdown # Current Tasks ## In Progress - [ ] Acme Q2 Campaign - waiting for client approval on headlines - [ ] Research for DataPulse competitive analysis ## Blocked - [ ] Email sequence for Acme - need segment data from client ## Completed This Week - [x] Landing page copy for Acme Attribution Fix - [x] 5 LinkedIn posts for Acme Q2 ``` You can resume exactly where you left off in any session. ## Real Usage Examples ### Example 1: Full Campaign from Scratch ``` User: "Build a campaign to get 30 demo requests for Acme's new attribution feature. Target marketing directors at B2B SaaS companies, budget $5K, 45 days." Orchestrator: Detecting new campaign request. Invoking full pipeline. [Researcher produces audience-profile.json with 87 data points] Strategist: Reading audience profile... Core pain point identified: "2-3 days per month wasted on attribution reports." [Strategist produces creative-brief.json selecting Growth Playbook #6 and Harsh Reality hook] Copywriter: Reading creative brief... Applying Harsh Reality hook formula. [Copywriter produces 5 LinkedIn posts, 1 landing page hero, 3-email sequence] Orchestrator: Campaign deliverables ready. Files saved to memory/marketing-os/campaigns/acme-q2/. ``` ### Example 2: Research Only ``` User: "Who should we target for a marketing attribution tool?" [Orchestrator detects research intent, invokes Researcher] Researcher: Conducting BOFU-first research... - Analyzing search intent for "best marketing attribution tool" - Scraping G2 reviews for voice-of-customer quotes - Cross-referencing Reddit r/marketing pain points [Produces audience-profile.json with job titles, pain points, actual quotes] ``` ### Example 3: Writing with Existing Brief ``` User: "Write 5 LinkedIn posts using the Acme Q2 brief." [Orchestrator detects copywriting intent with existing brief, invokes Copywriter] Copywriter: Reading brief at memory/marketing-os/campaigns/acme-q2/creative-brief.json... - Hook formula: Harsh Reality - Proof point: "2.3 days saved per month" - Voice check: Loading brands/your-agency/clients/acme-corp/voice.md [Produces 5 posts, each with different hook formula variation] ``` ## Configuration Reference ### Agent Roles | Agent | File | Primary Function | |-------|------|------------------| | Orchestrator | `.claude/agents/marketing-os/orchestrator.md` | Routes requests, tracks pipeline, never writes copy | | Researcher | `.claude/agents/marketing-os/researcher.md` | Produces audience profiles, competitive analysis (BOFU-first) | | Strategist | `.claude/agents/marketing-os/strategist.md` | Creates campaign briefs, matches growth playbooks | | Copywriter | `.claude/agents/marketing-os/copywriter.md` | Writes finished copy using hook formulas | ### Skill Triggers The proactive routing system in `.claude/rules/proactive-marketing.md` auto-detects: - **Research triggers**: "who's our audience", "competitive landscape", "pain points" - **Brief triggers**: "plan a campaign", "what should we say", "strategy" - **Copy triggers**: "write copy", "landing page", "headline" - **Social triggers**: "LinkedIn post", "tweet", "social content" - **Email triggers**: "drip campaign", "welcome sequence", "nurture" ### Framework Reference All frameworks live in `memory/marketing-os/marketing-wisdom.md`: **6 Hook Formulas**: 1. Observation + Stat: "I analyzed 500 landing pages. 89% make the same mistake." 2. Contrarian Challenge: "Everyone says X. That's surface-level thinking." 3. Harsh Reality: "Harsh reality: your approach is costing you $X." 4. Personal Limitation: "I used to believe X. Then I ran the numbers." 5. Social Proof: "I sat in on 12 board meetings. Same scene every time." 6. Simple Declarative: "Your attribution is broken. Here's why." **7 Growth Playbooks** (abbreviated): - Playbook 1: Free Tool Flywheel - Playbook 2: LLM Citation Strategy - Playbook 3: Vertical Domination - Playbook 6: Marketing Mistakes Content (3-5x engagement) - Playbook 7: Data Network Effects ## Common Patterns ### Pattern: Multi-Client Agency Setup ```bash brands/ ├── your-agency/ │ ├── BRAND.md # Your agency brand │ ├── voice.md # Your agency voice │ └── clients/ │ ├── acme-corp/ │ │ ├── BRAND.md │ │ └── voice.md # May differ from agency voice │ ├── techstart/ │ │ ├── BRAND.md │ │ └── voice.md │ └── dataflow/ │ ├── BRAND.md │ └── voice.md ``` When starting a campaign, specify the client: ``` "Build a campaign for Acme Corp's new feature..." ``` The Orchestrator will load `brands/your-agency/clients/acme-corp/` context automatically. ### Pattern: Testing with Example Brand The repo includes a complete fictional agency: ```bash brands/example-agency/ ├── BRAND.md # GrowthLab (fictional agency) ├── voice.md └── clients/ └── datapulse/ # DataPulse (fictional SaaS client) ├── BRAND.md └── voice.md ``` Test the full pipeline before setting up your own brand: ``` "Build a campaign for DataPulse targeting marketing directors at mid-market SaaS companies." ``` ### Pattern: Voice Evolution Loop 1. **Generate copy** with current voice guidelines 2. **Review and edit** to match your actual voice 3. **Log approved examples** to `memory/marketing-os/brand-voice.md` 4. **Repeat** — the Copywriter learns from approved examples After 5-10 campaigns, the voice matching becomes automatic. ## Troubleshooting ### Issue: Generic output despite brand voice file **Problem**: Copy doesn't match your voice, sounds generic. **Solution**: 1. Check `brands/your-agency/voice.md` has specific examples (not just rules) 2. Add 2-3 "Good vs Bad" examples showing your voice clearly 3. Add winning headlines to `memory/marketing-os/brand-voice.md` ```markdown ## Examples That Nail Our Voice ### Good "We cut their CAC from $847 to $312 in 6 weeks. Here's the breakdown." ### Bad "We're excited to share that our innovative approach helped drive meaningful results." ``` ### Issue: Agent doesn't invoke the right skill **Problem**: You ask for research but get copy instead. **Solution**: The proactive routing in `.claude/rules/proactive-marketing.md` may need more trigger phrases. Add your common phrasing: