What it is: The complete SEO weekly report entry point for Open Analytics. Prefer the data entry points already authorized in the current working environment: GA4 can be read via Analytics MCP, while GSC and Bing Webmaster Tools can be operated via Codex's built-in browser; API scripts and platform exports are optional data retrieval paths, not prerequisites for completing the weekly report. The Agent generates a Markdown weekly report based on the evidence obtained. Python weekly-organic-performance is only a single-period page summary, not another complete weekly report.
What it is not：
- Not a real-time dashboard (WorkBuddy, etc. read bundle JSON and build separately)
- Not full Google Ads / social media attribution (see
references/extensions.md） - Not a GTM/GA4 installation tutorial (the site must already have measurement connected)
Progressive loading: By default, only this file is read. When retrieving data, read references/portable/evidence-intake.md, and when drafting, read references/portable/report-template.md; other reference materials are read selectively based on the question, not mechanically loaded in full. Client configuration is provided externally; do not write client facts into this repository.
Data retrieval method: First confirm the MCPs, browser login state, APIs or exports available for this run, as well as the project's properties and permissions on each platform. When using GA MCP / the built-in browser, the client directory .envis not required to exist. Only when choosing this Skill's API collector should you set OPEN_ANALYTICS_PROJECT_ROOT and execute commands from scripts/ ; client configuration, credentials and data remain in the client directory. Do not copy client facts into public repositories.
§0 How to use
Trigger phrases
按 seo-weekly-report/SKILL.md 执行：
- 项目根：./（本文件夹）
- 报告周结束日：2026-08-23（周日，可选；默认上周日）
- 取数方式：connected（GA MCP + GSC/Bing 内置浏览器）| api | export；按实际可用来源组合
- 项目执行记录：有则提供，不强制套四个文本块
- 上周报告（可选）：reports/{project-id}-seo-weekly-{prev}.md
Inputs
| Input | Required | Description |
|---|---|---|
| Project properties and page scope | ✅ | May come from client configuration or verified project documentation; confirm the GSC, GA4 and Bing properties and the production hostname item by item |
config/project-config.yaml |
API mode | Site ID, GA4 hostname, optional thresholds and event configuration read by the collector |
config/brand-query-registry.yaml |
When splitting by brand | Brand term rules; if missing, do not report brand share |
scripts/.env |
API mode | For local API collector use only; not required in MCP / browser mode |
data/seo-report-bundle-*.json |
API mode | npm run fetch-all output; in connected and export modes, verifiable evidence can be used directly |
templates/*.txt |
Optional | Content, backlinks, observations, project status; may also be provided by project execution records |
| Last week's report | Optional | Week-over-week narrative and follow-up actions |
backlink-registry.yaml + current-period Referral evidence |
Optional | Load only when backlink Referral analysis is requested; evidence may come from MCP, the interface, exports or an API bundle |
Outputs
| # | Deliverable | Path |
|---|---|---|
| 1 | Data evidence and source records; API mode also has a merged data package | Project data directory or platform records; the API package is data/seo-report-bundle-{YYYY-MM-DD}.json |
| 2 | Weekly report Markdown | reports/{project-id}-seo-weekly-{YYYY-MM-DD}.md |
| 3 | Health check summary | Written into report §1 + quote at the top of the document |
Weekly data retrieval and drafting
- Confirm the report subject, page ownership, time zone, current/comparison periods, and each platform's properties. Do not mistakenly refer to full-site data as data for a particular repository page.
- Choose GA MCP, the logged-in Codex built-in browser, user exports, or API based on actual availability; different sources may be mixed, with no fixed priority. Record the actual date window, filters, data freshness, and unavailable items for each. When permissions are lacking or interface data is not yet fully processed, degrade honestly.
- When the API is configured and suitable for batch reruns, the collectors of this Skill may be run to form a bundle; when choosing other methods, this step is not required. It cannot be determined that the weekly report cannot be executed just because the project has no
.env. - Align the windows and page ranges of each source, verify project launch records and the previous report; every number must be traceable to current-period platform data, exports, or the bundle, then drafted according to the report template. Real data and private credentials do not enter public repositories.
For the common evidence requirements of each data retrieval method, see references/portable/evidence-intake.md; read only when the API collector is selected references/portable/api-setup.md。
Agent execution order
确认项目属性、页面范围与本次可用的取数方式
→ 读取 MCP／浏览器当期证据，或 API bundle／导出；不得只凭手动执行块写数据周报
→ 按 D0–D5 独立核对每个来源的实际周期、过滤器、维度和新鲜度；有 bundle 时读取 healthCheck 与 inputs.fetchedAt，不能把 merge 时间当来源新鲜度
→ 读取项目执行记录与可用的手动块
→ 可选读上周 reports/*.md
→ 按 references/portable/report-template.md 先建立事实与证据链，再生成 reports/*.md
→ 不编造任何当期证据中不存在的数字
All GA4 page and channel conclusions should be checked against the production hostname; in API mode, config/project-config.yaml provides the filter values, while in MCP/interface mode the actual filter conditions must be recorded to avoid localhost, preview domains, or other sites contaminating the weekly report.
Optional override
If there is project-skill-overlay.mdin the same directory, read it after finishing this file (tone, baseline, extra sections).ProhibitedReferencing paths outside the folder.
§1 Data bundle
The API collection mode is named data/seo-report-bundle-{YYYY-MM-DD}.json(date = Sunday of the current week). MCP/browser mode does not require first creating an isomorphic JSON.
Schema：references/portable/report-bundle-schema.md（schemaVersion: 1.0.0）
Validation：
python tools/validate_bundle.py data/seo-report-bundle-YYYY-MM-DD.json
python tools/week_period.py --week-end 2026-08-23
Key blocks
| Block | Purpose |
|---|---|
gsc |
Search clicks, branded/non-branded, top queries/pages |
ga4 |
Channels, landing pages, Key events,aiAssistant |
bing |
Second search engine, crawl issues |
content.weeklyNewPosts |
From content-catalog.yaml(optional) |
healthCheck |
D0–D5 of the API bundle; when there is no bundle, manually verify the same questions and list them in the report |
extensions |
Reserved for Ads / Social / landing×conversion (currently null) |
§2 Health checks D0–D5
Detailed table:references/portable/health-check.md
Must be handled before generating the report:
| ID | Agent behavior on failure |
|---|---|
| D0 | Label each source as MCP, browser, API, or export; for missing sources, skip only the dependent sections; a missing Bing does not invalidate the entire GSC+GA4 report |
| D1 false | Stop unconditional week-over-week comparison; correct the period or retain the platform's actual window and clearly state that direct comparison is not possible |
| D2 missing dimension | Mark the corresponding GSC section as "data unavailable" |
| D3 no GA4/Bing | Skip §3 or §5 |
| D4 below project threshold | ⚠️ low page alignment rate at the top of the document; §4 cross-interpretation is conservative; unknown when there is no dual-source data |
| D5 false | ⚠️ click volume at the top of the document exceeds the project-defined range, verify property and period; unknown when no range is configured |
§3 Branded term breakdown
Rules are in config/brand-query-registry.yaml; for the logic explanation see references/portable/brand-query-split.md。
Report §2.2 uses gsc.branded / gsc.nonBranded, do not use the sum of queries to impersonate overall (anonymous queries are hidden by GSC).
§4 Report structure and writing
Drafting and acceptance specification:references/portable/report-template.md. It determines the analysis depth and dynamic sections; the page comparison summary of weekly-organic-performance cannot be treated as the complete weekly report of this Skill.
Path：reports/{project.id}-seo-weekly-{period.current.end}.md
Principles：
- Chinese body text; URLs, event names, and English channel names are retained
- Every number must be traceable to the current period's MCP/browser records, platform exports, or bundle; execution blocks are not a substitute for platform metrics
- Newly collected GSC
overallcomes from property-level queries without dimensions and is not summed from page/query rows; when the project analyzes only some pages, the property overview cannot stand in for the project page-family total. If an old data pack is markedlegacy-page-row-sum-unverified, it must be re-pulled or interpreted only against the page sample. Brand terms match only visible queries; before publishing, spot-check short brand terms for misclassification. - Page/query candidates retain rows from the current period, the previous period, and large changes alike; URLs/queries that were present previously but not returned this period must be retained for verification, but "not returned" is not a real 0 for this period and cannot be used to directly claim a decline.
- The report must give specific changes, main contributors and offsets, data boundaries, and verifiable actions; a table of numbers without judgment does not count as a completed weekly report.
- Early-stage site with 0 clicks: write "base is low, look at trend not absolute values"
- Period-over-period comparisons only compare current / previous from the same source, of equal length, and aligned; when strict alignment is impossible, present the windows and limitations separately and do not fabricate a week-over-week comparison. When the previous period is 0, write the absolute change, not a percentage
Manual block mapping
| Template file | Report section | Description |
|---|---|---|
templates/content-weekly-block.txt |
Launch and observation window | ===CONTENT=== interval |
templates/backlinks-weekly-block.txt |
Conditional referral analysis | ===BACKLINKS=== |
templates/observations-block.txt |
Anomaly explanations and items to be verified | ===OBSERVATIONS=== |
templates/project-status-block.txt |
Decisions and next-period review | ===PROJECT_STATUS=== |
For the format see references/portable/manual-blocks.md。
§5 Metric glossary
When Agent explains metrics, read references/portable/metrics-glossary.md(GSC clicks vs GA4 sessions, etc.).
§6 Optional extensions
Extensions load by status; do not pretend the project already provides the corresponding data just because documentation exists:
| Module | Status and documentation |
|---|---|
| Paid Ads | Not connected;references/extensions.md §1 |
| Social | Not connected; §2 |
| Landing page × conversion | Not connected; §3 |
| Automated reconciliation of external link registry | When the project provides registry and Referral data, read references/portable/referral-analysis.md; in automatic mode, run from this Skill's scripts/ Run npm run fetch-referral-all |
| Dashboard | Not connected; §5, read-only bundle, this package does not build a UI |
Modules that are not connected may be mentioned as "to be connected". Referral mode is enabled only when the project inputs are complete,do not pretend that current-period data from any source already exists。
§7 Connection status and export mode (executable even without project API credentials)
When using GA MCP, a logged-in GSC/Bing built-in browser, or platform exports,merge does not automatically generate data packs for these sources:
- Directly read the current-period overview, page, and query samples of available platforms; export XLSX/CSV when precise calculation or retention is needed. For each source, record the property, actual date, search type/channel, hostname, filters, and data completion status. When there are only execution blocks and no platform metrics, only an execution record can be written.
- The Agent independently verifies the overview against dimension samples, does not sum visible top rows to pass them off as sitewide totals, and does not treat last week's report as this week's raw data. When dimensions are missing, trim the related sections.
- At the top of the document, mark the actual sources and limitations respectively, such as "GA MCP", "GSC built-in browser", "Bing built-in browser", "platform export"; do not write the entire report as just because one of the sources uses the API
api-auto。
§8 Optional API Collector Commands
In the scripts/ directory:
| Command | Purpose |
|---|---|
npm run fetch-gsc |
data/gsc-weekly-*.json |
npm run fetch-ga4 |
data/ga4-weekly-*.json |
npm run fetch-bing |
data/bing-weekly-*.json |
npm run merge |
data/seo-report-bundle-*.json |
npm run fetch-all |
All of the above |
Environment variable REPORT_WEEK_END=YYYY-MM-DD(Sunday) can fix the report week.
§9 Self-check before sending to the client
See the checklist at the end of references/project-skill-contract.md :
- No other repository paths, no client names, no internal URLs
-
.envNot in the package (only.env.example） -
data/、reports/desensitized or cleared - This SKILL +
references/portable/can run offline
§10 File Index
| Path | Audience |
|---|---|
README.md |
Human overview |
SKILL.md |
Agent main workflow (this file) |
references/portable/api-setup.md |
Human API configuration |
references/portable/evidence-intake.md |
Common evidence entry point for MCP, browser, export, and API |
references/portable/report-bundle-schema.md |
Agent / integration |
references/portable/report-template.md |
Agent drafting |
references/portable/referral-analysis.md |
Optional external-link Referral attribution and special report contract |
references/extensions.md |
Future Ads/Social/dashboard |
config/*.example.yaml |
Rename after copying |
§11 Troubleshooting
| Symptom | Possible cause | Handling |
|---|---|---|
| GSC 403 / 404 | The service account was not granted Full permission;GSC_SITE_URL does not match the property |
Check the Search Console user list and URL prefix (including trailing slash) |
| GA4 403 | The service account was not granted Property Viewer | GA4 Admin → Property access |
| Bing HTTP 401 | API Key is invalid or the site is not verified | Regenerate API Key |
fetch-all Skip Bing |
Not set BING_API_KEY |
Optional; when GSC and GA4 are both available, d0_dataSource=api-auto |
d1_periodAligned=false |
REPORT_WEEK_END is not Sunday |
Change it to the Sunday of that week, e.g., 2026-08-23 |
d4 too low |
GSC page path does not match GA4 landingPage | Check trailing slash and multiple domains; see landing-page-rules |
| GSC clicks are 0 | New site / wrong property URL / data delay of 2–3 days | Confirm the property; for early-stage sites, look at trends |
| merge cannot find the file | fetch was not run or REPORT_WEEK_END does not match the file name suffix |
Unify the environment variables and rerun |
| All brand terms are non-brand | Not copied brand-query-registry.yaml |
Copy from example and fill in patterns |