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

[jacobGor123]

Summary

Add a Search Console analysis skill for choosing a small, evidence-backed batch of page improvements, including a no-change recommendation when the data is weak or a page was recently edited. It checks exact property, country/device filters, inclusive Pacific-time windows, independent totals and query/page linkage before interpreting performance.

The default workflow is read-only. CSV/ZIP mode works locally with Python standard-library code and needs no account. Optional Google API access uses existing authorization and the Search Console read-only scope. No embedded credentials, telemetry, vendor connector, automatic OAuth or external uploads are included.

Differentiation

The existing search-ai-optimization-expert agent provides broad SEO/AEO/GEO guidance. This skill addresses the narrower GSC evidence-to-edit workflow with reproducible export handling and constraints on aggregate/query inference. It does not replace a technical site audit or general SEO implementation agent.

Included resources

• Data access, data quality, prioritization and reporting references.
• A CSV/ZIP importer that preserves unknown values and separate tables, rejects ambiguous comparison columns, and bounds archive size without extracting paths.
• An optional read-only API helper for scope verification, paginated analytics, independently requested totals and URL Inspection.
• 14 dependency-free helper tests and synthetic CSV fixtures; API responses are mocked.

Behavioral validation

Tested in GitHub Copilot CLI 1.0.88 using isolated directories, synthetic supplied evidence and only skill/read tools. No production data or live Google requests were used.

Case	Observed result
Current export declares Germany/28 days but its Filters say worldwide/24 days; comparison uses a different property type; Pages and Queries are separate; sitemap indexed=0	Declines a sitewide growth claim and forced two-page rewrite. Does not assign the query to a page or infer deindexing from a sitemap count.
Comparable totals plus exact page-filtered query rows; branded pricing page edited Sept 22; sparse page edited Sept 23; last finalized data Sept 24; intentional noindex preview	Prioritizes the relevant API-docs page, preserves the targeted title without contrary SERP evidence, leaves the other pages alone, and reports only two complete evidence days for the pricing edit.

An initial run anchored a proposed review date to the historical baseline. The data-quality reference now explicitly anchors post-change windows to deployment and counts available evidence only through the finalized-data endpoint. The prioritization case was rerun after that correction; both directory adapters produced the intended decisions. These are bounded behavioral checks, not a guarantee across models.

Examples

1. “Review these two GSC ZIP exports for my German market. Which pages should we improve next, and which should we leave alone?”
2. “These page and query exports look promising. Can we actually tell which query belongs to which page?”
3. “We changed pricing three days ago. Is its low CTR evidence that we should rewrite the title again?”

Provenance and limitations

AI-assisted contribution by a contributor affiliated with Tracetify, adapted from Tracetify Skills, MIT; attribution and license retained. The directory adapter omits vendor-specific routing and private-preference conventions.

Claude Code runtime compatibility, live Google authorization and live API responses have not been tested in this contribution. No claim of independent human usage validation, increased rankings or measured ROI is made.

Repository validation

• npx @microsoft/vally-cli lint skills/gsc-seo-optimizer --verbose — spec compliance and relative references passed.
• npm run skill:validate — all 424 skills valid.
• npm start — generated README/marketplace build passed.
• npm run plugin:validate — passed; existing external-catalog warnings remain unrelated.
• python3 -m unittest discover -s skills/gsc-seo-optimizer/tests -v — 14 passed.
• Relative resource references, skill-creator validator and git diff --check passed.
• Required eng/fix-line-endings.sh run with an external BSD-sed compatibility wrapper on macOS; upstream script unchanged.

docs/README.agents.md includes six existing MCP install-link refreshes produced by the required generator. They are retained so README regeneration is clean; no agent source was changed.

Automated risk-scan note: unpinned-version-indicator matched “Latest returned finalized date” in an API diagnostic string. That wording describes a data date, not a package, action or container version. The three script-touch notices identify the intentionally bundled Python helpers/tests.

[github-actions]

🔒 PR Risk Scan Results

Scanned 13 changed file(s).

Severity	Count
🔴 High	0
🟠 Medium	1
ℹ️ Info	3

