admin/metatron-open-seo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add skills for agents (#211)

Browse Source 
* Add OpenSEO skills for keyword and link workflows

* Remove credit scare copy from MCP and skills

* Remove local skills test sandbox

* Format OpenSEO skill docs

* Disclose OpenSEO credit threshold for MCP research

* Tighten OpenSEO skill workflows
This commit is contained in:
Ben Senescu 2026-05-22 08:46:06 -04:00 committed by GitHub
parent 3456af12fe
commit 5cef024c68
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 663 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
.agents/skills/competitive-landscape/SKILL.md Normal file
View File

@ -0,0 +1,72 @@
---
name: competitive-landscape
description: Map SEO market leaders, winning content themes, keyword coverage, backlinks, and strategic gaps.
---
# OpenSEO Competitive Landscape
## Goal
Answer: "Who is winning this SEO market, what content is working for them, and where are the openings?"
Use this when the user wants a market-level view across several competitors. For a deep dive on one domain, use `competitor-analysis`.
## Required inputs
- `projectId`
- Topic, seed keywords, market/category, or user's domain
- Optional known competitors
- Optional location/language
## OpenSEO MCP tools
- `research_keywords`: discover representative market queries.
- `get_serp_results`: identify recurring ranking domains across target queries.
- `get_domain_overview`: size organic footprint for candidate leaders.
- `get_domain_keyword_suggestions`: find what each leader ranks for.
- `get_backlinks_overview`: compare backlink/referring-domain strength where relevant.
## Workflow
1. Define the market query set:
- Use provided keywords, or call `research_keywords` to build 5-10 representative queries.
- Include mixed intent: informational, commercial, comparison, and tool/software terms when applicable.
2. Call `get_serp_results` for the representative queries. Send at most 10 queries per call.
3. Identify recurring domains and group them by type:
- Direct product competitors
- Publishers/media
- Marketplaces/directories
- Communities/forums
- Documentation/resources
4. For the strongest recurring domains, call `get_domain_overview`; default to the top 3-5 domains before expanding.
5. For direct competitors and relevant publishers, call `get_domain_keyword_suggestions`; default to the top 3-5 domains before expanding.
6. Use `get_backlinks_overview` when backlink authority appears important or the user asks why a domain is winning. Backlinks may be unavailable if the account has not enabled that data; continue with SERP/domain evidence if it fails.
7. Synthesize patterns: content types, themes, SERP formats, authority advantages, and underserved angles.
## Output format
Start with the market read:
- Market leaders
- Most winnable opportunity area
- Biggest barrier to ranking
Then include:
| Domain | Type | Why they matter | Organic footprint | Winning themes | Weakness/gap |
| ------ | ---- | --------------- | ----------------- | -------------- | ------------ |
Add:
- Query set used
- Content formats that are working
- Keyword/theme gaps
- Backlink or authority observations
- Recommended next workflows: competitor analysis, keyword clustering, or content brief
## Guardrails
- Distinguish SEO competitors from business competitors.
- Do not overstate exact traffic when OpenSEO returns estimates.
- If using a small query set, call the result directional.
- Do not assume a publisher is a product competitor; label domain types clearly.

75
.agents/skills/competitor-analysis/SKILL.md Normal file
View File

@ -0,0 +1,75 @@
---
name: competitor-analysis
description: "Analyze one competitor's organic footprint, ranking keywords, content themes, backlinks, and gaps."
---
# OpenSEO Competitor Analysis
## Goal
Analyze one competitor deeply enough to decide what to learn from, avoid, counter-position against, or outrank.
Use this for a named competitor. For identifying the market leaders first, use `competitive-landscape`.
## Required inputs
- `projectId`
- Competitor domain
- User's domain when comparison is requested
- Optional topic/category/location/language
## OpenSEO MCP tools
- `get_domain_overview`: baseline organic traffic and keyword count.
- `get_domain_keyword_suggestions`: top ranking keywords and keyword themes.
- `get_backlinks_overview`: backlink/referring-domain profile.
- `get_serp_results`: validate direct head-to-head SERPs for important keywords.
- `research_keywords`: expand gaps or category terms when needed.
## Workflow
1. Call `get_domain_overview` for the competitor, passing provided location/language when supported.
2. If comparing to the user, call `get_domain_overview` for the user's domain too.
3. Call `get_domain_keyword_suggestions` for the competitor, passing provided location/language when supported.
4. Group competitor keywords into themes:
- Product/category terms
- Alternatives/comparisons
- Templates/tools/calculators
- Educational guides
- Branded demand
5. Call `get_backlinks_overview` for the competitor, especially if authority appears to explain rankings. Continue without backlink evidence if it is unavailable.
6. Use `get_serp_results` for important shared or target keywords to compare positioning, passing provided location/language when supported.
7. Produce an actionable plan:
- What they are doing well
- Where they are vulnerable
- Which pages/keywords to pursue
- What to avoid copying
## Output format
Start with:
- Competitor snapshot
- Biggest lesson
- Best opportunity to beat them
Then include:
| Area | Competitor pattern | Evidence | OpenSEO opportunity |
| ---- | ------------------ | -------- | ------------------- |
Include sections for:
- Top keyword themes
- Content/page types working for them
- Backlink/authority notes
- Head-to-head SERP observations
- Priority actions for the user
## Guardrails
- Do not treat all competitor keywords as desirable. Filter for business fit.
- Separate evidence from inference.
- Do not infer competitor page/content-type patterns from keyword rows alone; use SERP or web evidence for page-level claims.
- Do not recommend copying content; recommend a stronger angle or better answer to the same intent.
- If the user's domain is unavailable, frame the analysis as competitor-only.

71
.agents/skills/keyword-clustering/SKILL.md Normal file
View File

@ -0,0 +1,71 @@
---
name: keyword-clustering
description: Cluster keywords by intent and map them to existing or proposed pages.
---
# OpenSEO Keyword Clustering
## Goal
Group 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.
## Required inputs
- `projectId`
- A keyword list, saved keyword tag, seed topic, or target domain
- Optional existing URLs/pages to map against
If keywords are not provided, use `list_saved_keywords` for saved sets, `research_keywords` for seed discovery, or `get_domain_keyword_suggestions` when the user starts from a target domain.
## OpenSEO MCP tools
- `list_saved_keywords`: fetch an existing keyword set, optionally filtered by tags.
- `research_keywords`: expand a seed when the user starts from a topic.
- `get_domain_keyword_suggestions`: gather ranking keywords when the user starts from a domain.
- `get_serp_results`: validate whether keywords belong on the same page by checking SERP overlap and intent.
- `save_keywords`: optionally tag final clusters after user confirmation.
## Workflow
1. Gather the candidate keyword set.
2. Remove duplicates, irrelevant terms, and terms that clearly require a different product or audience.
3. Build clusters around intent and page type:
- Same SERP intent and similar ranking pages belong together.
- Different intent, buyer stage, or SERP format should be split.
- Similar words do not guarantee the same cluster.
4. For important borderline terms, use a small `get_serp_results` batch to check overlap.
5. Assign each cluster to:
- Existing URL, if supplied and appropriate
- New page recommendation, if no existing page fits
- Do-not-target / later bucket, if weak or off-strategy
6. Identify cannibalization risk when multiple pages would target the same intent.
7. Ask before applying cluster tags with `save_keywords`.
## Output format
Start with a short mapping summary:
- Number of clusters
- Pages to create
- Existing pages to update
- Cannibalization or consolidation issues
Then include:
| Cluster | Primary keyword | Secondary keywords | Intent | Target page | Priority | Notes |
| ------- | --------------- | ------------------ | ------ | ----------- | -------- | ----- |
For each cluster, include a recommended page brief:
- Page type
- Searcher problem
- Required sections
- Internal-link opportunities
- Save/tag suggestion
## Guardrails
- Do not over-cluster tiny keyword sets. If there are fewer than 10 usable terms, produce a simple map.
- Do not rely on lexical similarity alone. SERP intent wins.
- Do not replace tags broadly without explicit confirmation.
- If existing URL data is missing, label target pages as proposed.

62
.agents/skills/keyword-research/SKILL.md Normal file
View File

@ -0,0 +1,62 @@
---
name: keyword-research
description: "Discover keyword opportunities, evaluate metrics and SERPs, and save/tag promising terms."
---
# OpenSEO Keyword Research
## Goal
Turn seed topics into a prioritized keyword opportunity set using OpenSEO MCP data. The output should help the user decide what to target, what to save, and what to research next.
## Required inputs
- `projectId`
- One or more seed topics, products, pages, competitors, or audience problems
- Optional market/location/language
If `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.
## OpenSEO MCP tools
- `research_keywords`: primary discovery tool. Use 1-5 seeds per call and prefer 150 results unless the user asks for exhaustive research.
- `get_serp_results`: inspect SERPs for the top candidate terms, especially when intent is ambiguous.
- `list_saved_keywords`: avoid duplicating already-saved work or use existing tags as context.
- `save_keywords`: save selected keywords only after explicit user confirmation.
## Workflow
1. Normalize seeds into a small set of distinct research angles.
2. Call `research_keywords` for the seeds. Use bulk calls when possible.
3. Remove irrelevant, duplicate, branded-only, and off-intent terms.
4. Prioritize by practical opportunity, not volume alone:
- Strong match to the user's product/page/topic
- Clear search intent
- Reasonable difficulty
- Useful volume/CPC signal
- SERP where the user can plausibly compete
5. Use `get_serp_results` for high-potential or ambiguous keywords when SERP intent would change the recommendation; keep the default check small.
6. Present a shortlist and a longer opportunity table.
7. Ask before saving keywords. When saving, suggest concise tags such as `topic:<topic>`, `intent:<intent>`, or `page:<slug>`.
## Output format
Start with the highest-signal recommendation:
- Best opportunity theme
- Top keywords to target now
- Keywords to save
- Risks or SERP caveats
Then include a compact table:
| Keyword | Intent | Volume | KD | CPC | Priority | Notes |
| ------- | ------ | -----: | --: | --: | -------- | ----- |
End with next actions, including whether to run keyword clustering, create a content brief, or save the chosen keywords.
## Guardrails
- Do not invent metrics. If OpenSEO does not return a value, write `unknown`.
- Do not call `save_keywords` without explicit confirmation.
- Prefer business-fit and intent-fit over chasing the largest volume term.

105
.agents/skills/link-prospecting/SKILL.md Normal file
View File

@ -0,0 +1,105 @@
---
name: link-prospecting
description: Find link prospects, discover contact paths, and draft outreach from SERPs and backlink signals.
---
# OpenSEO Link Prospecting
## Goal
Find realistic pages, sites, and authors that might reference the user's page, product, study, guide, or tool. Use OpenSEO for prospect discovery, then use available web/search/browser tools for contact discovery.
## Required inputs
- `projectId`
- User domain or target URL
- Linkable asset, page, product, study, tool, or topic
- Optional competitors
- Optional market/location/language
## OpenSEO MCP tools
- `get_serp_results`: find ranking articles, listicles, resource pages, comparisons, and topical publishers.
- `get_backlinks_overview`: inspect competitor domain or page backlink/referring-domain patterns.
- `get_domain_overview`: qualify important prospect domains.
- `get_domain_keyword_suggestions`: understand what a prospect or competitor is known for.
- `research_keywords`: expand prospecting queries.
## Contact discovery tools
After OpenSEO identifies good prospects, use available non-OpenSEO browsing or search tools for public contact discovery. Depending on the client, this may be web search, page fetches, browser automation, or a search API.
Look for:
- Author byline pages
- Contact pages
- Editorial guidelines
- About/team pages
- LinkedIn, X, Bluesky, or other professional profiles
- Newsletter or publication masthead pages
- Public email addresses in page HTML or visible page text
- Structured data such as `Person`, `Organization`, `sameAs`, or `email`
Only record contact details that were actually found. Include the source URL for any email, profile, or contact form.
## Prospecting query patterns
Build queries from the asset/topic:
- `<topic> resources`
- `best <category> tools`
- `<competitor> alternatives`
- `<topic> statistics`
- `<topic> guide`
- `<topic> examples`
- `<topic> templates`
- `<topic> software`
- `<topic> for <audience>`
Use `get_serp_results` in batches for the most relevant patterns. Send at most 10 queries per call.
## Workflow
1. Clarify the linkable asset and the reason someone would reference it.
2. Build 5-10 prospecting queries by default.
3. Call `get_serp_results` for those queries.
4. If competitors are provided, call `get_backlinks_overview` for the strongest competitor domains or pages first. Continue without backlink evidence if it is unavailable.
5. Filter prospects:
- Keep topical relevance and editorial pages.
- Prioritize articles, directories, resource pages, comparisons, statistics pages, templates, and curated lists.
- Deprioritize homepages, login pages, thin affiliate pages, spam, unrelated forums, and direct competitors unless a comparison angle is valid.
6. For each good prospect, define the outreach angle:
- Broken/missing resource
- Better current data
- Useful tool/template
- Alternative or comparison inclusion
- Expert quote or supporting reference
7. For the strongest prospects, visit or search the prospect site to find the best contact path.
8. Draft outreach messages. If contact details were found, include the source. If not, list the next best contact-discovery path.
## Output format
Start with:
- Best outreach angle
- Highest-priority prospect type
- Any data limitations
Then include:
| Prospect URL | Site/domain | Source | Relevance | Suggested angle | Contact path | Priority |
| ------------ | ----------- | ------ | --------- | --------------- | ------------ | -------- |
Then provide 2-3 reusable outreach drafts:
- Resource/list inclusion
- Article update/reference suggestion
- Competitor alternative/comparison angle
## Guardrails
- Do not invent email addresses, social handles, or contact names.
- Do not say OpenSEO found contact details unless an OpenSEO tool returned them. Attribute contact discovery to the web/search/browser source used.
- If contact details are not available after a reasonable search, recommend specific discovery steps such as checking the author page, contact page, LinkedIn, X, or a reputable contact-enrichment tool.
- Avoid spammy mass outreach. Personalize by page and reason.
- Flag prospects that are direct competitors or likely paid placements.

163
.agents/skills/onboarding-checklist/SKILL.md Normal file
View File

@ -0,0 +1,163 @@
---
name: onboarding-checklist
description: Guide a new OpenSEO user through workspace setup, site goals, positioning context, MCP checks, SEO strategy, and Search Console data intake.
---
# OpenSEO Onboarding Checklist
## Goal
Help the user set up a durable SEO workspace and gather enough context for future OpenSEO workflows to be useful. This is an intake and readiness workflow, not a full audit.
## Tone
Be friendly, practical, and structured. Ask questions in small batches. Explain why each item matters only when useful. Do not overwhelm a beginner with jargon.
## Checklist
### 1. Pick a working folder
Suggest that the user choose or create a local folder for SEO work, for example:
- `~/SEO/<company-or-site>/`
- `~/Documents/SEO/<company-or-site>/`
- A repo or workspace folder if SEO work should live beside website/content files
Explain that keeping notes, exports, briefs, scraped pages, and reports in one folder helps the agent build context over time.
Recommended starter structure:
```text
seo-workspace/
README.md
gsc/
keywords/
competitors/
content/
outreach/
reports/
```
Do not create folders unless the user asks. If file tools are available and the user asks, create a simple structure and a short `README.md` with the current goals and known sites.
### 2. Collect website scope
Ask for:
- Primary website/domain
- Additional domains or subdomains
- Important products, services, categories, or pages
- Target countries/languages
- Whether the site is new, established, migrating, or recovering from a drop
- CMS or publishing workflow, if relevant
### 3. Capture goals
Ask the user what they want from SEO:
- More qualified leads
- More signups/trials
- More ecommerce revenue
- More newsletter/audience growth
- More brand/category awareness
- Recovery from traffic loss
- Better ranking for specific pages
Ask for success metrics and timeframe. If goals are vague, help turn them into measurable goals such as "increase non-branded organic signups" or "rank top 10 for 20 buying-intent terms."
### 4. Capture positioning and strategy context
Ask what research they have already done about the company, product, audience, and competitors. Request any notes, docs, customer interviews, positioning docs, pitch decks, landing pages, or strategy memos they can share.
Probe for:
- Who the product or site is for
- What pain it solves
- Why users choose it over alternatives
- Competitors and substitutes
- Strong opinions or positioning claims
- Best customers and bad-fit customers
- Existing content that already converts
- Topics they do not want to target
If the user has not done this yet, offer to help research positioning using the company website, competitor pages, reviews, forums, and web search.
### 5. Verify OpenSEO MCP
After the user has described the company, website, goals, and positioning, check that OpenSEO MCP is configured and mapped to the right project:
1. Use `whoami` if available.
2. Use `list_projects` to confirm the user can access projects.
3. Match the project to the website/domain they want to rank for.
4. If the project list is ambiguous, ask the user which project should be used.
5. If the MCP is unavailable, tell the user to connect OpenSEO MCP before continuing with live OpenSEO data.
Do not run research tools just to test connectivity; `whoami` and `list_projects` are enough.
### 6. Request Google Search Console export
Ask the user to export a CSV from Google Search Console and place it in the SEO working folder.
Recommended exports:
- Queries: last 3 months and last 16 months if available
- Pages: last 3 months and last 16 months if available
- Query + page combinations when possible
- Countries/devices if relevant
Ask them to drop files into `gsc/` and use names like:
```text
gsc/queries-last-3-months.csv
gsc/pages-last-3-months.csv
gsc/queries-last-16-months.csv
gsc/pages-last-16-months.csv
```
Explain that GSC data reveals existing impressions, near-ranking terms, cannibalization, and pages that already have search demand.
### 7. Inventory existing assets
Ask for or discover:
- Sitemap or important URL list
- Current blog/resources/content library
- Product/category/feature pages
- Existing keyword lists
- Current rank trackers
- Backlink or PR assets
- Linkable assets such as studies, templates, tools, datasets, calculators, or original opinions
### 8. Recommend first workflow
After intake, recommend one next OpenSEO workflow:
- `keyword-research`: when the user needs ideas from seed topics
- `keyword-clustering`: when they have keywords or GSC data to map to pages
- `competitive-landscape`: when the market is unclear
- `competitor-analysis`: when they know a competitor to study
- `link-prospecting`: when they have a linkable asset or target page
## Output format
Use a checklist with statuses:
| Step | Status | Notes | Next action |
| ---- | ------ | ----- | ----------- |
Then summarize:
- Working folder
- OpenSEO MCP/project status
- Sites in scope
- Goals
- Known positioning
- Uploaded data/files
- Recommended next workflow
## Guardrails
- Keep setup lightweight. The user should feel oriented, not assigned homework.
- Do not pretend a GSC CSV has been uploaded unless you can see it.
- Keep onboarding focused on setup and context unless the user asks for live research.
- If web search or scraping is used for positioning research, distinguish source evidence from inference.

105
.agents/skills/seo-coach/SKILL.md Normal file
View File

@ -0,0 +1,105 @@
---
name: seo-coach
description: Enter a friendly OpenSEO coach mode that explains workflows, recommends next steps, and helps users use agents, web search, scraping, and MCP data effectively.
---
# OpenSEO Coach
## Goal
Act as a friendly SEO coach for users working with OpenSEO and an AI agent. Help them understand what the workflows do, choose the right next action, and use the agent's full toolset effectively.
## 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
When this mode starts, orient the user:
- Ask whether they are new to SEO, experienced, or somewhere in between.
- Ask what site or project they are working on.
- Ask whether they want strategy, execution help, or explanation of the tools.
- Offer 2-4 concrete next options, not a long menu.
Example:
```text
I can coach you through this. Are you new to SEO, or do you mostly want help using OpenSEO faster?
Good starting points:
- Set up the onboarding checklist
- Find keyword opportunities
- Map keywords to pages
- Study a competitor
- Build link prospects for a page
```
## What each workflow does
- `onboarding-checklist`: sets up the workspace, verifies MCP, captures goals, positioning, and 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.
- `link-prospecting`: finds likely link opportunities, discovers contact paths, and drafts outreach.
## Tool coaching
Explain the difference between data sources:
- OpenSEO MCP tools provide SEO data such as keywords, SERPs, domain overviews, backlinks, saved keywords, projects, and rank trackers.
- Web search can find current market context, recent pages, reviews, docs, social profiles, and contact paths outside OpenSEO.
- 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 OpenSEO 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.
When the user asks for execution:
- Move quickly into the relevant workflow.
- Use OpenSEO MCP data where available.
- Use web/search/browser tools for context that OpenSEO does not provide.
- Save or tag data only after confirmation.
## Suggested next actions
Offer concise options based on context:
- "Let's run onboarding first so future work has context."
- "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 deep-dive 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 OpenSEO 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.

14
src/server/mcp/transport.ts
View File

@ -14,10 +14,16 @@ import { getPublicOrigin } from "@/server/mcp/public-origin";
import { registerOpenSeoMcpTools } from "@/server/mcp/server"; import { registerOpenSeoMcpTools } from "@/server/mcp/server";
function createOpenSeoMcpServer() { function createOpenSeoMcpServer() {
const server = new McpServer({ const server = new McpServer(
name: "OpenSEO MCP", {
version: "0.0.10", name: "OpenSEO MCP",
}); version: "0.0.10",
},
{
instructions:
"OpenSEO research tools use credits. Proceed with normal focused research, but ask the user for confirmation before planned batches over 2,000 credits.",
},
);
registerOpenSeoMcpTools(server); registerOpenSeoMcpTools(server);
return server; return server;