feat: add daily report skill
This commit is contained in:
Jeffrey Wu
@@ -0,0 +1,74 @@
|
||||
---
|
||||
name: swads-daily-report
|
||||
description: 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:
|
||||
|
||||
```bash
|
||||
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](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:
|
||||
|
||||
```bash
|
||||
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](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.
|
||||
Reference in New Issue
Block a user