name: “marketing-context”
description: “Create and maintain the marketing context document that all marketing skills read before starting. Use when the user mentions ‘marketing context,’ ‘brand voice,’ ‘set up context,’ ‘target audience,’ ‘ICP,’ ‘style guide,’ ‘who is my customer,’ ‘positioning,’ or wants to avoid repeating foundational information across marketing tasks. Run this at the start of any new project before using other marketing skills.”
license: MIT
metadata:
version: 1.0.0
author: Alireza Rezvani
category: marketing
updated: 2026-03-06
Marketing Context
You are an expert product marketer. Your goal is to capture the foundational positioning, messaging, and brand context that every other marketing skill needs — so users never repeat themselves.
The document is stored at .agents/marketing-context.md (or marketing-context.md in the project root).
How This Skill Works
Mode 1: Auto-Draft from Codebase
Study the repo — README, landing pages, marketing copy, about pages, package.json, existing docs — and draft a V1. The user reviews, corrects, and fills gaps. This is faster than starting from scratch.
Mode 2: Guided Interview
Walk through each section conversationally, one at a time. Don’t dump all questions at once.
Mode 3: Update Existing
Read the current context, summarize what’s captured, and ask which sections need updating.
Most users prefer Mode 1. After presenting the draft, ask: “What needs correcting? What’s missing?”
Sections to Capture
1. Product Overview
- One-line description
- What it does (2-3 sentences)
- Product category (the “shelf” — how customers search for you)
- Product type (SaaS, marketplace, e-commerce, service)
- Business model and pricing
2. Target Audience
- Target company type (industry, size, stage)
- Target decision-makers (roles, departments)
- Primary use case (the main problem you solve)
- Jobs to be done (2-3 things customers “hire” you for)
- Specific use cases or scenarios
3. Personas
For each stakeholder involved in buying:
- Role (User, Champion, Decision Maker, Financial Buyer, Technical Influencer)
- What they care about, their challenge, the value you promise them
4. Problems & Pain Points
- Core challenge customers face before finding you
- Why current solutions fall short
- What it costs them (time, money, opportunities)
- Emotional tension (stress, fear, doubt)
5. Competitive Landscape
- Direct competitors: Same solution, same problem
- Secondary competitors: Different solution, same problem
- Indirect competitors: Conflicting approach entirely
- How each falls short for customers
6. Differentiation
- Key differentiators (capabilities alternatives lack)
- How you solve it differently
- Why that’s better (benefits, not features)
- Why customers choose you over alternatives
7. Objections & Anti-Personas
- Top 3 objections heard in sales + how to address each
- Who is NOT a good fit (anti-persona)
8. Switching Dynamics (JTBD Four Forces)
- Push: Frustrations driving them away from current solution
- Pull: What attracts them to you
- Habit: What keeps them stuck with current approach
- Anxiety: What worries them about switching
9. Customer Language (Verbatim)
- How customers describe the problem in their own words
- How they describe your solution in their own words
- Words and phrases TO use
- Words and phrases to AVOID
- Glossary of product-specific terms
10. Brand Voice
- Tone (professional, casual, playful, authoritative)
- Communication style (direct, conversational, technical)
- Brand personality (3-5 adjectives)
- Voice DO’s and DON’T’s
11. Style Guide
- Grammar and mechanics rules
- Capitalization conventions
- Formatting standards
- Preferred terminology
12. Proof Points
- Key metrics or results to cite
- Notable customers / logos
- Testimonial snippets (verbatim)
- Main value themes with supporting evidence
13. Content & SEO Context
- Target keywords (organized by topic cluster)
- Internal links map (key pages, anchor text)
- Writing examples (3-5 exemplary pieces)
- Content tone and length preferences
14. Goals
- Primary business goal
- Key conversion action (what you want people to do)
- Current metrics (if known)
Output Template
See templates/marketing-context-template.md for the full template.
Tips
- Be specific: Ask “What’s the #1 frustration that brings them to you?” not “What problem do they solve?”
- Capture exact words: Customer language beats polished descriptions
- Ask for examples: “Can you give me an example?” unlocks better answers
- Validate as you go: Summarize each section and confirm before moving on
- Skip what doesn’t apply: Not every product needs all sections
Proactive Triggers
Surface these without being asked:
- Missing customer language section → “Without verbatim customer phrases, copy will sound generic. Can you share 3-5 quotes from customers describing their problem?”
- No competitive landscape defined → “Every marketing skill performs better with competitor context. Who are the top 3 alternatives your customers consider?”
- Brand voice undefined → “Without voice guidelines, every skill will sound different. Let’s define 3-5 adjectives that capture your brand.”
- Context older than 6 months → “Your marketing context was last updated [date]. Positioning may have shifted — review recommended.”
- No proof points → “Marketing without proof points is opinion. What metrics, logos, or testimonials can we reference?”
Output Artifacts
| When you ask for… | You get… |
|---|
| ”Set up marketing context” | Guided interview → complete marketing-context.md |
| ”Auto-draft from codebase” | Codebase scan → V1 draft for review |
| ”Update positioning” | Targeted update of differentiation + competitive sections |
| ”Add customer quotes” | Customer language section populated with verbatim phrases |
| ”Review context freshness” | Staleness audit with recommended updates |
Communication
All output passes quality verification:
- Self-verify: source attribution, assumption audit, confidence scoring
- Output format: Bottom Line → What (with confidence) → Why → How to Act
- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
- marketing-ops: Routes marketing questions to the right skill — reads this context first.
- copywriting: For landing page and web copy. Reads brand voice + customer language from this context.
- content-strategy: For planning what content to create. Reads target keywords + personas from this context.
- marketing-strategy-pmm: For positioning and GTM strategy. Reads competitive landscape from this context.
- cs-onboard (C-Suite): For company-level context. This skill is marketing-specific — complements, not replaces, company-context.md.
#!/usr/bin/env python3
"""Validate marketing context completeness — scores 0-100."""
import json
import re
import sys
from pathlib import Path
SECTIONS = {
"Product Overview": {"required": True, "weight": 10, "markers": ["one-liner", "what it does", "product category", "business model"]},
"Target Audience": {"required": True, "weight": 12, "markers": ["target compan", "decision-maker", "use case", "jobs to be done"]},
"Personas": {"required": False, "weight": 5, "markers": ["persona", "champion", "decision maker"]},
"Problems & Pain Points": {"required": True, "weight": 10, "markers": ["core problem", "fall short", "cost", "tension"]},
"Competitive Landscape": {"required": True, "weight": 10, "markers": ["direct", "competitor", "secondary"]},
"Differentiation": {"required": True, "weight": 10, "markers": ["differentiator", "differently", "why customers choose"]},
"Objections": {"required": False, "weight": 5, "markers": ["objection", "response", "anti-persona"]},
"Switching Dynamics": {"required": False, "weight": 5, "markers": ["push", "pull", "habit", "anxiety"]},
"Customer Language": {"required": True, "weight": 10, "markers": ["verbatim", "words to use", "words to avoid"]},
"Brand Voice": {"required": True, "weight": 8, "markers": ["tone", "style", "personality"]},
"Style Guide": {"required": False, "weight": 3, "markers": ["grammar", "capitalization", "formatting"]},
"Proof Points": {"required": True, "weight": 7, "markers": ["metric", "customer", "testimonial"]},
"Content & SEO": {"required": False, "weight": 3, "markers": ["keyword", "internal link"]},
"Goals": {"required": True, "weight": 2, "markers": ["business goal", "conversion"]}
}
def validate_context(content: str) -> dict:
"""Validate marketing context file and return score."""
content_lower = content.lower()
results = {"sections": {}, "score": 0, "max_score": 100, "missing_required": [], "missing_optional": [], "warnings": []}
total_weight = sum(s["weight"] for s in SECTIONS.values())
earned = 0
for name, config in SECTIONS.items():
section_present = name.lower().replace("& ", "").replace(" ", " ") in content_lower or any(
m in content_lower for m in config["markers"][:2]
)
markers_found = sum(1 for m in config["markers"] if m in content_lower)
markers_total = len(config["markers"])
has_placeholder = bool(re.search(r'\[.*?\]', content[content_lower.find(name.lower()):content_lower.find(name.lower()) + 500] if name.lower() in content_lower else ""))
if section_present and markers_found > 0:
completeness = markers_found / markers_total
if has_placeholder and completeness < 0.5:
completeness *= 0.5 # Penalize unfilled templates
section_score = round(config["weight"] * completeness)
earned += section_score
status = "complete" if completeness >= 0.75 else "partial"
else:
section_score = 0
status = "missing"
if config["required"]:
results["missing_required"].append(name)
else:
results["missing_optional"].append(name)
results["sections"][name] = {
"status": status,
"markers_found": markers_found,
"markers_total": markers_total,
"score": section_score,
"max_score": config["weight"],
"required": config["required"]
}
results["score"] = round((earned / total_weight) * 100)
# Warnings
if "verbatim" not in content_lower and '"' not in content:
results["warnings"].append("No verbatim customer quotes found — copy will sound generic")
if not re.search(r'\d+%|\$\d+|\d+ customer', content_lower):
results["warnings"].append("No metrics or proof points with numbers found")
if "last updated" in content_lower:
date_match = re.search(r'last updated:?\s*(\d{4}-\d{2}-\d{2})', content_lower)
if date_match:
from datetime import datetime
try:
updated = datetime.strptime(date_match.group(1), "%Y-%m-%d")
age_days = (datetime.now() - updated).days
if age_days > 180:
results["warnings"].append(f"Context is {age_days} days old — review recommended (>180 days)")
except ValueError:
pass
return results
def print_report(results: dict):
"""Print human-readable validation report."""
print(f"\n{'='*50}")
print(f"MARKETING CONTEXT VALIDATION")
print(f"{'='*50}")
print(f"\nOverall Score: {results['score']}/100")
print(f"{'🟢 Strong' if results['score'] >= 80 else '🟡 Needs Work' if results['score'] >= 50 else '🔴 Incomplete'}")
print(f"\n{'─'*50}")
print(f"{'Section':<25} {'Status':<10} {'Score':<10}")
print(f"{'─'*50}")
for name, data in results["sections"].items():
icon = {"complete": "✅", "partial": "⚠️", "missing": "❌"}[data["status"]]
req = " *" if data["required"] else ""
print(f"{icon} {name:<23} {data['status']:<10} {data['score']}/{data['max_score']}{req}")
if results["missing_required"]:
print(f"\n🔴 Missing Required Sections:")
for s in results["missing_required"]:
print(f" → {s}")
if results["missing_optional"]:
print(f"\n🟡 Missing Optional Sections:")
for s in results["missing_optional"]:
print(f" → {s}")
if results["warnings"]:
print(f"\n⚠️ Warnings:")
for w in results["warnings"]:
print(f" → {w}")
print(f"\n* = required section")
print(f"{'='*50}")
def main():
import argparse
parser = argparse.ArgumentParser(
description="Validates marketing context completeness. "
"Scores 0-100 based on required and optional section coverage."
)
parser.add_argument(
"file", nargs="?", default=None,
help="Path to a marketing context markdown file. "
"If omitted, runs demo with embedded sample data."
)
parser.add_argument(
"--json", action="store_true",
help="Also output results as JSON."
)
args = parser.parse_args()
if args.file:
filepath = Path(args.file)
if not filepath.exists():
print(f"Error: File not found: {filepath}", file=sys.stderr)
sys.exit(1)
content = filepath.read_text()
else:
# Demo with sample data
content = """# Marketing Context
*Last updated: 2026-01-15*
## Product Overview
**One-liner:** AI-powered mobility analysis for elderly care
**What it does:** Smartphone-based fall risk assessment using computer vision
**Product category:** HealthTech / Digital Health
**Business model:** SaaS, per-facility licensing
## Target Audience
**Target companies:** Care facilities, nursing homes, 50+ beds
**Decision-makers:** Facility directors, quality managers
**Primary use case:** Automated fall risk assessment replacing manual observation
**Jobs to be done:**
- Reduce fall incidents by identifying high-risk residents
- Meet regulatory documentation requirements efficiently
- Give care staff actionable mobility insights
## Problems & Pain Points
**Core problem:** Manual fall risk assessment is subjective, time-consuming, and inconsistent
**Why alternatives fall short:**
- Manual observation takes 30+ minutes per resident
- Paper-based assessments are completed once per quarter at best
**What it costs them:** Falls cost €8,000-12,000 per incident, plus liability
**Emotional tension:** Staff fear missing warning signs, blame after incidents
## Competitive Landscape
**Direct:** Traditional gait labs — $50K+ hardware, need trained staff
**Secondary:** Wearable sensors — low compliance, residents remove them
**Indirect:** Manual observation — subjective, inconsistent
## Differentiation
**Key differentiators:**
- Uses standard smartphone (no special hardware)
- AI-powered analysis (objective, repeatable)
**Why customers choose us:** Fast, affordable, no hardware investment
## Customer Language
**How they describe the problem:**
- "We never know who's going to fall next"
- "The documentation takes forever"
**Words to use:** mobility analysis, fall prevention, care quality
**Words to avoid:** surveillance, monitoring, tracking
## Brand Voice
**Tone:** Professional, empathetic, evidence-based
**Personality:** Trustworthy, innovative, caring
## Proof Points
**Metrics:**
- 80+ care facilities served
- 30% reduction in fall incidents (pilot data)
**Customers:** Major care facility chains in Germany
## Goals
**Business goal:** Expand to 200+ facilities, enter Spain and Netherlands
**Conversion action:** Book a demo
"""
print("[Using embedded sample data — pass a file path for real validation]")
results = validate_context(content)
print_report(results)
if args.json:
print(f"\n{json.dumps(results, indent=2)}")
if __name__ == "__main__":
main()
Marketing Context
Last updated: [date]
Product Overview
One-liner: [What you do in one sentence]
What it does: [2-3 sentences]
Product category: [The "shelf" — how customers search for you]
Product type: [SaaS, marketplace, e-commerce, service]
Business model: [Pricing model and range]
Target Audience
Target companies: [Industry, size, stage]
Decision-makers: [Roles, departments]
Primary use case: [The main problem you solve]
Jobs to be done:
- [Job 1]
- [Job 2]
- [Job 3]
Use cases:
- [Scenario 1]
- [Scenario 2]
Personas
| Persona |
Role |
Cares about |
Challenge |
Value we promise |
| [Name] |
User |
|
|
|
| [Name] |
Champion |
|
|
|
| [Name] |
Decision Maker |
|
|
|
| [Name] |
Financial Buyer |
|
|
|
Problems & Pain Points
Core problem: [What customers face before finding you]
Why alternatives fall short:
- [Gap 1]
- [Gap 2]
What it costs them: [Time, money, opportunities]
Emotional tension: [Stress, fear, doubt]
Competitive Landscape
| Competitor |
Type |
How they fall short |
| [Name] |
Direct |
[Gap] |
| [Name] |
Secondary |
[Gap] |
| [Name] |
Indirect |
[Gap] |
Differentiation
Key differentiators:
- [Differentiator 1]
- [Differentiator 2]
How we do it differently: [Approach]
Why that's better: [Benefits]
Why customers choose us: [Decision drivers]
Objections
| Objection |
Response |
| "[Objection 1]" |
[How to address] |
| "[Objection 2]" |
[How to address] |
| "[Objection 3]" |
[How to address] |
Anti-persona (NOT a good fit): [Who should NOT buy this]
Switching Dynamics
Push (away from current): [Frustrations]
Pull (toward us): [Attractions]
Habit (keeping them stuck): [Inertia]
Anxiety (about switching): [Worries]
Customer Language
How they describe the problem:
- "[verbatim quote]"
- "[verbatim quote]"
How they describe us:
- "[verbatim quote]"
- "[verbatim quote]"
Words to use: [list]
Words to avoid: [list]
| Term |
Meaning |
| [Product term] |
[Definition] |
Brand Voice
Tone: [professional, casual, playful, authoritative]
Style: [direct, conversational, technical]
Personality: [3-5 adjectives]
Voice DO's: [list]
Voice DON'T's: [list]
Style Guide
Grammar: [Key rules]
Capitalization: [Conventions]
Formatting: [Standards]
Preferred terms: [List]
Proof Points
Metrics:
- [Metric 1]
- [Metric 2]
Customers: [Notable logos]
Testimonials:
"[quote]" — [Name, Title, Company]
"[quote]" — [Name, Title, Company]
| Value Theme |
Supporting Proof |
| [Theme 1] |
[Evidence] |
| [Theme 2] |
[Evidence] |
Content & SEO Context
Target keywords:
| Cluster |
Primary Keyword |
Secondary Keywords |
Intent |
| [Topic 1] |
[keyword] |
[kw1, kw2] |
[informational/commercial] |
Internal links map:
| Page |
URL |
Use for |
Anchor text |
| [Page name] |
[URL] |
[Topic] |
[Suggested anchor] |
Writing examples:
- [URL or file — what makes it good]
Goals
Business goal: [Primary objective]
Conversion action: [What you want people to do]
Current metrics: [If known]