orkas-ai/orkas/seo-keywords

seo-keywords

Discover the phrasings people actually use, starting from a seed. seo-opportunity ranks queries a site ALREADY has console data for; this skill is the other half — it finds queries the site has no data for yet, which is where a new page or a new site has nothing to rank.

Deterministic and stdlib-only: it does not fetch, call models, or persist.

The split, and why the agent has to do the harvesting

A Python skill cannot reach the network. So the AGENT harvests and this skill processes. That division is the whole design — do not ask this skill for data it cannot get, and do not skip the processing because the raw lists "look fine": a pool of near-duplicate strings across three surfaces is not research.

When to use

• The user asks what to write, what to rank for, or which keywords to target.
• A site or page is new, or seo-opportunity returned mostly inferred /

Estimated rows because no Search Console data exists.

When NOT to use

• Ranking queries the site already has impressions for → seo-opportunity.
• Discovering volume or difficulty. Nothing here measures those. If you HAVE them

from a source that does, pass them in (below) — but this skill never estimates them, and no amount of scoring substitutes for them.

How to call

1) Harvest with web_search, one call per surface per seed. Record each returned phrase with the surface it came from:

• autocomplete — prefix suggestions
• related — related searches
• paa — People Also Ask questions

2) Process:

echo '{"seeds":["ai agent desktop app"],"brand":"Orkas","domain":"orkas.ai","harvested":[{"query":"best ai agent tools","source":"autocomplete"},{"query":"best ai agent tools for startups","source":"paa"}]}' | "$ORKAS_NODE" "$ORKAS_PC_DIR/bin/run-skill.cjs" seo-keywords keywords -- --op expand

→ { ok, data: { summary, clusters:[{head, dominant_intent, size, score, keywords:[{query,intent,sources,score,score_reasons,data_tier,metrics?}]}], rejected:[{query,reason}], data_tier, note } }

3) Optional — attach volume you already have. Pass metrics keyed by keyword (or a list of {keyword, ...} rows) with any of search_volume, keyword_difficulty, cpc, competition, plus a source label:

{"seeds":["crm"],"harvested":[...],"metrics":{"best crm tools":{"search_volume":2400,"keyword_difficulty":61,"source":"dataforseo"}}}

Matching is on the normalized keyword, so provider casing and spacing do not matter. A row that receives metrics is tiered Measured; the rest stay Observed. Sources that measure volume include a Search Console export, Keyword Planner, or a paid API the user already pays for — never this skill, and never the model's guess.

Own-brand and own-domain queries are rejected: they are brand defence, already yours to lose, and would crowd out the demand you do not yet serve. Every rejection names its reason — report the count, never drop them silently.

Reading the output

• `data_tier` is per row. Observed means the phrasing exists on the search

surface — not volume, not difficulty. Measured means external metrics were supplied for that specific row. The pool-level tier is Measured only when every kept row has them, Mixed when some do; one measured keyword never vouches for the unmeasured rest. Never write "high-volume keyword" for an Observed row, and never estimate the number yourself — say the phrasing is observed and name what would measure it.

• `score` never absorbs `metrics`. Volume is demand; the score is phrasing

quality. They stay separate fields so a measured row and an unmeasured one remain distinguishable at a glance. Rank by volume when you have it, and say which rows you had it for.

• `score` ranks phrasing quality, not demand — intent depth, specificity, and

whether more than one surface returned it. score_reasons carries the whole derivation; quote it rather than the bare number.

• `dominant_intent` decides the page type, not the wording: transactional →

pricing/signup, commercial → comparison/listicle, informational → guide/answer block, navigational → existing owned page (usually not worth new content).

• A cluster is one page, not one keyword. Its head is the broadest member;

write for the cluster and let the long-tail members inform the sections.