/monthly-performance-summary

name: monthly-performance-summary
description: >
  Generate a clear, client-ready social media performance summary from Planable analytics
  or a user-uploaded CSV export. Use this skill whenever the user asks for a monthly report,
  performance recap, analytics summary, results overview, or says things like "summarize
  last month's performance", "give me a report for [client]", "how did we do this month",
  "pull the analytics for [workspace]", or uploads a CSV with social media data and asks
  for a summary. Works with or without a Planable account — activate for any analytics
  summary request, whether the source is the Planable connector or a file upload.

Monthly performance summary

Generate a plain-language performance summary from Planable analytics data or a CSV export. Works in two modes: connected (pulls data live via Planable) or CSV (user uploads their own export).

---

Step 0: Detect the input mode

**Mode A — Planable connector** (default) The user has a Planable account connected and wants to pull live data.

**Mode B — CSV upload** The user has uploaded (or will upload) a CSV export from Planable or any social media analytics tool.

**How to detect:**

• If the user uploads a file → Mode B
• If the user mentions "export", "CSV", "spreadsheet", or "file" → Mode B
• If the user mentions a workspace name, client, or Planable directly → Mode A
• If unclear, ask: "Do you have a CSV export to upload, or should I pull the data from your Planable workspace?"

---

Mode A: Planable connector

Step 1: Gather inputs

• **Workspace / client name** — which workspace to report on
• **Date range** — default to previous calendar month if not specified
• **Platforms to include** — all pages by default, or specific platforms if requested

Step 2: Fetch data

list_workspaces → find workspaceId
list_pages(workspaceId) → get all pageIds
get_page_metrics(workspaceId, pageIds, startDate, endDate)
get_page_metrics_summary(workspaceId, pageIds, startDate, endDate)
get_post_metrics_summary(workspaceId, pageIds, startDate, endDate)

For top post highlights, page through `get_post_metrics(workspaceId, pageIds, startDate, endDate)` for the whole period, then rank the posts by engagement and take the top 5. It returns the newest posts first, not the best ones, so `limit: 5` alone would give the 5 newest posts. Check that the number of posts fetched matches `totalPosts` from `get_post_metrics_summary`; if it is lower, fetch page by page or over shorter date ranges, and mention any gap in the notes.

**Note on unsupported platforms:** `get_page_metrics` returns `unsupportedPages` for Google My Business and Threads — note these in the report as "data not available." X is not missing data: `get_page_metrics_summary` leaves it out of its totals (it shows up in `unsupportedPages` there), and its figures cover only the posts published through Planable — say so in the report rather than calling X "data not available".

**Analytics add-on:** if a metrics tool rejects because the analytics add-on is not active for the workspace, tell the user plainly and offer Mode B: they can upload a CSV export instead.

**Data freshness:** if `metricsFetchedAt` is old, offer `refresh_page_metrics` and `refresh_post_metrics`. They only queue a sync, so new data lands after a few minutes; offer to build the report with the stored numbers meanwhile. If `metricsFetchedAt` has not changed after a few minutes, the sync did not run: carry on with the stored numbers and say how old they are.

Step 3: Structure the report → go to [Report Format](#report-format)

---

Mode B: CSV upload

Step 1: Accept the file

If no file is uploaded yet, ask: "Please upload your CSV export and I'll summarize it."

Supported sources: Planable Analytics export, Hootsuite, Sprout Social, Meta Business Suite, LinkedIn Analytics, or any tabular CSV with date, platform, and metric columns.

Step 2: Parse the CSV

Read the uploaded file. Identify:

• **Date column** — look for `date`, `period`, `week`, `month`, or similar
• **Platform column** — look for `platform`, `channel`, `network`, `page`, `profile`
• **Metric columns** — impressions, reach, views, engagement, likes, comments, shares, followers, engagement rate

If the structure is unclear or columns are ambiguous, ask one clarifying question before proceeding.

**Flexible parsing rules:**

• Column names may vary by source — match by keyword, not exact name
• Aggregate by platform if data is at post level
• Handle blank rows and footer rows gracefully (skip non-numeric rows in metric columns)
• If a date range is not obvious from the data, ask the user to confirm what period the export covers

Step 3: Structure the report → go to [Report Format](#report-format)

---

Report Format

Deliver the report as a **downloadable HTML file** — a self-contained visual report the user can open in a browser, share with a client, or screenshot. Also output a short plain-text summary in chat so the user can see the key numbers without opening the file.

---

Visual HTML report

Generate a single `.html` file saved to `/mnt/user-data/outputs/[client-name]-[month]-report.html`. Use `present_files` after creating it.

The report must be visually designed — not a raw data dump. Follow these design principles:

**Aesthetic direction:** Clean, modern agency report. Light background, bold accent color (use Planable green `#3BBA7B` as primary accent). Card-based layout. Generous whitespace. Clear hierarchy.

**Required sections and visual treatment:**

1. Header

• Client name (large)
• Month + year
• Tagline: "Social Media Performance Report"
• Subtle gradient bar or divider in Planable green

2. 📊 Headline numbers — KPI cards

4 metric cards in a row (or 2×2 on narrow):

• 👥 **Total audience** (followers across all platforms)
• 👀 **Total impressions**
• 💬 **Total engagement**
• 📅 **Posts published**

Each card: big bold number, label, and trend arrow