Surfer

View saved version →

---
name: surfer-connect
description: >-
  Use when Surfer MCP tools are unavailable or the user asks to connect, install, or set up Surfer
  in their AI assistant. Triggers include "connect the Surfer MCP server", "add Surfer to this
  client", "install Surfer MCP", and "how do I sign in to Surfer". It follows the current client
  setup guide, verifies the connection, and returns to the interrupted surfer-* workflow.
license: MIT
---

# Surfer: Connect MCP

Connect Surfer MCP in the current client, verify it, and return to the interrupted workflow.

## MCP setup

Use the [Surfer MCP overview](https://devs.surferseo.com/mcp/overview) and
[quickstart](https://devs.surferseo.com/mcp/quickstart) as the source of truth for requirements.
Detect the current client and read its guide before configuring it; ask which client only when
it cannot be determined. Follow that guide's current endpoint, sign-in, and verification steps.

| Client | Setup guide |
|---|---|
| Claude Code | https://devs.surferseo.com/mcp/connect/claude-code |
| Claude web or desktop | https://devs.surferseo.com/mcp/connect/claude |
| ChatGPT web | https://devs.surferseo.com/mcp/connect/chatgpt-web |
| ChatGPT desktop (Work) | https://devs.surferseo.com/mcp/connect/chatgpt-desktop |
| Codex CLI or IDE | https://devs.surferseo.com/mcp/connect/codex |
| Cursor | https://devs.surferseo.com/mcp/connect/cursor |
| VS Code | https://devs.surferseo.com/mcp/connect/vs-code |
| Other clients | https://devs.surferseo.com/mcp/connect/other |

Use the client's normal connector settings or CLI. Show a manual configuration edit before
applying it. The user completes OAuth in their browser; never request their sign-in credentials.

## Verify and return

Confirm that Surfer tools are available and `workspace__list` succeeds. Registration
alone is not success; if a restart is required, report setup as pending until the tools are usable.

For connection errors, follow [troubleshooting](https://devs.surferseo.com/mcp/troubleshooting);
for access or quota issues, consult [credits and limits](https://devs.surferseo.com/mcp/credits-and-limits).

After verification, resume the interrupted workflow. If the user only
asked to connect, report what is usable and stop.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: surfer-content-recommendations
description: >-
  Use when the user wants to act on Surfer's site recommendations. Triggers include "what should I
  optimize next", "turn my Surfer recommendations into articles", "find a content opportunity and
  act on it", and "run the write or optimize workflow from my workspace". It selects
  recommendation-led Optimize or Write work and delegates drafting and optimization to the focused
  Surfer skills.
license: MIT
---

# Surfer: Act on Content Recommendations

## Overview

Turn a chosen, site-level recommendation into one Content Editor workflow without creating the same
work twice.

## Prerequisites

- Require connected Surfer MCP tools. For setup or connection failures, use `surfer-connect`;
  ask to install it if missing. If a required tool is unavailable, name it and stop.

## Playbook

1. **Establish scope.** Resolve an active `workspace_id` with `workspace__list`; recommendations
   are read per workspace. If several workspaces are active, ask the caller which one to use rather
   than guessing. If none is active, stop and report. Offer a brand review before optimizing:
   editors opened by `recommendation__optimize` always apply the workspace's brand profile, with no
   per-editor toggle, so read it with `brand__get` and write it with `brand__update` only with an
   approved replacement. Write recommendations are also generated from that profile, so an update
   shapes future generation runs, not the current list. Do not confuse "enabled for this editor"
   with inspecting the profile.

2. **List, explain, and select a recommendation.** Call `recommendation__list`, filtered with
   `type` when the user already chose `optimize` or `write` work. Present each candidate's page URL
   or keyword and its `score`. Scores order items within one type and are not comparable across
   types; the default ordering lists optimize items before write items, each block score-descending.
   An item whose `content_editor_id` is set is already being worked on, so offer to continue it
   rather than start over. An empty list may mean no source is configured:
   `meta.content_audit_configured` and `meta.topical_maps_configured` name which of Content Audit
   or Topical Maps is missing, so report that rather than a bare "no recommendations". Let the user
   choose. Auto-select only when the user states a clear rule, such as "highest-score optimize
   recommendation", and rank within one type only.

3. **Run the focused workflow.** The recommendation carries everything needed to act, and its
   `content_editor_id` marks the editor already covering it — never create a second editor for a
   covered item.
   - For an *optimize* item, hand its editor to `surfer-optimize-content`, skipping that skill's
     create step. Use `content_editor_id` when set. Otherwise confirm the spend, then call
     `recommendation__optimize` — the product's Optimize button. It opens the page's own Content
     Editor, connected to Content Audit so optimization progress tracks in the product, charges one
     Content Editor credit unless the page's editor was already paid for, and returns the refreshed
     item with `content_editor_id` set. Never import the page URL into a fresh editor instead; that
     disconnects the tracking. On an already-open conflict, re-list and use its editor id. If the
     tool explicitly says the editor is not ready yet, wait and retry `recommendation__optimize`
     with the same workspace and recommendation ids, bounded; re-listing alone will not open it.
     Stop on quota or other reported failures. After a lost or unclear response, re-list first and
     reuse the editor id if present. If bounded reads cannot establish the outcome, report it as
     indeterminate and stop instead of repeating the action.
   - For a *write* item, pass its `content_editor_id`, `workspace_id`, `main_keyword`, and `location`
     to `surfer-write-article` when the id is set. The writer verifies and reuse

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: surfer-create-content-brief
description: >-
  Use when the user wants a writer-ready content brief grounded in Surfer's SEO and AI Search
  guidance. Triggers include "make a content brief", "brief a writer for this keyword", "what should
  an article cover", and "give me an SEO and AI Search brief". Also use it for SERP or competitor
  research with no draft, such as "analyze the SERP for this keyword" or "what do the top-ranking
  pages cover". It reports the SERP-derived competitors, structure, terms, and questions without
  writing anything. It creates or reuses a manual Content Editor and assembles its outline, SEO
  guidelines, and source-attributed AI Search facts into a concise brief. For an outline alone, use
  surfer-create-outline. For an article draft, use surfer-write-article.
license: MIT
---

# Surfer: Create a Content Brief

## Overview

Turn a keyword into an evidence-aware writing specification. The output is a brief for a human or
agent writer. Do not produce a generic article, and do not imply that an empty editor already scores
well.

## Inputs and setup

- Require `main_keyword` and ask for it when missing. Use the user's `location` and `device`,
  otherwise default to United States and mobile. Accept a `workspace_id` or call `workspace__list`
  and choose the sole active workspace. If several are active, ask the caller which one to use;
  if none is active, stop and report that resource operations are unavailable.
- Reuse an existing `content_editor_id` when it matches the intended keyword and scope. Otherwise
  create one. A `content_editor__create` call with only a keyword yields a manual editor. AI
  drafting starts only when `ai_article__generate` is called. A create consumes a credit, so pass
  an `idempotency_key`. Retry a timeout or an ambiguous failure with the same key. Surfer then
  returns the original editor instead of creating a duplicate.
- Before creation, collect brand knowledge, content type or template, voice, custom instructions,
  and competitor choices whenever they must shape the initial outline. They map to the
  `content_editor__create` inputs: `use_brand_knowledge`, one `custom_template_id` or
  `surfer_template` (mutually exclusive), and `custom_instructions`. When both template fields are
  omitted, Surfer picks a template itself during analysis. It may pick the workspace default, an
  AI-chosen preset or custom template, or none, so a request for no template cannot be guaranteed.
  Verify which template took effect and swap it only when the user asks. A template, once set, can
  be swapped but not removed. `content_editor__update` rejects an update that clears
  `custom_template_id` without supplying a `surfer_template`. Omitting `custom_voice_id` applies
  the workspace default voice. To honor a request for no voice, send `custom_voice_id: null`.
  Competitors change through `seo_guidelines__update_competitors` after initialization.
- Require connected Surfer MCP tools. For setup or connection failures, use `surfer-connect`;
  ask to install it if missing. If a required tool is unavailable, name it and stop.

## Playbook

1. **Initialize the Content Editor.** Call `content_editor__create` with the complete initial setup
   when no suitable editor exists. Await the completion signal or poll `content_editor__get` until
   `completed`. On failure or timeout, report the editor id and stop.

2. **Inspect the effective setup.** Read `content_editor__get`. Read the `competitors` block of
   `seo_guidelines__get` only when competitor selection matters. State the effective brand toggle,
   template or voice, instructions, and competitor set. Change a setting only on an explicit user
   request, using `content_editor__update` or `seo_guidelines__update_competitors`.

3. **Collect the brief inputs:**
   - `outline__get`, always returned as Markdown.
   - `seo_guidelines__get`, the SEO brief with structure targets, terms, topics, and questions.
   - `ai_search_guidelines__list_

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: surfer-create-outline
description: >-
  Use when the user wants a Surfer-derived, SERP-informed article outline without a full draft.
  Triggers include "create an outline for X", "plan headings for this keyword", "make a Surfer
  outline", and "outline an article before writing". It creates or reuses a Content Editor in
  manual-writing mode, returns its SEO-oriented outline, and can verify the requested brand,
  template, instructions, and competitor choices. For a writer-ready plan that also includes AI
  Search facts, or for SERP or competitor research with no deliverable, use
  surfer-create-content-brief. For a complete AI-written draft, use surfer-write-article.
license: MIT
---

# Surfer: Create an Optimized Outline

## Overview

Produce the structural plan for a new article. The outline is SERP-derived. To add AI Search facts
to the writer's plan, use the content-brief workflow. A manual Content Editor is the source of
truth. Do not invoke `ai_article__generate` unless the user changes the request to a draft.

## Inputs

- Require `main_keyword`. Ask for it if it is missing.
- Use the user's `location` and `device`. Otherwise default to United States and mobile. Location and
  device are inputs to `content_editor__create`.
- Accept a `workspace_id` or resolve one with `workspace__list`. If several workspaces are active,
  ask the caller which `workspace_id` to use rather than guessing.
- Accept an existing `content_editor_id` to avoid spending another Content Editor credit.
- Treat brand knowledge, content type, custom instructions, template, voice, and competitor
  selection as setup choices collected before the create: `use_brand_knowledge`, one
  `custom_template_id` or `surfer_template` (mutually exclusive), and `custom_instructions` are
  `content_editor__create` inputs. When both template fields are omitted, Surfer picks a template
  itself during analysis. It may pick the workspace default, an AI-chosen preset or custom
  template, or none, so a request for no template cannot be guaranteed. Verify which template took
  effect and swap it only when the user asks. A template, once set, can be swapped but not removed.
  `content_editor__update` rejects an update that clears `custom_template_id` without supplying a
  `surfer_template`. Omitting `custom_voice_id` applies the workspace default voice. To honor a
  request for no voice, send `custom_voice_id: null`. Competitors are changed with
  `seo_guidelines__update_competitors` after initialization.
- Require connected Surfer MCP tools. For setup or connection failures, use `surfer-connect`;
  ask to install it if missing. If a required tool is unavailable, name it and stop.

## Playbook

1. **Create or reuse the editor.** Reuse the supplied `content_editor_id` after confirming it targets
   the requested keyword and workspace. Otherwise call `content_editor__create` once with the
   complete initial setup: the keyword, location, device, `use_brand_knowledge`, any selected
   template or voice, and `custom_instructions`. A create consumes a credit, so pass an
   `idempotency_key`. Retry a timeout or an ambiguous failure with the same key. Surfer then
   returns the original editor instead of creating a duplicate.

2. **Wait for analysis.** Await the completion signal or poll `content_editor__get` until `state` is
   `completed`. On a `failed` state or a bounded timeout, report the editor id and its terminal or
   indeterminate state instead of retrying forever.

3. **Verify setup without silently changing it.** Read `content_editor__get`. For a requested
   competitor review, read the `competitors` block of `seo_guidelines__get`. Report the effective
   brand toggle, template or voice, instructions, and included competitors. Apply a change only when
   the user requested it. Use `content_editor__update` for editor settings and
   `seo_guidelines__update_competitors` for an explicit competitor selection.

4. **Retrieve the outline.** Call `outline__get`. 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: surfer-manage-content-templates
description: >-
  Use when the user wants to create, inspect, update, choose, or delete a reusable Surfer content
  template. Triggers include "create a custom template", "turn this article into a Surfer template",
  "list our templates", "set a default template", and "update or delete a content template". For a
  writing style or tone profile, use custom voices. For one article's direction, use the custom
  instructions in surfer-write-article.
license: MIT
---

# Surfer: Manage Content Templates

## Overview

Manage reusable structural examples safely. A template is a reference text that future Content
Editors reuse for structure. The Boundaries section separates it from a voice profile and a one-off
prompt.

## Boundaries

- A template is the reusable organization, sections, formatting, and recurring document shape.
- A custom voice is the reusable tone and style. Manage it with `custom_voice__*` when that is the
  actual request.
- Custom instructions are one editor's editorial or factual direction. Pass them through
  `content_editor__create` or `content_editor__update`.
- A Surfer template is a read-only predefined template from `surfer_content_template__list`. Never
  try to update or delete it.

## Prerequisites

- Resolve the workspace with `workspace__list`. If several workspaces are active, ask the caller
  which `workspace_id` to use rather than guessing.
- Require connected Surfer MCP tools. For setup or connection failures, use `surfer-connect`;
  ask to install it if missing. If a required tool is unavailable, name it and stop.
- Do not create a template until the user supplies or approves its name and reference text.

## Playbook

1. **Inspect before mutating.** Use `content_template__list` to find a similarly named custom
   template. Use `content_template__get` before changing a specific template. List predefined options
   with `surfer_content_template__list` when the user wants to compare rather than create a duplicate.

2. **Prepare a high-signal reference.** Keep stable structure, heading hierarchy, formatting, and
   representative phrasing. Remove stale facts, client secrets, and accidental product claims.
   Preserve only material the user is authorized to reuse. Do not bury changing campaign details in a
   shared template. Create and update both require a `reference_text` of 1 to 25,000 characters and
   at least 200 words. When the reference falls short of 200 words, ask the user for more material
   or for approval to expand it. Never pad the reference silently to clear the floor.

3. **Create safely.** Call `content_template__create` with `name`, `reference_text`, and
   `default: false` unless the user explicitly requests a workspace default. Pass an
   `idempotency_key`. Retry a timeout or an ambiguous failure with the same key. Surfer then
   returns the original template instead of creating a duplicate. Read the created template
   afterward to confirm its id and stored reference text.

4. **Update intentionally.** Read the target first, show the proposed changes to name, reference, and
   default, then call `content_template__update`. Treat changing the default as a workspace-wide
   behavior change, and require explicit user confirmation immediately before it.

5. **Delete only with confirmation.** Identify the exact template by id and name, explain that
   deletion is destructive, and call `content_template__delete` only after the user confirms that
   exact target. Never infer a deletion from a request to "clean up templates."

6. **Make selection explicit.** Return the template id and workspace. To apply it to a new article,
   pass the chosen `custom_template_id` to `content_editor__create`. Do not combine it with
   `surfer_template`, because the two are mutually exclusive.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: surfer-optimize-content
description: >-
  Use when the user has existing content, a URL or a draft, and wants to improve its Surfer SEO
  Score, AI Search Score, or both. Triggers include "optimize my article", "improve this page's
  content score", "auto-optimize this", "make this rank better", "optimize for SEO and AI search",
  and "improve my AI or LLM visibility". For writing a new article from scratch, use
  surfer-write-article instead.
license: MIT
---

# Surfer: Optimize Existing Content

## Overview

Raise the Surfer score dimensions the user selected for a page or draft, working through a Content
Editor. Treat the unified Content Score as a diagnostic snapshot. Optimize against the explicit SEO
or AI Search targets the user cares about.

## Prerequisites

- Require connected Surfer MCP tools. For setup or connection failures, use `surfer-connect`;
  ask to install it if missing. If a required tool is unavailable, name it and stop.
- Resolve an active `workspace_id` with `workspace__list`. If several workspaces are active, ask
  the caller which `workspace_id` to use rather than guessing.
- Require a target keyword and either an import URL or raw HTML or Markdown. Ask for a missing
  keyword rather than guessing it from the page alone.
- Ask which dimensions matter: SEO, AI Search, or both. If the user says only "optimize", default to
  SEO 70+. If they ask for both and give no targets, default to 70+ for each and say so. A missing
  AI Search score does not mean zero.
- Treat brand knowledge, content type or template, custom instructions, and competitor selection as
  Content Editor setup, collected before the create: the brand profile is applied through the
  `use_brand_knowledge` toggle and cannot be inspected or edited from here, the content type is one
  `custom_template_id` or `surfer_template` (mutually exclusive), instructions go in
  `custom_instructions`, and competitors are read and changed through `seo_guidelines__get` and
  `seo_guidelines__update_competitors`. When both template fields are omitted, Surfer picks a
  template itself during analysis. It may pick the workspace default, an AI-chosen preset or custom
  template, or none, so a request for no template cannot be guaranteed. Verify which template took
  effect and swap it only when the user asks. A template, once set, can be swapped but not removed.
  `content_editor__update` rejects an update that clears `custom_template_id` without supplying a
  `surfer_template`. Omitting `custom_voice_id` applies the workspace default voice. To honor a
  request for no voice, send `custom_voice_id: null`.

Use bounded waits only. On an explicit failure, an unavailable score, or a timeout, report the id
and state. Never poll indefinitely.

## Playbook

1. **Create or reuse a Content Editor.** Reuse a matching editor through `content_editor__list` when
   the user supplies one or asks to continue it. Omit `workspace_id` on that list call for an
   org-wide search. Otherwise call `content_editor__create` once with `main_keyword`, location,
   device, the full initial setup, and `import_content_url` for a live page. Default the location to
   United States and the device to mobile. For pasted text, omit the import URL and load the body
   after initialization. A create consumes a credit, so pass an `idempotency_key`. Retry a timeout
   or an ambiguous failure with the same key. Surfer then returns the original editor instead of
   creating a duplicate.

2. **Wait and verify the setup.** Await the completion signal or poll `content_editor__get` until
   `state` is `completed`. Read `content_editor__get`. If the user asked to review competitors,
   read the `competitors` block of `seo_guidelines__get`. Report the effective brand toggle,
   template or voice, instructions, and competitors. Apply changes only after user approval, with
   `content_editor__update` or `seo_guidelines__update_competitors`, then re-read the affected
   guidelines.

3. **Load con

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: surfer-write-article
description: >-
  Use when the user wants Surfer to produce a brand-new article or blog post from a keyword or topic.
  Triggers include "write an SEO article about X", "draft optimized content for this keyword",
  "generate a Surfer AI article", and "write for SEO and AI Search". To improve content that already
  exists, use surfer-optimize-content. For a writer brief without a draft, use
  surfer-create-content-brief.
license: MIT
---

# Surfer: Write an Optimized Article

## Overview

Turn a keyword into a new, AI-authored draft grounded in Surfer's SEO and AI Search analysis. When
the user wants only an outline or a brief, create a manual Content Editor and stop before
`ai_article__generate`.

## Prerequisites

- Require connected Surfer MCP tools. For setup or connection failures, use `surfer-connect`;
  ask to install it if missing. If a required tool is unavailable, name it and stop.
- Use the `workspace_id` supplied by the user or the handoff, and verify it is active with
  `workspace__list`. If none was supplied, use the sole active workspace or ask the caller to
  choose when several are active.
- Accept an existing `content_editor_id` as a first-class input, especially from a recommendation,
  outline, or brief handoff. Require `main_keyword` for a new editor; for an existing editor, read
  its keyword and accept up to 19 secondary keywords. Default the location to United States and the
  device to mobile only when creating. Location and device are inputs to `content_editor__create`.
- Before creation, collect the optional `target_word_count`, any SEO or AI Search score targets,
  and `manual_outline`, which is an `ai_article__generate` input. Collect the full editor setup as
  well: the `use_brand_knowledge` toggle (it applies the workspace's brand profile, which cannot be
  inspected or edited from here), one `custom_template_id` or `surfer_template` as the content type
  (mutually exclusive), and `custom_instructions`. When both template fields are omitted, Surfer
  picks a template itself during analysis, so a request for no template cannot be guaranteed.
  Omitting `custom_voice_id` applies the workspace default voice. To honor a request for no voice,
  send `custom_voice_id: null`. Competitors are read from the `competitors` block of
  `seo_guidelines__get` and changed with `seo_guidelines__update_competitors` after initialization.
- Treat "AI writing mode" as the `ai_article__generate` call rather than a `content_editor__create`
  field. Leave it out for manual work.

## Playbook

1. **Reuse or create the Content Editor.** When `content_editor_id` is supplied, read it with
   `content_editor__get` in the selected workspace. Verify the keyword and any location, device, or
   setup constraints the user supplied; report a mismatch before generating. Keep its existing
   settings unless the user requested a change. Reuse it for a continuation or a first draft from
   an outline or brief. An explicit request for another, separate article takes priority: create a
   fresh editor with the requested setup. Otherwise, if no id was supplied, look for a matching
   editor the user asked to continue and call `content_editor__create` only if none applies.
   Include the keyword, location, device, selected brand toggle, template or voice, and custom
   instructions. A create consumes a credit, so use one `idempotency_key` for that logical create
   and reuse it after an ambiguous response. If no template is selected, keep the one Surfer chooses
   during analysis.

2. **Wait for initialization.** Await the completion signal or poll `content_editor__get` until
   `state` is `completed`. Report a failure or a bounded timeout with the editor id.

3. **Review the content plan before drafting.** Read `seo_guidelines__get`, one brief with the terms,
   structure targets, topics, questions, and competitors. Read `ai_search_guidelines__list_facts`
   when AI Search is a goal. Read `content_editor__ge

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.