PDF Marketing Report Generator

Phase 0: Grounding

Read ${CLAUDE_PLUGIN_ROOT}/references/grounding.md and load any _grounding/ folder it finds. Client documentation outranks every default in this skill, and any claim rules it contains bind the output. Name the loaded files at the top of what you produce.

Pass business-appropriate action items into the JSON. The script's built-in fallbacks are deliberately generic and should not reach a client PDF.

Also read ${CLAUDE_PLUGIN_ROOT}/references/output-location.md. Normalize the target URL to its exact non-www domain and resolve two paths now:

python "${CLAUDE_PLUGIN_ROOT}/scripts/resolve_audit_output.py" --purpose MARKETING-REPORT --scope <domain> --extension pdf
python "${CLAUDE_PLUGIN_ROOT}/scripts/resolve_audit_output.py" --purpose REPORT-DATA --scope <domain> --extension json --data

Use python3 on macOS/Linux. The first call's output_path is the final PDF; the second's is the flat intermediate JSON under data/. Retain audit_dir — Step 1 below reads prior skill output from it too.

Skill Purpose

Generate a professional, visually polished PDF marketing report using the Python script scripts/generate_pdf_report.py. This skill collects all available audit and analysis data, structures it into the expected JSON format, invokes the script, and produces a branded PDF with score gauges, bar charts, comparison tables, findings, and a prioritized action plan.

When to Use

• User wants a PDF version of the marketing report (not just Markdown)
• User is preparing a deliverable for a client presentation
• User asks for a "polished report", "client-ready report", or "PDF report"
• User wants a visual report with charts and scores
• Triggered by /marketkit:report-pdf or /marketkit:report-pdf <domain>

When to Use PDF vs Markdown

Rule of thumb: If the report is going to a client or prospect, use PDF. If it is for internal use or further editing, use Markdown.

How to Execute

Step 1: Collect All Available Data

Gather data from all previous skill runs. Check only inside the audit_dir resolved in Phase 0, for the exact same domain scope — never search older audit folders.

Primary data sources (MARKETKIT - <PURPOSE> - <domain>.md unless noted):

• MARKETING-AUDIT -- Overall audit results
• LANDING-CRO -- Landing page conversion analysis
• SEO-AUDIT -- SEO findings
• BRAND-VOICE -- Brand voice analysis
• COMPETITOR-REPORT -- Competitor comparison data
• FUNNEL-ANALYSIS -- Funnel analysis
• SOCIAL-CALENDAR -- Social media plan
• EMAIL-SEQUENCES -- Email marketing plan
• AD-CAMPAIGNS -- Advertising plan

If no previous data exists:

1. Recommend the user run /marketkit:audit <url> first for the best results
2. If the user insists on generating a report without prior audits, analyze the provided URL directly and build the data structure from scratch
3. Use the analyze_page.py script to gather automated data: python3 "${CLAUDE_PLUGIN_ROOT}/scripts/analyze_page.py" "<url>" (python instead of python3 on Windows)

Step 2: Build the JSON Data Structure

The scripts/generate_pdf_report.py script expects a JSON file as input with this exact structure:

{
  "url": "https://example.com",
  "date": "March 1, 2026",
  "brand_name": "Example Co",
  "report_metadata": {
    "prepared_by": "[exact resolver output; omit this entire object when disabled]",
    "document_author": "[exact resolver output]",
    "toolkit": "Market Context Kit",
    "host": "[exact active host]",
    "llm_provider": "[exact active provider]",
    "llm_model": "[exact active model]",
    "generated_at": "[exact resolver output]"
  },
  "overall_score": 62,
  "executive_summary": "A 2-4 sentence summary of the overall marketing health, key opportunities, and estimated revenue impact of implementing recommendations.",
  "categories": {
    "Content & Messaging": {
      "score": 68,
      "weight": "25%"
    },
    "Conversion Optimization": {
      "score": 52,
      "weight": "20%"
    },
    "SEO & Discoverability": {
      "score": 74,
      "weight": "20%"
    },
    "Competitive Positioning": {
      "score": 48,
      "weight": "15%"
    },
    "Brand & Trust": {
      "score": 70,
      "weight": "10%"
    },
    "Growth & Strategy": {
      "score": 55,
      "weight": "10%"
    }
  },
  "findings": [
    {
      "severity": "Critical",
      "finding": "Description of the most important finding"
    },
    {
      "severity": "High",
      "finding": "Description of a high-priority finding"
    },
    {
      "severity": "Medium",
      "finding": "Description of a medium-priority finding"
    },
    {
      "severity": "Low",
      "finding": "Description of a lower-priority finding"
    }
  ],
  "quick_wins": [
    "First quick win action item",
    "Second quick win action item",
    "Third quick win action item"
  ],
  "medium_term": [
    "First medium-term action item",
    "Second medium-term action item",
    "Third medium-term action item"
  ],
  "strategic": [
    "First strategic action item",
    "Second strategic action item",
    "Third strategic action item"
  ],
  "competitors": [
    {
      "name": "Competitor A",
      "positioning": "Their market position",
      "pricing": "Their pricing model",
      "social_proof": "Their trust signals",
      "content": "Their content approach"
    },
    {
      "name": "Competitor B",
      "positioning": "Their market position",
      "pricing": "Their pricing model",
      "social_proof": "Their trust signals",
      "content": "Their content approach"
    }
  ]
}

