serp-keyword-harvester

SERP Keyword Harvester

This skill prepares raw search-demand evidence for the pre-design pipeline. It does not decide final site architecture or source/proxy policy; serp-source-configurator owns setup gates and this skill hands structured inputs to semantic-core-builder.

Operating Modes

• plan: define seed keywords, locales, sources, approvals, and fallback.
• harvest-local: normalize user-provided keywords, exported CSVs, existing site text, or local reports.
• harvest-external: use approved SERP/autocomplete APIs or tools; approval required before network calls.
• audit: review an existing reports/keyword-harvest.json.

Required Workflow

1. Read references/keyword-harvest-contract.md.
2. If OpenSERP, AKE, proxy, API keys, engine checkboxes, source settings, or paid-proxy limits are mentioned, route setup to serp-source-configurator first and consume its redacted reports/serp-source-config.json handoff.
3. If OpenSERP is already approved/configured, read references/openserp-setup.md and use assets/openserp-settings.example.json only as a redacted contract, not as a credential store.
4. Confirm privacy and approval mode:
   • local inputs and user-provided public facts: allowed;
   • external SERP/API/crawling: explicit approval required;
   • private/authenticated sources: explicit approval plus data-handling note.
5. Collect or normalize seed keywords, market/locale, project type, and source provenance.
6. Write or update reports/keyword-harvest.json using assets/keyword-harvest.schema.json as the field contract.
7. Label every data group as Ran, Skipped, Planned, or Manual.
8. Hand off to semantic-core-builder; do not invent missing SERP evidence.

Safety Rules

• Do not scrape or call external services without approval.
• Do not store API keys, cookies, private URLs, recovery codes, or .env values in reports.
• Treat OpenSERP as optional-cloud / external-network: no call without explicit approval, configured credentials, query scope, source config, and a data-transfer note.
• Do not decide proxy provider, paid budget, or engine selection inside this skill when it is not already explicit; use serp-source-configurator.
• If search APIs return 429/503 or are unavailable, mark the source Skipped and continue with local/user-provided inputs.

Handoff Shape

Mode:
Locale/market:
Seed keywords:
Sources used:
Sources skipped:
Source config:
Output path:
Privacy/approval note:
Next skill: semantic-core-builder

Validation

When editing this skill, run:

python3 $CODEX_HOME/skills/.system/skill-creator/scripts/quick_validate.py $CODEX_HOME/skills/serp-keyword-harvester
python3 $CODEX_HOME/skills/senior-skill-architect/scripts/lint_production_skill.py $CODEX_HOME/skills/serp-keyword-harvester