google-keyword-research
Research Google keywords for SEO and paid search using Google Ads planning data (Keyword Planner). Use for keyword ideas, search volume, "how many people search for" questions, CPC and bid estimates, competition, seasonality, or a Search Viability Loop that prices commercial keyword clusters against contribution-based acquisition ceilings and read-only forecasts before proposing a paid test.
- License 许可
- MIT
- 最近更新
- 2026-11-06
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- google-keyword-research
- description
- Research Google keywords for SEO and paid search using Google Ads planning data (Keyword Planner). Use for keyword ideas, search volume, "how many people search for" questions, CPC and bid estimates, competition, seasonality, or a Search Viability Loop that prices commercial keyword clusters against contribution-based acquisition ceilings and read-only forecasts before proposing a paid test.
02 资源文件 11
- 参考文档agents/openai.yaml321 B
- 参考文档README.md3.0 KB
- 参考文档references/cli-and-metrics.md11.5 KB
- 参考文档references/search-viability-loop.md13.2 KB
- 参考文档references/setup.md6.3 KB
- 参考文档references/viability-calculator.md10.7 KB
- 脚本scripts/google_keywords.py31.8 KB
- 脚本scripts/search_viability.py36.3 KB
- 脚本tests/test_forecast.py8.1 KB
- 脚本tests/test_google_keywords.py22.6 KB
- 脚本tests/test_search_viability.py22.5 KB
03 SKILL.md 正文
Google Keyword Research
Use observed Keyword Planner data to make a relevant keyword selection. Scripts retrieve data and calculate scenarios; the agent judges intent, product fit, evidence, and priority.
Choose the decision
- SEO or raw research: use the brief, research, and shortlist flow below. Do not require an offer, margins, conversion tracking, or a viability exercise for these requests.
- Paid-search viability: when the user asks whether Search ads can work, what they can afford, or to run the Search Viability Loop, read search-viability-loop.md. Lock the offer and calculate acquisition ceilings before building keyword clusters. Use the offline calculator and read-only forecasts to produce a decision sheet.
- Both: maintain separate SEO and paid-search conclusions. Informational terms can be useful for SEO while failing the first paid test's intent filter.
A request for paid keyword ideas or bid data alone does not require the full viability mode. Do not infer campaign execution permission from research or a GO result.
Establish the brief
Read supplied product context and keyword lists. Establish the audience, product or topic, and whether the decision concerns SEO, paid search, or both. Use the request's geography and language; ask when either is missing. Do not silently default to the US or the account's locale.
Keep separate markets in separate runs and rankings. Multiple geo IDs in one call describe a combined market, not individual country results. Worldwide targeting requires an explicit request. If only raw metrics are requested, return them without imposing a strategy exercise.
Get access and choose a command
Run the bundled script using its installed absolute path:
uv run /path/to/google-keyword-research/scripts/google_keywords.py --help
Read setup.md for first-time authentication, missing credentials, or access errors. Use external YAML via --config or Google Ads environment variables. Never ask the user to paste credentials into chat. doctor checks account access; only doctor --check-planning verifies planning access.
Read cli-and-metrics.md for arguments, output fields, limits, and interpretation.
- Use
locationsandlanguagesto resolve market IDs. Select the intended location from the returned canonical names; do not silently resolve ambiguous names. - Use
ideasfor keyword discovery from seed terms, a URL, or both, or from a whole domain with--site. Use coherent themes and a relevant product or landing-page URL. Google receives the supplied terms, URL, or domain. - Use
metricsto measure an existing list. Ideas already contain historical metrics, so a second call is usually unnecessary.--from-month/--to-monthselects a custom historical window, e.g. to compare seasons. - For more than a handful of rows, pass
--output file.json(and--csvif wanted). Stdout then shows a compact TSV summary instead of the full JSON; read the file only for the fields you need. - Use
forecastonly after selecting a commercial cluster and establishing its budget and CPC ceiling. It models a proposed scenario without saving a plan or creating a campaign. Its v25 limitations are documented in the CLI reference. - All commands read account data or generate planning results. They do not create campaigns, saved plans, bids, or budgets.
Do the accessible setup and research work, then identify the exact missing user action if OAuth consent or Cloud approval prevents live calls. Continue with clearly labeled provisional candidates if useful. Missing access never justifies fabricated volumes, bids, or competition scores.
Select and explain
- Apply product relevance first: identify what the searcher wants and whether the product or proposed content can satisfy it. Hold ambiguous terms and exclude unsupported promises.
- Group the returned terms by intent or use case. Rank by relevance, intent, observed demand, seasonality, and business value. Explain the tradeoffs instead of hiding them behind an arbitrary composite score.
- For SEO, use volume as demand evidence. Verify the live search results before claiming an intent match or an achievable ranking opportunity: use web search or browser tools when available, in the target market and language where possible, and note the result types (organic, local pack, shopping, video, AI overview), whether ads appear, and which page types rank (product, category, comparison, guide, forum). Without such a tool, label the intent assessment unverified. Google Ads competition measures advertising, not organic difficulty.
- For paid research, use advertiser competition and bid ranges as auction context. They do not establish an affordable bid, conversion rate, or profitability. Route affordability and test-budget decisions to the viability loop, which keeps observations, forecasts, and assumptions separate.
- Idea rows carry Google's keyword
concepts. ABRANDorOTHER_BRANDSconcept is a brand hint, not a verdict; you still judge brand and intent from the term and market. - Preserve null versus zero, returned close-variant groups, and each market's settings. Do not sum overlapping groups into a total addressable search market. Treat a truncated ideas response as a sample; its API order is not a priority ranking.
Deliver
Provide a concise ranked shortlist with intent, relevance, available metrics, seasonal observations, and a reason for selection. Separate SEO and advertising implications when both are requested. Include exclusions or uncertainties that change the decision.
For viability work, search_viability.py scaffold turns a metrics/ideas export into profile keyword entries for you to judge, and evaluate --forecast-plans DIR writes the exact forecast plan files the gates check. Deliver the reference's decision CSV, input/result JSON, keyword and negative exports, and a concise GO / NO_GO / INCOMPLETE explanation. economics returning READY means only that the economics brief is ready for keyword research. Only evaluate can return a full viability decision, and the proposed campaign needs its own combined check.
Link requested JSON/CSV exports and state geography, language, network, retrieval time, returned months, and any truncation or missing data. Preserve raw API output separately from your judgment. Reuse task exports for follow-up analysis when their settings and freshness fit; historical statistics refresh monthly. An unavailable result is unknown demand, not zero demand.
04 同仓库更多 Skills
motion-design
Plan, build, and review short motion-design films for SaaS and app marketing: launch videos, product films, promo and social ad clips, app trailers, and landing-page loops of roughly 6–45 seconds. Develops the brief, promise, storyline, rendered key frames, timed beat sheet, and sound plan first, has them critiqued with fresh eyes, and gets sign-off before any animation, because iterating on a plan is far cheaper than iterating on renders. Then builds the film (following the project's motion studio when one exists, otherwise a code-rendered timeline) and reviews cuts with a scored rubric and prioritized fixes. Use whenever the user wants to make, script, storyboard, animate, render, critique, or fix a product video, motion graphics ad, launch clip, or app promo, even if they only say 'make a video for my app' or share a cut for feedback. Not for UI micro-interactions inside the product itself.
mise
Set up, migrate, or maintain a project on the team's mise stack: mise tools and tasks under one shared task-naming convention, deployment environments as mise config environments (mise.<env>.toml), uv for Python, bun for JavaScript and TypeScript, Terraform in terraform/, and optional fnox secrets (Proton Pass locally, environment variables in CI and on deployed hosts). Invoke it to replace a Makefile, justfile, or package scripts, add or rename tasks, add secrets or environments, or bootstrap a repository.
grafana
Set up lean application monitoring in Grafana Cloud for a solo maintainer running several web apps, APIs, mobile backends, or jobs on GCP or AWS. Use when adding metrics or monitoring to an app; sending OpenTelemetry (OTLP) or Prometheus metrics to Grafana Cloud; querying Cloud Run, Lambda, Cloud Monitoring, or CloudWatch metrics from Grafana; building or fixing app and portfolio dashboards; or keeping active series within the free tier. Also covers client-side health signals for mobile and browser apps and whether a first alert is worth adding.
frontend-design
Design, implement, and refine polished web interfaces: new screens, components, dashboards, landing pages, and visual redesigns. Use when UI quality, layout, typography, responsive behavior, or interaction polish is part of the task, including requests to make an interface look better. Reuses or establishes a design system and verifies the rendered result. Not for backend-only work or logic changes with no visual impact.
apple-ads-keyword-research
Read Apple Ads (formerly Apple Search Ads) campaign data and research App Store keywords through the Apple Ads Platform API. Use for campaign, ad group, keyword, or search term performance (spend, taps, installs, CPT, CPI), Apple's keyword and phrase suggestions, relative App Store search popularity by country and genre, impression share and rank, ASO keyword ideas, or deciding which App Store keywords to add, pause, negate, or bid on. Read-only; it never changes campaigns.
agentic-browsing-auditor
Verify and improve a website, current page, or frontend repository for Lighthouse Agentic Browsing readiness. Use when asked to audit, raise, improve, or debug agentic browsing level, WebMCP readiness, llms.txt discoverability, agent-accessible forms, accessibility-tree quality for agents, or layout stability for AI/browser agents.