Step 3: Field-by-Field Data Assembly Guide

url (string, required)

The target website URL. Use the full URL including protocol.

date (string, required)

The report generation date. Format: "Month DD, YYYY" (e.g., "March 1, 2026").

brand_name (string, required)

The company or brand name. Used in competitor comparison table headers.

overall_score (integer, 0-100, required)

The weighted average of all category scores. Calculate as:

overall_score = (content * 0.25) + (conversion * 0.20) + (seo * 0.20) + (competitive * 0.15) + (brand * 0.10) + (growth * 0.10)

executive_summary (string, required)

A 2-4 sentence summary covering:

• Current marketing health assessment
• Top 1-2 most impactful findings
• Estimated revenue impact of implementing recommendations
• Recommended first step

Keep it concise and impactful. This appears on the cover page right below the score gauge.

categories (object, required)

Exactly 6 categories with their scores. The categories map to these evaluation areas:

findings (array, required)

An array of finding objects, each with severity and finding fields.

Severity levels:

• Critical -- Directly losing revenue or customers. Fix immediately.
• High -- Significant impact on growth. Fix within 1-2 weeks.
• Medium -- Meaningful improvement opportunity. Fix within 1 month.
• Low -- Nice-to-have improvement. Fix when time allows.

Writing effective findings:

• Be specific: "Homepage headline says 'Welcome to Our Platform'" not "Headline needs improvement"
• Quantify impact: "Missing meta descriptions on 8 of 12 landing pages"
• Reference benchmarks: "Page load time is 4.2s (benchmark: under 2s)"
• Include evidence: "No testimonials found on homepage, pricing/RFQ/contact page, or signup/enrollment page"

Aim for 5-10 findings. Order from most to least severe.

quick_wins (array, required)

3-5 action items that can be implemented within one week with minimal effort. Each should be a specific, actionable instruction.

Good quick win: "Rewrite the homepage headline from 'Welcome to Our Platform' to 'Cut Your Reporting Time by 75% -- Automated Analytics for Growth Teams'"

Bad quick win: "Improve the headline" (too vague)

medium_term (array, required)

3-5 action items requiring 1-3 months to implement. These are more involved but have high impact.

strategic (array, required)

3-5 action items requiring 3-6 months. These are foundational changes that require planning and sustained effort.

competitors (array, optional)

Up to 3 competitor objects for the comparison table. If no competitor data is available, omit this field -- the script will skip the competitor section.

Step 4: Write the JSON File

Use the Write tool to save the assembled data to the exact output_path resolved in Phase 0 for REPORT-DATA (flat under data/). The Write tool creates the folder if it doesn't exist yet — do not mkdir separately.

Do not build this file with a shell heredoc or echo redirect. Heredoc quoting differs between shells and breaks on Windows, and JSON containing quotes, $, or backticks gets corrupted. The Write tool behaves identically on every platform. For the same reason, do not use /tmp — it does not exist on Windows.

Step 5: Invoke the PDF Generator Script

Prerequisites check: First, verify that reportlab is installed:

# macOS / Linux
python3 -c "import reportlab" || pip3 install reportlab
# Windows
python -c "import reportlab" || pip install reportlab

Generate the report:

