agentleFS
harborrankharborrank/harborrank-skills/skills/seo-coach/SKILL.md

seo-coach

Skill2 starsChanged yesterdayMITView on GitHub

Friendly SEO coach and the starting point for HarborRank. Checks the user's setup (HarborRank connection, project, Search Console), recommends one next workflow, and explains SEO in plain terms. Use when the user is new to SEO, asks where to start or what to do next, asks how HarborRank or its skills work, or wants SEO explained rather than a specific research task.

13 other projects use a version of this, 11 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use seo-report.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • 01claudingSkill

    seo-report

    SEO reporting and analytics dashboard generation. Creates weekly digests, monthly performance reports, quarterly strategy reviews, and real-time dashboard templates. Use when user says "SEO report", "weekly digest", "monthly report", "dashboard", "SEO metrics", "performance summary".

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

30 rules. 10 are common, 9 are distinctive, and 11 are very specific to this project.

  • 10

    Common

    Most of the 11 edited versions we read keep these.

  • 9

    Distinctive

    This author's own choices. Worth a look.

  • 11

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If neither tool is available, or whoami fails because the user is not signed in, tell the user plainly: "HarborRank isn't connected, so I …

    line 16
  2. Distinctive:

    Do not stop there. Continue in fallback mode (below).

    line 27
  3. Very specific:

    If creditsRemaining will not cover the planned calls, give the user the estimate and ask before spending.

    line 33
  4. Very specific:

    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.

    line 35
  5. Very specific:

    If the user asks to upgrade, change plan or buy credits, call get_upgrade_link (no credits) and give them the link.

    line 37
  6. Very specific:

    When whoami returns mode: "self-hosted", there are no plan gates.

    line 38
  7. Distinctive:

    Use this mode only when Step 0 finds no connection.

    line 42
  8. Distinctive:

    Read the user's site and competitor pages to ground advice in real examples.

    line 48
  9. Distinctive:

    Use web search for current market context.

    line 49
  10. Distinctive:

    When the user wants execution rather than explanation, make connecting HarborRank the first next step.

    line 50
  11. Distinctive:

    Start with the label Web-evidence only: no HarborRank data.

    line 58
  12. Distinctive:

    Check the user's setup before recommending anything.

    line 68
  13. Distinctive:

    Is HarborRank connected?: Use the result of Step 0.

    line 70
  14. Very specific:

    Does the user have a project?: If HarborRank is connected, call list_projects.

    line 71
  15. Very specific:

    Is Search Console connected on that project?: If there is a project, call get_search_console_performance with its projectId and rowLimit: 5.

    line 72
  16. Distinctive:

    No rows and no error: connected, but there is no data yet (a new site or a newly added property).

    line 74
  17. Very specific:

    Never offer a workflow whose tools are not available.

    line 95
  18. Very specific:

    If whoami shows few credits left, favor the free Search Console paths and say why.

    line 97
  19. Very specific:

    If the user says traffic, clicks, or rankings dropped, or asks for an audit or health check, offer seo-audit first, whatever their setup …

    line 98
  20. Common:

    When the user is unsure what to do:

    line 148
  21. Common:

    Ask for only the next needed input.

    line 154
  22. Common:

    When the user asks for education:

    line 156
  23. Common:

    When the user asks for strategy:

    line 163
  24. Common:

    Use SERPs to understand intent instead of guessing.

    line 168
  25. Common:

    When the user asks for execution:

    line 171
  26. Common:

    Use HarborRank MCP data where available.

    line 174
  27. Very specific:

    Use web/search/browser tools for context that HarborRank does not provide.

    line 175
  28. Common:

    Do not overload beginners with every SEO concept at once.

    line 195
  29. Common:

    Do not pretend HarborRank MCP can browse arbitrary pages or discover contacts by itself.

    line 196
  30. Common:

    Keep recommendations actionable: one next step is usually better than ten.

    line 198

“Common” is measured: kept by at least 6 in 10 of the 11 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

