Update to HarborRank

{
  "description": "Group keywords into page-level clusters by search intent and map each cluster to an existing or new page, flagging cannibalization. Use when the user has a keyword list, saved keywords, or Search Console queries and asks which page should target which keywords, or wants a keyword map, content plan, topic clusters, or to fix pages competing for the same query.",
  "included_files": [],
  "name": "keyword-clustering",
  "skill_md_contents": "---\nname: keyword-clustering\ndescription: \"Group keywords into page-level clusters by search intent and map each cluster to an existing or new page, flagging cannibalization. Use when the user has a keyword list, saved keywords, or Search Console queries and asks which page should target which keywords, or wants a keyword map, content plan, topic clusters, or to fix pages competing for the same query.\"\n---\n\n# HarborRank Keyword Clustering\n\n## Goal\n\nGroup keywords into page-level clusters and decide which existing or new page should target each cluster. This is a keyword mapping workflow, not just a semantic grouping exercise.\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- Cluster the keywords the user supplies, or a Search Console query or query+page CSV export, by intent and page type.\n- Check whether borderline terms share results by running them through web search; label intent calls you could not check as unverified.\n- Map clusters to existing pages by reading the user's site; label the rest as proposed pages.\n- Flag cannibalization only when a query+page export shows it. Do not tag 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, difficulty, and SERP-overlap checks to these clusters.\" Do not add more sales copy than that.\n\n## Required inputs\n\n- `projectId`\n- A keyword list, saved keyword tag, seed topic, or target domain\n- Optional existing URLs/pages to map against\n\nIf keywords are not provided, use `list_saved_keywords` for saved sets, `research_keywords` for seed discovery, or `get_ranked_keywords` when the user starts from a target domain.\n\n## HarborRank MCP tools\n\n- `list_saved_keywords`: fetch an existing keyword set, optionally filtered by tags.\n- `research_keywords`: expand a seed when the user starts from a topic.\n- `get_ranked_keywords`: gather exact ranking keywords and URLs when the user starts from a domain or page.\n- `get_search_console_performance`: when Search Console is connected, pull real queries with `dimensions: [\"query\",\"page\"]` to map terms to the pages already earning impressions and to surface cannibalization (one query splitting clicks across multiple URLs).\n- `get_serp_results`: validate whether keywords belong on the same page by checking SERP overlap and intent.\n- `search_local_businesses`: find the businesses and categories around a location before mapping local clusters.\n- `get_local_serp_results`: use for local SEO clusters when Maps/local-pack intent should affect page mapping.\n- `save_keywords`: optionally tag final clusters after user confirmation.\n\n## Workflow\n\n1. Gather the candidate keyword set.\n   - Use `get_search_console_performance` (dimensions `[\"query\",\"page\"]`) when Search Console is connected to start from real queries and the pages already ranking for them.\n   - Use `get_ranked_keywords` for domain/page-driven clustering.\n   - Use `search_local_businesses` and `get_local_serp_results` when proximity, local packs, or Google Business results determine whether terms belong on location pages.\n2. Remove duplicates, irrelevant terms, and terms that clearly require a different product or audience.\n3. Build clusters around intent and page type:\n   - Same SERP intent and similar ranking pages belong together.\n   - Different intent, buyer stage, or SERP format should be split.\n   - Similar words do not guarantee the same cluster.\n4. For important borderline terms, use a small `get_serp_results` batch to check overlap.\n5. Assign each cluster to:\n   - Existing URL, if supplied and appropriate\n   - New page recommendation, if no existing page fits\n   - Do-not-target / later bucket, if weak or off-strategy\n6. Identify cannibalization risk when multiple pages would target the same intent. When Search Console is connected, confirm it from real data with `get_search_console_performance` (`dimensions: [\"query\",\"page\"]`) — the same query sending impressions to multiple URLs.\n7. Ask before applying cluster tags with `save_keywords`.\n\n## Output format\n\nStart with a short mapping summary:\n\n- Number of clusters\n- Pages to create\n- Existing pages to update\n- Cannibalization or consolidation issues\n\nThen include:\n\n| Cluster | Primary keyword | Secondary keywords | Intent | Target page | Priority | Notes |\n| ------- | --------------- | ------------------ | ------ | ----------- | -------- | ----- |\n\nFor each cluster, include a recommended page brief:\n\n- Page type\n- Searcher problem\n- Required sections\n- Internal-link opportunities\n- Save/tag suggestion\n\n- **Next workflow:** end with one recommended next workflow, the reason for it, and the input it starts from. Default: `competitor-analysis` on the domain that holds the top result for the highest-priority cluster's primary keyword, to see what the new or updated page has to beat.\n- **Where the output goes:** the cluster table as `keywords/clusters-<YYYY-MM-DD>.csv` and one brief per cluster as `content/briefs/<cluster-slug>.md`. Cluster tags go to the HarborRank project only after the user confirms. 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 over-cluster tiny keyword sets. If there are fewer than 10 usable terms, produce a simple map.\n- Do not rely on lexical similarity alone. SERP intent wins.\n- Do not replace tags broadly without explicit confirmation.\n- If existing URL data is missing, label target pages as proposed.\n"
}