# macOS / Linux
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/generate_pdf_report.py" "<REPORT-DATA output_path>" "<MARKETING-REPORT output_path>"
# Windows
python "${CLAUDE_PLUGIN_ROOT}/scripts/generate_pdf_report.py" "<REPORT-DATA output_path>" "<MARKETING-REPORT output_path>"

${CLAUDE_PLUGIN_ROOT} resolves to this plugin's directory on any machine — never hardcode a path. Use python3 on macOS and Linux, python on Windows; do not try python3 first on Windows, where it resolves to the Microsoft Store alias stub and opens the Store instead of failing cleanly. Pass the two exact output_path values resolved in Phase 0 — do not reconstruct them.

Demo mode (no arguments): Running the script without arguments generates a sample report with placeholder data:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/generate_pdf_report.py"
# Creates: MARKETING-REPORT-sample.pdf in the current directory

Step 6: Verify the Output

After generation, verify the PDF was created:

ls -la "<MARKETING-REPORT output_path>"

Report the file path and size to the user.

The REPORT-DATA JSON under data/ is a kept intermediate, not a temp file — never delete it. It lets a later report-pdf or report run reuse this run's assembled data.

PDF Report Contents

The generated PDF includes the following pages:

Page 1: Cover Page

• Report title: "Marketing Audit Report"
• Target URL
• Generation date
• Overall score gauge (circular visualization with color coding)
• Grade letter (A+ through F)
• Executive summary paragraph

Page 2: Score Breakdown

• Horizontal bar chart showing all 6 category scores with color coding
• Score table with category names, scores, weights, and status labels
• Color coding: Green (80+), Blue (60-79), Yellow (40-59), Red (<40)

Page 3: Key Findings

• Findings table with severity labels and descriptions
• Color-coded severity indicators (Critical = red, High = orange, Medium = yellow, Low = blue)
• Findings ordered from most to least severe

Page 4: Prioritized Action Plan

• Quick Wins section (This Week)
• Medium-Term section (1-3 Months)
• Strategic section (3-6 Months)
• Numbered action items in each tier

Page 5: Competitive Landscape (if competitor data provided)

• Comparison table with client vs up to 3 competitors
• Rows: Positioning, Pricing, Social Proof, Content

Final Page: Methodology

• Scoring methodology explanation
• Category weights and measurement criteria
• Optional footer: exact toolkit, host, provider, and model from report_metadata; omit when metadata is disabled

Color Scheme

The PDF uses a professional color palette:

Score-to-Color Mapping

• 80-100: Green (#00C853) -- Strong performance
• 60-79: Blue (#2D5BFF) -- Solid with room to improve
• 40-59: Amber (#FFB300) -- Needs attention
• 0-39: Red (#FF1744) -- Critical issues

Troubleshooting

Integration with Other Skills

This skill works best when combined with other audit skills. The recommended workflow:

1. Run /marketkit:audit <url> -- Generates comprehensive audit data
2. Run /marketkit:competitors <url> -- Adds competitor comparison data
3. Run /marketkit:seo <url> -- Adds detailed SEO findings
4. Run /marketkit:landing <url> -- Adds CRO analysis
5. Run /marketkit:report-pdf <url> -- Compiles everything into a PDF

The PDF report skill will automatically look for output files from these skills and incorporate their data into the report JSON.

Output: MARKETKIT - MARKETING-REPORT - <domain>.pdf

• File: the exact output_path resolved in Phase 0 for MARKETING-REPORT
• Location: the active audit folder, resolved per ${CLAUDE_PLUGIN_ROOT}/references/output-location.md (Audit/)
• Data: MARKETKIT - REPORT-DATA - <domain>.json, kept flat under data/
• Size: Typically 200KB-500KB depending on content volume
• Pages: 5-7 pages depending on whether competitor data and additional sections are included

Key Principles

• The PDF report is the most client-facing deliverable in the toolkit. Quality matters.
• Always verify the JSON data is complete and accurate before generating. Garbage in, garbage out.
• Use the PDF for initial client impressions and sales conversations. Follow up with the more detailed Markdown report if the client engages.
• Every score should be justifiable. If a client asks "why did I get a 52 in Conversion Optimization?", the findings should provide clear evidence.
• Round scores to whole numbers. Decimals imply false precision.
• Keep the executive summary tight -- 2-4 sentences maximum. Clients skim cover pages.
• If generating for a prospect (not yet a client), the report serves as a sales tool. Make the opportunities compelling and the action plan achievable.