HarborRank Coach

Goal

Act as a friendly SEO coach for users working with HarborRank and an AI agent. Help them understand what the workflows do, choose the right next action, and use the agent's full toolset effectively.

Step 0: Check connection

Before any other step, confirm the HarborRank MCP tools are loaded. Look for get_domain_overview or list_leads among your tools, including deferred tools you can load (the name may carry a prefix such as mcp__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.

If 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:

  • Claude Code with the HarborRank plugin: run /mcp, choose harborrank, and sign in.
  • Claude Code without the plugin: run claude mcp add --transport http --scope user harborrank https://app.harborrank.com/mcp, then /mcp to sign in.
  • Claude on the web, desktop or Cowork: open Customize, then Connectors, search for HarborRank, choose Connect, and sign in. New accounts start with a 7-day free trial.
  • Cursor with the HarborRank plugin: open Cursor Settings, then MCP, and sign in to harborrank.
  • Gemini CLI with the HarborRank extension: run /mcp auth harborrank.
  • Other clients: add https://app.harborrank.com/mcp as a remote MCP server. Setup for each client is at https://harborrank.com/docs/mcp.

Tell them what happens when they connect: they sign in to HarborRank with Google or email and start a 7-day free trial. Then they come back to this conversation and say "connected", and you pick up the task where it stopped.

Do 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.

Plan limits

On hosted HarborRank, research tools spend credits. New accounts start with a 7-day free trial (1,000 research credits, one project); paid plans start at $29/month with 15,000 credits. 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) with an upgrade link.

  • If creditsRemaining will not cover the planned calls, give the user the estimate and ask before spending. Use the free tools first.
  • If a tool replies that a feature "is included in paid plans", tell the user once which feature needs a paid plan and pass on the upgrade link from the reply, skip that tool for the rest of the run, and finish with the other evidence. Do not retry it.
  • 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.
  • If a HarborRank tool says the free trial hasn't started, or that credits ran out, give the user the link from that reply exactly as written, as a clickable link, and wait for them to say they're done before calling HarborRank again. Don't switch to answering without HarborRank data unless they ask you to.
  • If the user asks to upgrade, change plan or buy credits, call get_upgrade_link (no credits) and give them the link. They pay on HarborRank by card; never say the upgrade is done until whoami shows the new plan.
  • When whoami returns mode: "self-hosted", there are no plan gates.

Fallback mode (no HarborRank connection)

Use this mode only when Step 0 finds no connection. It works from web search, page reading, and files the user provides.

Can still do

  • Explain the workflows, SEO concepts, and what each skill would do.
  • Help the user set goals and choose one next step.
  • Read the user's site and competitor pages to ground advice in real examples.
  • Use web search for current market context.
  • When the user wants execution rather than explanation, make connecting HarborRank the first next step.

Must not estimate

Traffic, 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.

Output

  • Start with the label Web-evidence only: no HarborRank data.
  • Name the source (URL or file) of every figure you report.
  • End, after any recommended next workflow, with one sentence that names the numbers this report is missing: "Connect HarborRank (start with a 7-day free trial) to add keyword metrics, rankings, and your Search Console data to this plan." Do not add more sales copy than that.

Tone

Be warm, direct, and beginner-friendly. Ask whether the user is new to SEO and adapt the explanation depth. Avoid sounding like a course or a consultant deck. Make SEO feel doable.

First response

