feat: add evidence-led GSC SEO optimizer skill 🤖🤖🤖

docs/README.skills.md

@@ -225,6 +225,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
 | [gitmoji](../skills/gitmoji/SKILL.md)<br />`gh skills install github/awesome-copilot gitmoji` | Generates commit messages following the gitmoji convention (https://gitmoji.dev) — picks the right emoji for the intent of the change and writes a well-formed message. Use when asked to "write a gitmoji commit", "add an emoji to my commit message", "which gitmoji should I use", "gitmoji this change", or when a project uses gitmoji-style commit messages. Works from a git diff, staged changes, or a plain description of the change. Generates the message only — does not run git commands. | `references/gitmoji-reference.md` |
 | [go-mcp-server-generator](../skills/go-mcp-server-generator/SKILL.md)<br />`gh skills install github/awesome-copilot go-mcp-server-generator` | Generate a complete Go MCP server project with proper structure, dependencies, and implementation using the official github.com/modelcontextprotocol/go-sdk. | None |
 | [gsap-framer-scroll-animation](../skills/gsap-framer-scroll-animation/SKILL.md)<br />`gh skills install github/awesome-copilot gsap-framer-scroll-animation` | Use this skill whenever the user wants to build scroll animations, scroll effects, parallax, scroll-triggered reveals, pinned sections, horizontal scroll, text animations, or any motion tied to scroll position — in vanilla JS, React, or Next.js. Covers GSAP ScrollTrigger (pinning, scrubbing, snapping, timelines, horizontal scroll, ScrollSmoother, matchMedia) and Framer Motion / Motion v12 (useScroll, useTransform, useSpring, whileInView, variants). Use this skill even if the user just says "animate on scroll", "fade in as I scroll", "make it scroll like Apple", "parallax effect", "sticky section", "scroll progress bar", or "entrance animation". Also triggers for Copilot prompt patterns for GSAP or Framer Motion code generation. Pairs with the premium-frontend-ui skill for creative philosophy and design-level polish. | `references/framer.md`<br />`references/gsap.md` |
+| [gsc-seo-optimizer](../skills/gsc-seo-optimizer/SKILL.md)<br />`gh skills install github/awesome-copilot gsc-seo-optimizer` | Analyze Google Search Console exports or authorized API data to prioritize page improvements. Use for traffic changes, page/query opportunities, indexing evidence, and deciding when to leave recently edited or weakly supported pages alone. | `LICENSE`<br />`references/data-access.md`<br />`references/data-quality.md`<br />`references/report-template.md`<br />`references/roi-rubric.md`<br />`scripts/gsc_fetch.py`<br />`scripts/import_gsc.py`<br />`scripts/requirements-api.txt`<br />`tests/fixtures/Filters.csv`<br />`tests/fixtures/Pages.csv`<br />`tests/fixtures/Queries.csv`<br />`tests/test_gsc.py` |
 | [gtm-0-to-1-launch](../skills/gtm-0-to-1-launch/SKILL.md)<br />`gh skills install github/awesome-copilot gtm-0-to-1-launch` | Launch new products from idea to first customers. Use when launching products, finding early adopters, building launch week playbooks, diagnosing why adoption stalls, or learning that press coverage does not equal growth. Includes the three-layer diagnosis, the 2-week experiment cycle, and the launch that got 50K impressions and 12 signups. | None |
 | [gtm-ai-gtm](../skills/gtm-ai-gtm/SKILL.md)<br />`gh skills install github/awesome-copilot gtm-ai-gtm` | Go-to-market strategy for AI products. Use when positioning AI products, handling "who is responsible when it breaks" objections, pricing variable-cost AI, choosing between copilot/agent/teammate framing, or selling autonomous tools into enterprises. | None |
 | [gtm-board-and-investor-communication](../skills/gtm-board-and-investor-communication/SKILL.md)<br />`gh skills install github/awesome-copilot gtm-board-and-investor-communication` | Board meeting preparation, investor updates, and executive communication. Use when preparing board decks, writing investor updates, handling bad news with the board, structuring QBRs, or building board-level metric discipline. Includes the "Three Things" narrative model, the 4-tier metric hierarchy, and the pre-brief pattern that prevents board surprises. | None |

skills/gsc-seo-optimizer/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tracetify contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skills/gsc-seo-optimizer/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: gsc-seo-optimizer
+description: 'Analyze Google Search Console exports or authorized API data to prioritize page improvements. Use for traffic changes, page/query opportunities, indexing evidence, and deciding when to leave recently edited or weakly supported pages alone.'
+license: MIT
+---
+
+# GSC SEO Optimizer
+
+Turn the user's own search evidence into a small, justified optimization batch. Default to read-only diagnosis. Execute changes only within the user's explicit authorization; existing approval for a concrete batch remains valid. An analysis request never authorizes publishing or spending.
+
+## Establish scope and data route
+
+Confirm the exact GSC property (domain property or URL prefix), target market, Web/other search type, and requested period. Verify the property returned by a connector matches the requested site before using any numbers. Do not choose the first accessible property. Infer from the user's site and supplied context when unambiguous; ask if multiple properties or markets remain plausible.
+
+For ranking analysis use the user's target market, not a universal US default. Global performance totals may be useful separately; label them and never mix scopes in comparisons. If no market can be established, label aggregate findings and defer market-specific ranking claims.
+
+Use the least-friction route already available:
+
+1. **Supplied exports:** CSV or ZIP can be analyzed without credentials. Read [references/data-access.md](references/data-access.md) for the bundled local importer and export requirements.
+2. **Existing Google API access:** prefer it for reproducible filtering and comparison. The same reference documents the bundled read-only fetcher, authentication, and URL Inspection.
+3. **Connected tools:** inspect their actual capabilities and verify property, scope, freshness, authorization and any cost before use.
+4. **Available browser:** use the user's available authorized browser integration for UI-only evidence or missing API access. On login, account selection, 2FA, or permission screens, let the user complete the interaction. Never extract cookies, browser profile data, or passwords. If browser access is unavailable, request exports and continue with available evidence rather than blocking all analysis.
+
+Do not install packages/connectors or start OAuth unless needed and within the user's request. The CSV importer uses Python's standard library. API dependencies are optional and separate.
+
+## Validate before interpreting
+
+Read [references/data-quality.md](references/data-quality.md) before drawing conclusions. Every run must record property, date range, search type, country/device/page filters, data source, and completeness limitations.
+
+- Default to the most recent 28 complete GSC days, compared with the preceding non-overlapping 28 days when assessing change. Use 90 days for sparse sites and 7-day windows for recent releases, without treating short-term movement as causality.
+- Dates use GSC's Pacific-time calendar. Inclusive 28-day windows start 27 days before the end. Prefer finalized data and label the latest available date; a missing day is not proof of zero traffic or of ingestion completeness.
+- Get overall totals independently from page/query detail. Check row caps, pagination, anonymized queries, filter scope, and aggregation before reporting changes.
+- Separate brand, non-brand, and ambiguous terms using user-confirmed brand spellings/aliases. Inspect page-specific queries before calling a low-CTR page an opportunity; branded sitelinks are a common false signal.
+- Compare the same query and page when interpreting rank movement. An aggregate average can improve because lower-ranking queries disappeared.
+- Do not join separately exported page and query tables to invent query-to-page relationships. Without that evidence, offer page-level findings and state what targeted export is needed.
+- Impressions are not an indexing verdict. For indexing conclusions use URL Inspection or explicit UI evidence. Sitemap counts do not establish the indexed count of the whole site.
+
+If query evidence is absent or too sparse, try a targeted page export/query or available UI. UI may also omit anonymized queries. If no stronger evidence is available, lower confidence and continue only with supported findings; never conclude that the page has no keywords.
+
+## Prioritize
+
+Read [references/roi-rubric.md](references/roi-rubric.md) when ranking opportunities. Prefer relevant business intent, a plausible small intervention, and adequate evidence. Call this an opportunity assessment, not measured ROI unless conversion and cost data are supplied.
+
+Distinguish ranking gaps, snippet/intent mismatch, missing query coverage, and confirmed technical problems. Do not diagnose intent mismatch from CTR alone. Two pages appearing for a query do not by themselves prove cannibalization.
+
+Check recent edits in supplied change notes or repository history. Usually observe for at least 7–14 complete post-change days before another overlapping edit; larger ranking effects may take longer. Do not promise a time-to-impact.
+
+Recommend only as many pages as the evidence supports, often 1–5 and sometimes none. For each include URL, scope, clicks/impressions/CTR/position, supporting queries, diagnosis, proposed action, business relevance, confidence, and review interval. Explain important skips. Keep broad informational, irrelevant report, and very sparse pages out of the batch unless a strategic reason is explicit.
+
+## Deliver and optionally execute
+
+Lead with what changed and what to do next. State limitations that would change the decision. Use [references/report-template.md](references/report-template.md) to save a baseline when useful; analysis artifacts belong in the workspace and are not committed by default. Preserve private search data locally unless the user authorizes an external destination.
+
+For approved edits, inspect the project's own instructions and content storage first. Follow existing code/CMS patterns and limit changes to approved pages. Back up changed CMS rows. Align copy with the page's actual functionality; add FAQ/schema only for visible supported content. Avoid mass year updates, keyword stuffing, speculative canonicals, or replacing useful conversion copy with generic SEO prose.
+
+Verify the relevant rendered title, description, canonical, robots, schema, links, and visible content. Run the project's checks appropriate to the changes. Deploy only if authorized. Record changed URLs, edit/deployment dates, baseline, expected mechanism, and review interval. A later comparison can show association, not isolate the edit's causal effect.
+
+## Bundled tools and validation
+
+Use [scripts/import_gsc.py](scripts/import_gsc.py) for local CSV/ZIP exports. The optional [scripts/gsc_fetch.py](scripts/gsc_fetch.py) requires [scripts/requirements-api.txt](scripts/requirements-api.txt) and authorized Google access; setup is in the data-access reference. Python 3.9 or newer is required.
+
+Run `python3 -m unittest discover -s tests -v` from this skill directory. [tests/test_gsc.py](tests/test_gsc.py) checks parsing, scope, date windows, pagination and read-only request construction using synthetic [fixtures](tests/fixtures). API responses are mocked; these tests do not prove live authorization or host compatibility.
+
+## Provenance
+
+Adapted from [Tracetify Skills](https://github.com/tracetify/skills/tree/6ac8e87f7aa76b1ebec9148812b215158f04a059/skills/gsc-seo-optimizer), MIT. See [LICENSE](LICENSE).

skills/gsc-seo-optimizer/references/data-access.md

@@ -0,0 +1,59 @@
+# Data access
+
+Resolve script paths relative to this skill's installed directory, not the workspace or a private home directory. In the commands below, run from the skill directory or substitute its absolute path.
+
+## CSV / ZIP: no account or third-party Python dependencies
+
+In GSC Performance select the exact property, search type, date range and market/device filters, then export CSV. A ZIP of the CSV tables is supported. For comparisons export each window separately; the importer intentionally rejects ambiguous comparison columns. For a shortlisted page, add an exact page filter and export its Queries table separately.
+
+```bash
+python3 scripts/import_gsc.py /path/to/export.zip \
+  --property sc-domain:example.com --start 2026-08-28 --end 2026-09-24 \
+  --country deu --output /path/to/workspace/gsc-current.json
+```
+
+`--country`, `--device`, and `--page` **declare the export's filters; they do not filter the file**. Check preserved Filters records against these declarations. The importer never guesses a site's property or market from a filename. Scope remains user-declared until reconciled. If the exact property is unknown, omit `--property`: the output preserves null/unknown and marks scope incomplete. Do not invent a placeholder or infer domain versus URL-prefix property from page URLs. You can inspect the supplied rows while asking for the exact property, but defer cross-period/sitewide conclusions until scope is confirmed.
+
+Supported: UTF-8 CSV (including BOM), comma/semicolon/tab separation, English and common Chinese metric headers, standard separate export tables, and explicit combined page/query tables. `--number-format de` supports decimal-comma numbers **with supported headers**; it does not translate German headers. Other headers require deliberate mapping or an English re-export. XLSX is not supported by this helper. Use other available file tools only when their mapping is explicit.
+
+Missing metrics stay null. Tables stay separate. The output has `scopeTotal: null`; use the verified Chart table/API response for an independently scoped total, rather than summing query/page tables. ZIPs are read in memory, never extracted. Limits: 25 MiB input/uncompressed CSV data, 100 CSV members. Nothing is uploaded and there is no telemetry.
+
+## Google API: existing user authorization
+
+Use existing authorized credentials; never inspect browser credentials. If API setup is desired, the user's Google OAuth credential must authorize Search Console read access and the selected property. Application Default Credentials (ADC) alone may lack the Search Console scope. A service account also needs property access. Follow current Google guidance: https://developers.google.com/webmaster-tools/v1/how-tos/authorizing
+
+Install optional dependencies in a virtual environment, not the system Python:
+
+```bash
+python3 -m venv /path/to/workspace/.venv-gsc
+/path/to/workspace/.venv-gsc/bin/pip install -r scripts/requirements-api.txt
+/path/to/workspace/.venv-gsc/bin/python scripts/gsc_fetch.py sites
+```
+
+The script uses `google.auth.default` with the readonly scope. Quota attribution uses the credential's own setting, `GOOGLE_CLOUD_QUOTA_PROJECT`, or explicit `--quota-project`. No account, project, or credential is embedded. Do not print tokens, credential files, or secrets while diagnosing auth failures.
+
+```bash
+# Select the exact property returned by sites; this is an example only.
+python3 scripts/gsc_fetch.py query --property sc-domain:example.com \
+  --days 28 --country deu --dimensions page --compare \
+  --output /path/to/workspace/gsc-pages.json
+
+# Query a shortlisted page directly, using exactly the same date window.
+python3 scripts/gsc_fetch.py query --property sc-domain:example.com \
+  --start 2026-08-28 --end 2026-09-24 --country deu \
+  --page https://example.com/tool --dimensions query --limit 50000
+
+python3 scripts/gsc_fetch.py inspect --property sc-domain:example.com \
+  --page https://example.com/tool
+python3 scripts/gsc_fetch.py sitemaps --property sc-domain:example.com
+```
+
+Without `--end`, the fetcher probes the last 90 Pacific-calendar days for finalized date rows in the selected scope and uses the latest returned day. Reuse that resulting window explicitly for other tables so all comparisons align. Sparse scopes can have an earlier last observed day: this is an available-data date, not proof of when processing finished.
+
+`--start` requires `--end`. `--days 28` includes exactly 28 days. `--compare` requests the preceding non-overlapping window of equal length. `--limit` is a client cap across 25,000-row batches; reaching it is flagged, and even paginated results are not guaranteed exhaustive. `scopeTotal` comes from a separate zero-dimension query with matching filters; failures do not silently become zero totals.
+
+The commands are read-only. They never submit a sitemap, request indexing, alter a property or deploy content. Output file names are user-selected; keep private data out of version control.
+
+## Browser fallback
+
+Use the browser tool actually available to the user, rather than requiring a particular vendor's tool name. Request login/property selection when necessary; continue other supported work while waiting. Use UI for exact indexing aggregate buckets or additional query checks, while acknowledging that anonymized queries may remain hidden there too.