Update to HarborRank

{
  "description": "Find and prioritize keywords to target: discover ideas from seed topics or Search Console, check search volume, keyword difficulty, CPC, intent and live SERPs, and save the best terms to the HarborRank project. Use when the user asks what keywords to target or wants keyword ideas, content topics, search volume, low-competition or striking-distance keywords, or local service keywords.",
  "included_files": [],
  "name": "keyword-research",
  "skill_md_contents": "---\nname: keyword-research\ndescription: \"Find and prioritize keywords to target: discover ideas from seed topics or Search Console, check search volume, keyword difficulty, CPC, intent and live SERPs, and save the best terms to the HarborRank project. Use when the user asks what keywords to target or wants keyword ideas, content topics, search volume, low-competition or striking-distance keywords, or local service keywords.\"\n---\n\n# HarborRank Keyword Research\n\n## Goal\n\nTurn seed topics into a prioritized keyword opportunity set using HarborRank MCP data. The output should help the user decide what to target, what to save, and what to research next.\n\n## Step 0: Check connection\n\nBefore any other step, confirm the HarborRank MCP tools are loaded. Look for `get_domain_overview` or `list_leads` among your tools (the name may carry a prefix such as `harborrank`). If they are there, call `whoami`: it uses no credits, confirms the user is signed in, and returns `creditsRemaining` for budgeting the run. Do not call a research tool to test the connection.\n\nIf neither tool is available, or `whoami` fails because the user is not signed in, tell the user plainly: \"HarborRank isn't connected, so I can't pull live HarborRank data yet.\" Then tell them how to connect it:\n\n- ChatGPT or Codex: open the HarborRank plugin, choose Connect, and sign in to HarborRank.\n- Other clients: add `https://app.harborrank.com/mcp` as a remote MCP server. Setup for each client is at https://harborrank.com/docs/mcp.\n\nDo not stop there. Continue in fallback mode (below). If the user connects HarborRank mid-task, run Step 0 again and switch to the full workflow.\n\n### Plan limits\n\nOn hosted HarborRank, research tools spend credits. The Free plan has 1,000 credits a month and one project. Search Console, saved keywords, rank tracker reads, and site crawls use no credits. A keyword search costs about 50 credits and a domain overview about 80. Full backlinks, lead research (`research_lead`), and Lighthouse checks need a paid plan; on Free, the backlinks tools return a preview (totals and the top 3 referring domains, about 50 credits).\n\n- If `creditsRemaining` will not cover the planned calls, give the user the estimate and ask before spending. Use the free tools first.\n- If a tool replies that a feature \"is included in paid plans\", tell the user once which feature needs a paid plan, skip that tool for the rest of the run, and finish with the other evidence. Do not retry it.\n- If a tool fails for insufficient credits, stop making paid calls, tell the user, and finish with free tools and the data you already have. If `whoami` warns that credits are low, say so before a large run.\n- If the user asks about plans or credits, point them to https://harborrank.com/pricing. Do not quote prices or promote plans.\n- When `whoami` returns `mode: \"self-hosted\"`, there are no plan gates.\n\n### Fallback mode (no HarborRank connection)\n\nUse this mode only when Step 0 finds no connection. It works from web search, page reading, and files the user provides.\n\n**Can still do**\n\n- Gather keyword ideas from seed topics and from web search: related searches, autocomplete suggestions, and People Also Ask questions.\n- Work striking-distance queries (average position 5-20) from Search Console CSV exports in the workspace. Those figures are the user's own data; report them with the file as the source.\n- Read the top results for the leading candidates to judge intent and what a winning page needs.\n- Prioritize on business fit and intent, and deliver the shortlist as a table or file the user can save later. Do not save keywords.\n\n**Must not estimate**\n\nTraffic, search volume, keyword difficulty, CPC, keyword counts, rankings, backlink counts, Maps pack positions, and Q&A counts. Write `unknown` for each. A web search shows which pages appeared for a query when you searched, not their Google ranking: report it as \"appeared in web search\", never as a position.\n\n**Output**\n\n- Start with the label **Web-evidence only: no HarborRank data.**\n- Name the source (URL or file) of every figure you report.\n- End, after any recommended next workflow, with one sentence that names the numbers this report is missing: \"Connect HarborRank (the Free plan needs no card) to add search volume, keyword difficulty, and CPC to this shortlist.\" Do not add more sales copy than that.\n\n## Required inputs\n\n- `projectId`\n- One or more seed topics, products, pages, competitors, or audience problems\n- Optional market/location/language\n\nIf `projectId` is missing, use `list_projects` first. If the target market/location/language is unclear and would materially affect keyword metrics, ask the user; otherwise use the MCP tool defaults.\n\n## HarborRank MCP tools\n\n- `research_keywords`: primary discovery tool. Use 1-5 seeds per call and prefer 150 results unless the user asks for exhaustive research.\n- `get_keyword_metrics`: hydrate up to 700 known keywords with volume, keyword difficulty (KD), search intent, CPC, and monthly trends in one call. Use it to score candidate or known terms — including the Search Console striking-distance queries from step 1.\n- `get_ranked_keywords`: pull exact ranking keyword rows when a target domain or page is part of the research brief.\n- `get_search_console_performance`: when Search Console is connected, start from the project's real first-party demand — queries already earning impressions and near-ranking (\"striking distance\") terms. Request a high `rowLimit` and filter average position 5-20 client-side, since the API sorts by clicks and can't filter by position. Then hydrate those striking-distance queries with `get_keyword_metrics` to attach difficulty and intent.\n- `get_serp_results`: inspect SERPs for the top candidate terms, especially when intent is ambiguous.\n- `search_local_businesses`, `get_local_serp_results`, and `get_google_business_questions`: use for local SEO topics when a business/location radius matters.\n- `list_saved_keywords`: avoid duplicating already-saved work or use existing tags as context.\n- `save_keywords`: save selected keywords only after explicit user confirmation.\n\n## Workflow\n\n1. Normalize seeds into a small set of distinct research angles. If Search Console is connected for the project, first pull `get_search_console_performance` (high `rowLimit`, default lookback), filter to striking-distance positions (~5–20) client-side, and hydrate those queries with `get_keyword_metrics` to attach KD and intent. That ranked, hydrated list is your fastest opportunity set — work it before broad discovery.\n2. If the request is local SEO, identify the business, location/coordinates or service area, and local categories. Use `search_local_businesses` and `get_local_serp_results` for the most important location/keyword set instead of relying only on national keyword/SERP data.\n3. Call `research_keywords` for exploratory seeds. Use bulk calls when possible.\n4. Use `get_keyword_metrics` to hydrate a fixed keyword list — or the striking-distance queries from step 1 — with volume, KD, and intent before prioritizing.\n5. Use `get_ranked_keywords` when the user provides a domain/page and wants opportunities based on current rankings, near-misses, or competitor-owned terms.\n6. Remove irrelevant, duplicate, branded-only, and off-intent terms.\n7. Prioritize by practical opportunity, not volume alone:\n   - Strong match to the user's product/page/topic\n   - Clear search intent\n   - Reasonable difficulty\n   - Useful volume/CPC signal\n   - SERP where the user can plausibly compete\n   - For local SEO, local-pack/Maps visibility and proximity fit\n8. Use `get_serp_results` for high-potential or ambiguous keywords when SERP intent would change the recommendation; keep the default check small.\n9. Present a shortlist and a longer opportunity table.\n10. Ask before saving keywords. When saving, suggest concise tags such as `topic:<topic>`, `intent:<intent>`, or `page:<slug>`.\n\n## Output format\n\nStart with the highest-signal recommendation:\n\n- Best opportunity theme\n- Top keywords to target now\n- Keywords to save\n- Risks or SERP caveats\n\nThen include a compact table:\n\n| Keyword | Intent | Volume |  KD | CPC | Priority | Notes |\n| ------- | ------ | -----: | --: | --: | -------- | ----- |\n\nEnd with whether to save the chosen keywords.\n\n- **Next workflow:** end with one recommended next workflow, the reason for it, and the input it starts from. Default: `keyword-clustering` on the shortlist, to decide which page targets each keyword. If one domain holds the top results for most of the shortlist, recommend `competitor-analysis` on that domain instead.\n- **Where the output goes:** the opportunity table as `keywords/<topic>-<YYYY-MM-DD>.csv`, with the summary at the top of `keywords/<topic>-<YYYY-MM-DD>.md`. Keywords the user approves are also saved to the HarborRank project with `save_keywords`. Save it in the project's SEO folder (see `seo-project-setup`); if there is none, ask once whether to create one or where to save instead. If the user prefers a doc or a sheet and a docs or spreadsheet tool is available, put reports in a doc and tables in a sheet instead. Tell the user where it was saved.\n\n## Guardrails\n\n- Do not invent metrics. If HarborRank does not return a value, write `unknown`.\n- Do not call `save_keywords` without explicit confirmation.\n- Prefer business-fit and intent-fit over chasing the largest volume term.\n"
}