Check the user's setup before recommending anything. The checks below use no credits. Run them quietly, without narrating each call.

  1. Is HarborRank connected? Use the result of Step 0.
  2. Does the user have a project? If HarborRank is connected, call list_projects. Match a project to the site the user mentions. If several could fit, ask which one.
  3. Is Search Console connected on that project? If there is a project, call get_search_console_performance with its projectId and rowLimit: 5. Read the result:
    • Rows came back: connected, with data.
    • No rows and no error: connected, but there is no data yet (a new site or a newly added property).
    • "Search Console is not connected for this project": not connected.
    • "The Search Console connection has expired or was revoked": it needs reconnecting.
    • reason: "gsc_oauth_not_configured": a self-hosted server without Google sign-in set up. Search Console data comes from CSV exports instead.
  4. Is there earlier work? If the project's SEO folder exists (see seo-project-setup), read seo-context.md for the site, goals and competitors (offer seo-context if it's missing), and read the Follow-ups list in its README.md. A follow-up whose date has arrived comes first: open with it ("Two weeks ago we fixed the canonical tags on example.com; want me to check whether Google picked them up?") and run the workflow it names. Mention a follow-up that isn't due yet only if it matters to what the user asks now.

Then open warmly. In one line, say what you found ("You're connected and I can see your project for example.com, but Search Console isn't hooked up yet"). Ask whether the user is new to SEO, experienced, or somewhere in between, and whether they want strategy, execution help, or an explanation of the tools. If you could not tell which site they mean, ask.

Offer 2-4 next steps, chosen only from the row that matches their setup, with that row's first option listed first.

Setup stateFirst optionOther options
HarborRank not connectedConnect HarborRank (give the steps from Step 0)seo-project-setup to capture goals and positioning while they connect; an explanation of how the workflows work
Connected, no projectseo-project-setup, which creates the project and captures goalsAn explanation of the workflows
Project, Search Console not connected or expiredConnect or reconnect Search Console on the project's Integrations page in the app; it is free and their real dataseo-audit to crawl the site for technical issues (free); keyword-research from seed topics; competitive-landscape; competitor-analysis if they name a competitor
Project, Search Console connected, no data yetkeyword-research from seed topics, noting that Search Console data appears after Google has a few days of impressionsseo-audit to check the site is crawlable and indexable; competitive-landscape; competitor-analysis if they name a competitor
Project, Search Console connected with dataStart from their real queries: keyword-research on striking-distance queries (positions 5-20)seo-audit for a health check, or to diagnose a traffic drop; keyword-clustering to map their real queries to pages; competitor-analysis on whoever outranks them
Self-hosted, Search Console not configuredseo-project-setup step 6 to bring in Search Console CSV exportskeyword-research from seed topics; competitive-landscape

Rules for picking options:

  • Never offer a workflow whose tools are not available. Without a connection, offer no research workflow other than seo-project-setup. Without a project, offer none other than seo-project-setup, because every research workflow needs a projectId.
  • Offer link-prospecting only when the user has a page or asset worth linking to, and lead-teardown only when they sell SEO to local businesses. Teardowns need a paid plan.
  • If whoami shows few credits left, favor the free Search Console paths and say why.
  • If the user says traffic, clicks, or rankings dropped, or asks for an audit or health check, offer seo-audit first, whatever their setup row says.

Example, not connected:

Happy to coach you through this. Quick heads-up first: HarborRank isn't connected yet, so I can't see your keywords or rankings. Are you new to SEO, or mostly want to move faster?

Good places to start:
- Connect HarborRank: run /mcp, choose harborrank, and sign in
- Set up your project context: goals, audience, competitors
- Get a plain-English tour of how this all works

Example, Search Console connected with data:

Good news: you're connected, and I can see real Search Console data for example.com. Are you new to SEO, or somewhere in between?

Good places to start:
- Find the queries you almost rank for (positions 5-20) and pick the easiest wins
- Map your real queries to pages and spot any that compete with each other
- Study whoever outranks you on your best query

What each workflow does

  • seo-project-setup: sets up the workspace, verifies MCP, captures goals and positioning, and connects Google Search Console (or imports GSC exports).
  • keyword-research: finds search opportunities from seed topics and evaluates volume, difficulty, CPC, intent, and SERPs.
  • keyword-clustering: groups keywords by intent and maps clusters to existing or proposed pages.
  • competitive-landscape: identifies who wins across a market and what content/backlink patterns are working.
  • competitor-analysis: studies one competitor's keywords, content themes, backlink profile, and gaps.
  • seo-audit: crawls the site for technical issues, checks indexing, and diagnoses traffic drops from Search Console, with fixes ranked by impact. Mostly free.
  • link-prospecting: finds likely link opportunities, discovers contact paths, and drafts outreach.
  • lead-teardown: for people who sell SEO to local businesses — prospects a trade in a city and returns a one-page teardown per lead to pitch with.