Severity	Rule	File	Line	Match
ℹ️	skill-script-touched	skills/gsc-seo-optimizer/scripts/gsc_fetch.py	1	skills/gsc-seo-optimizer/scripts/gsc_fetch.py
🟠	unpinned-version-indicator	skills/gsc-seo-optimizer/scripts/gsc_fetch.py	169	"detail": "Latest returned finalized date; days with no data may be omitted."})
ℹ️	skill-script-touched	skills/gsc-seo-optimizer/scripts/import_gsc.py	1	skills/gsc-seo-optimizer/scripts/import_gsc.py
ℹ️	skill-script-touched	skills/gsc-seo-optimizer/tests/test_gsc.py	1	skills/gsc-seo-optimizer/tests/test_gsc.py

This is an automated soft-gate report. Findings indicate review targets and do not block merge by themselves.

[github-actions]

🔍 Vally Lint Results

✅ All checks passed

Scope	Checked
Skills	1
Agents	0
Total	1

Severity	Count
❌ Errors	0
⚠️ Warnings	0
ℹ️ Advisories	0

Summary

Level	Finding
ℹ️	✅ gsc-seo-optimizer (2/2 checks passed)
ℹ️	✓ [spec-compliance] All 1 skill(s) are spec-compliant.
ℹ️	✓ spec-compliance: All spec checks passed.
ℹ️	✓ [valid-refs] All file references across 1 skill(s) are valid.
ℹ️	✓ valid-refs: All file references resolve to existing files within the skill directory.
ℹ️	1 skill(s) linted, 1 passed

Full linter output

### Linting skills/gsc-seo-optimizer
✅ gsc-seo-optimizer (2/2 checks passed)
    ✓ [spec-compliance] All 1 skill(s) are spec-compliant.
        ✓ spec-compliance: All spec checks passed.
    ✓ [valid-refs] All file references across 1 skill(s) are valid.
        ✓ valid-refs: All file references resolve to existing files within the skill directory.

1 skill(s) linted, 1 passed

[github-actions]

🚦 Submission status: 👀 Ready for review

Risk tier: merge-risk:high — Privileged execution, automation, or review-policy change
Required to merge: passing submission-gate checks plus 1 approval from reviewers with write access, including a maintainer with admin or maintain permission.

Why this tier

• skills/gsc-seo-optimizer/scripts/gsc_fetch.py is a high-risk path (automation, scripts, MCP config, hooks, or review policy)
• skills/gsc-seo-optimizer/scripts/import_gsc.py is a high-risk path (automation, scripts, MCP config, hooks, or review policy)
• skills/gsc-seo-optimizer/scripts/requirements-api.txt is a high-risk path (automation, scripts, MCP config, hooks, or review policy)
• skills/gsc-seo-optimizer/tests/test_gsc.py is a high-risk path (automation, scripts, MCP config, hooks, or review policy)

Automated checks

Check	Status	Details
Line endings	✅ Passed	Passed · logs
Spelling	✅ Passed	Passed · logs
Generated README consistency	✅ Passed	Passed · logs
Skill validation	✅ Passed	Passed · logs
Skill lint (vally)	✅ Passed	Passed · logs
Risk scan	✅ Passed	Passed · logs
Contributor reputation	✅ Passed	Passed · logs
Duplicate resource scan	✅ Passed	Passed · logs
PR quality signal	⏭️ Skipped	Skipped by its workflow · logs

Review

• Approvals: 0/1
• Assigned reviewer: aaronpowell
• Review target date: not set
• Still needed: 1 more approval(s); an approval from a maintainer with admin or maintain permission
• The core-maintainers pool is not staffed yet; an approver with admin or maintain permission is required instead.

Commands

Command	Who	What it does
/rerun-checks	PR author, maintainers	Re-runs failed or incomplete checks and re-evaluates this gate
/request-review	PR author, maintainers	Asks the review rotation to assign a reviewer (adds needs-reviewer)

_{Updated for 829d01c · gate run · This comment is maintained automatically — see submission gate docs.}

[jacobGor123]

Friendly ping: all automated checks are green and the PR is waiting on a reviewer with write access. Happy to adjust anything if it needs changes. Thanks!

[jacobGor123]

/rerun-checks

[github-actions]

🔁 /rerun-checks for cc0d81e

No failed or incomplete checks to re-run.

• Submission Gate has not run for this commit yet.

The status comment updates when the checks finish.

[jacobGor123]

/request-review

[github-actions]

🙋 Added needs-reviewer. Reviewer routing is assigning a reviewer now.

Already requested: aaronpowell.

[aaronpowell]

This doesn't fit with the repo at this time.