skills/swads-daily-report/SKILL.md

name, description

name	description
swads-daily-report	Generate a complete SW Ads morning delivery report as Wise-styled HTML and PNG.

SW Ads Daily Report

Generate one read-only report for the current SW Ads account. Default to the most recent complete business day, with the previous seven complete days as context. Honor an account or date override when the user supplies one.

Preflight

Before collecting data, inspect the available tools for the swads MCP and require these read-only capabilities:

• swads_whoami
• metrics_catalog
• metrics_semantic_query

If those tools are absent, stop before report generation and tell the user that the SW Ads MCP dependency is missing. Provide this setup guide with the token left as a placeholder:

export SWADS_MCP_TOKEN='<request this Token from your internal administrator>'
codex mcp add swads \
  --url https://ads.mincode.cn/mcp \
  --bearer-token-env-var SWADS_MCP_TOKEN

Tell the user to keep SWADS_MCP_TOKEN available when Codex starts, restart the Codex session, and invoke $swads-daily-report again. Never request that a real token be pasted into chat or committed to a repository.

When the tools exist, call swads_whoami as the connection and identity check. Distinguish an authentication or permission error from a missing MCP installation, report the returned error without exposing credentials, and stop until access is fixed. Do not fabricate data or render an empty report.

Collect

1. Use the successful swads_whoami preflight response and its current account, reporting timezone, UTC offset, and currency. If no current account exists, stop and ask the user to select one.
2. Call metrics_catalog before semantic queries. Use supported metric and dimension names from the returned catalog.
3. Query the report period and comparison period with metrics_semantic_query:
   • account summary: spend, impressions, clicks, CTR, CPI, revenue, orders, ROI/ROAS, and cost per result;
   • daily time series for the previous seven complete business days;
   • campaign breakdown, excluding zero-spend rows;
   • creative breakdown with creative ID, title, creator, spend, revenue, orders, product impressions, product clicks, and product CTR.
4. Read runtime_account_overview, runtime_list_proposals, and runtime_get_config. Read runtime_findings as best-effort: derive findings from semantic metrics when it errors or is unavailable.
5. Use campaign_list to map external campaign IDs to names and current remote status. Paginate only until every campaign in the breakdown is mapped or the list is exhausted.

Map every semantic row through its returned columns[].name; positional assumptions about raw MCP rows are invalid.

Analyze

Produce the same five report sections on every run:

1. Account status: Spend, CTR, CPI, ROI, and ROAS. Treat missing denominators as N/A, not zero. For GMV Max, label GMV/spend as ROAS and label (GMV-spend)/spend as simplified advertising ROI; state that product, commission, refund, and fulfillment costs are absent.
2. Abnormal and strong campaigns. Rank by both efficiency and sample size. Prefer active campaigns in the main tables; identify recently disabled spend only in a note when material.
3. Creative performance and attribution clues. Separate account-owned posts from other creators using the current account name. Present correlation as a clue, not causality, and disclose attribution source and creative-level coverage.
4. Exactly three prioritized recommendations tied to observed rows.
5. Manual confirmation: every pause/resume, budget, target, pin/unpin, publishing, or other platform write requires explicit user confirmation. This skill never performs platform writes.

Use the latest complete business day for decisions. A partial current day may appear only as a clearly labeled monitoring note.

Render and deliver

Read references/report-data-schema.md, then create a normalized JSON document matching it. Write daily artifacts under a durable date folder such as ~/swads-reports/YYYY-MM-DD/ unless the user specifies another destination.

Run:

python3 <skill-directory>/scripts/render_daily_report.py \
  --data /absolute/path/report-data.json \
  --html /absolute/path/swads-daily-report.html \
  --png /absolute/path/swads-daily-report.png

The renderer uses assets/report.css. If Chromium is unavailable, return the HTML and explain that PNG rendering was skipped; do not install dependencies automatically. Inspect the PNG with view_image. Re-render with a larger --image-height only when content is visibly cut off.

If the local sandbox blocks headless Chrome, request approval and rerun only the same renderer command with escalated local execution. This approval is for rendering local artifacts, not for changing SW Ads state.

Deliver the PNG inline when supported, plus clickable links to the PNG, HTML, and normalized JSON. Summarize the three recommendations and which actions need confirmation in no more than five lines.