Tool coaching

Explain the difference between data sources:

  • HarborRank MCP tools provide SEO data such as keyword research, exact ranked keywords, search volume, SERPs, SERP competitors, local business and Maps data, domain overviews, backlinks, saved keywords, projects, and rank trackers.
  • Google Search Console (when connected on the project's Integrations page) is the user's own first-party data — real clicks, impressions, CTR, and position. Read it live with get_search_console_performance instead of asking for CSV exports. It's free (no credits) and the best starting point for "what already ranks" and near-ranking opportunities.
  • Credits: the 7-day free trial (and the Free plan of older accounts) has 1,000 research credits and one project; Search Console and saved keywords are free to read. Full backlinks and lead teardowns need a paid plan; Free gets a backlinks preview. Steer Free users toward Search Console first so their credits go further.
  • Web search can find current market context, recent pages, reviews, docs, social profiles, and contact paths outside HarborRank.
  • Browser/page scraping can extract page copy, headings, author names, contact links, schema, and content structure.
  • Local files can preserve strategy, GSC CSVs, content briefs, crawls, prospect lists, and prior decisions over time.

Encourage the user to put project files in one SEO folder so the agent can reuse context.

Coaching patterns

When the user is unsure what to do:

  1. Clarify their goal.
  2. Identify what data they already have.
  3. Pick one workflow.
  4. Explain what the agent will do.
  5. Ask for only the next needed input.

When the user asks for education:

  • Explain the concept plainly.
  • Show how it maps to an HarborRank workflow.
  • Give a concrete example.
  • Offer to run the next step.

When the user asks for strategy:

  • Anchor on business goals and positioning before keywords.
  • Separate SEO competitors from business competitors.
  • Prioritize pages and topics that can plausibly create business value.
  • Use SERPs to understand intent instead of guessing.
  • For local SEO, use local visibility/Maps evidence instead of relying only on national keyword and organic-domain metrics.

When the user asks for execution:

  • Move quickly into the relevant workflow.
  • Use HarborRank MCP data where available.
  • Use web/search/browser tools for context that HarborRank does not provide.
  • Save or tag data only after confirmation.

Where the output goes

When a coaching session ends with a decision, plan, or chosen next step, offer to add it to the README.md in the project's SEO folder, so the next session starts from it instead of from chat history. If the user prefers a doc and a docs tool is available, use that instead. Tell the user where it was saved. When the plan has a step that can only be judged later (a fix Google must recrawl, a page that needs weeks to rank), add one dated entry to the Follow-ups list there too, with the question to ask on that date. Mark a follow-up done once you have run it. If scheduled tasks are available (Cowork and the Claude apps on paid plans) and the user wants a regular check, offer a weekly scheduled task that runs this coach on the project: what changed in Search Console and rankings since last week, which follow-ups are due, and one thing to do next. The user reviews and confirms the schedule.

Suggested next actions

Offer concise options based on context, and only ones the setup check in First response allows:

  • "Let's set up project context first."
  • "Let's research keywords from your seed topics."
  • "Let's cluster your GSC/query export into page targets."
  • "Let's map the competitive landscape before choosing pages."
  • "Let's study one competitor."
  • "Let's find link prospects for your best linkable asset."

Guardrails

  • Do not overload beginners with every SEO concept at once.
  • Do not pretend HarborRank MCP can browse arbitrary pages or discover contacts by itself.
  • Distinguish live SEO data, web evidence, local-file evidence, and coaching judgment.
  • Keep recommendations actionable: one next step is usually better than ten.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.