> ## Documentation Index
> Fetch the complete documentation index at: https://devs.surferseo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Run a complete Surfer workflow from one request with built-in playbooks.

export const Prompt = ({text}) => {
  const copyIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg>';
  const checkIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M20 6 9 17l-5-5"></path></svg>';
  const copy = event => {
    const button = event.currentTarget;
    if (!navigator.clipboard) return;
    navigator.clipboard.writeText(text).then(() => {
      button.innerHTML = checkIcon;
      button.setAttribute('aria-label', 'Copied');
      clearTimeout(button.resetTimer);
      button.resetTimer = setTimeout(() => {
        button.innerHTML = copyIcon;
        button.setAttribute('aria-label', 'Copy prompt');
      }, 2000);
    }).catch(() => {});
  };
  return <div className="surfer-prompt not-prose">
      <div className="surfer-prompt-meta">
        <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
          <path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2" />
          <circle cx="12" cy="7" r="4" />
        </svg>
        <span>Prompt</span>
      </div>
      <div className="surfer-prompt-bubble">
        <p className="surfer-prompt-text">{text}</p>
        <button type="button" className="surfer-prompt-copy" aria-label="Copy prompt" onClick={copy}>
          <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
            <rect width="14" height="14" x="8" y="8" rx="2" ry="2" />
            <path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" />
          </svg>
        </button>
      </div>
    </div>;
};

A skill is a markdown playbook the Surfer MCP server ships. Your assistant reads it and executes it with the server's tools, pausing where your input matters. You ask for the outcome and the playbook carries the steps you would otherwise prompt one by one.

Playbooks update when the server updates. There is nothing to install.

## How to use a skill

You need no special syntax. A skill triggers from a natural request:

<Prompt text="Write an SEO article about invoice automation for the Acme workspace." />

The assistant matches the request to the surfer-write-article skill and runs the playbook. You can also name the skill:

<Prompt text="Use the surfer-optimize-content skill on this draft." />

The assistant lists the available skills, each with its name and a description of when it applies, then fetches the playbook it picked.

<Note>
  Skills are not slash commands. The Surfer MCP server registers tools only, and
  no MCP prompts. Your client does not show skills in its slash command list or
  prompts menu. Ask in plain language or name the skill in your message.
</Note>

If your assistant cannot find any skills, its cached tool list is stale; [Troubleshooting](/mcp/troubleshooting#the-assistant-cannot-see-a-tool-surfer-shipped-recently) has the refresh step for each client.

## Available skills

| Skill | Use it when | Example ask |
| - | - | - |
| surfer-write-article | You want a new AI-written article from a keyword or topic. | "Write an SEO article about invoice automation." |
| surfer-optimize-content | You have existing content, a URL or a draft, and want to raise its SEO or AI Search content score, or both. | "Optimize my article." |
| surfer-create-content-brief | You need a writer-ready brief (outline, SEO Guidelines, and source-attributed AI Search facts), or SERP and competitor research with no draft. | "Brief a writer for 'invoice automation'." |
| surfer-create-outline | You want a SERP-derived heading structure without a full draft. | "Plan headings for 'invoice automation'." |
| surfer-manage-content-templates | You want to create, inspect, update, choose, or delete a reusable content template. | "Turn this article into a Surfer template." |
| surfer-content-recommendations | You want Surfer to pick what to optimize or write next from its recommendations and run the matching workflow. | "What should I optimize next in the Acme workspace?" |

## Which skill do I need?

* Nothing written yet and you want a finished draft: surfer-write-article.
* Nothing written yet and you want a plan for a human writer: surfer-create-content-brief (adds SEO Guidelines and AI Search facts) or surfer-create-outline (headings only).
* Content already exists: surfer-optimize-content.
* Setting standards for future content: surfer-manage-content-templates.
* You do not know what to work on: surfer-content-recommendations. It lists the workspace's recommendations, lets you pick one, and hands the work to surfer-optimize-content or surfer-write-article.
* Setting a writing style or tone profile: no skill. That is a custom voice, not a template, so manage voices with the [voice tools](/mcp/tools/index#templates-and-voices).
* One-off direction for a single article: no skill either. It goes in the custom instructions that surfer-write-article collects.

Use a skill by default for the six workflows above. Drop to free-form prompts for what the playbooks do not cover: AI Tracker reads, reporting, workspace administration, or a single tool call. [Use cases](/mcp/use-cases) has example prompts for those.

## What happens when you run one

This is what the surfer-write-article playbook does, stage by stage. The playbook's own numbering groups the work slightly differently; ask your assistant to show you the playbook for the exact wording.

<Steps>
  <Step title="Confirms the setup before spending a credit">
    The assistant lists your workspaces and asks which one to use when several
    are active. It collects:

    * The main keyword, plus up to 19 secondary keywords
    * The location (default United States) and device (default mobile)
    * Whether to apply your brand knowledge
    * One template, a Surfer preset or one of your workspace's own
    * A voice
    * Custom instructions
    * Any word count or score targets

    Creating a Content Editor uses one Content Editor credit, and the playbook
    makes the create request safe to retry ([Credits and
    limits](/mcp/credits-and-limits#tools-that-consume-credits)).
  </Step>

  <Step title="Waits for SERP analysis">
    Creating the Content Editor takes time; the assistant waits for
    it or checks its progress, whichever your client supports. It reports
    a failure or a bounded timeout together with the editor id.
  </Step>

  <Step title="Reviews the content plan">
    It reads three things:

    * The SEO Guidelines: terms, structure targets, topics, questions, competitors
    * The AI Search facts, when AI Search is a goal
    * The editor itself, to confirm the brand toggle, template or voice, and instructions took effect

    If you ask for different competitors, it updates the competitor list and
    re-reads the guidelines before writing.
  </Step>

  <Step title="Pauses for your outline approval">
    When you ask for a reviewable outline, the assistant starts the article in
    manual outline mode. Generation pauses once the outline is drafted, and the
    assistant fetches it and shows it to you. Starting generation reserves an AI Article credit on plans that charge separately; see [Credits and limits](/mcp/credits-and-limits). Only the version you approve goes
    back, and nothing is written until you sign off.
  </Step>

  <Step title="Generates the article">
    It starts generation and waits while the article moves through outline
    drafting and writing. Then it reads the stored draft and its SEO, AI Search,
    and total scores. A score counts only once it is ready; an AI Search score
    that reports an error or is unavailable is reported, not retried.
  </Step>

  <Step title="Iterates toward your targets">
    If you set an SEO or AI Search score target and it is unmet, the assistant
    revises in rounds. Each round:

    1. Revises the draft against the guidelines and facts.
    2. Replaces the editor's content with the revision.
    3. Re-reads the version Surfer stored (see [Content Editors](/mcp/tools/index#content-editors)).
    4. Waits for the scores to recalculate.

    It stops after 3 to 5 rounds or when the score plateaus, and it does not
    chase the unified total.
  </Step>

  <Step title="Hands off">
    You get the content, the SEO, AI Search, and total scores separately, the
    Content Editor id, and an edit or share link to the editor.
  </Step>
</Steps>

Every skill follows the same pattern: confirm inputs, execute, pause where your judgment is needed, deliver with links back to Surfer. Which of the steps consume credits is on [Credits and limits](/mcp/credits-and-limits).

Tools: [workspaces](/mcp/tools/index#workspaces-and-brand), [Content Editors](/mcp/tools/index#content-editors), [guidelines](/mcp/tools/index#guidelines), [AI Articles](/mcp/tools/index#writing-and-optimizing), [templates and voices](/mcp/tools/index#templates-and-voices).

## Inspect a playbook

Ask your assistant to list the available skills or show you a playbook before running it. Reading a playbook spends no credits.

<Prompt text="Show me the surfer-write-article playbook before you run it." />

The playbooks mention an API key for their standalone REST setup. Over MCP, your connection is already signed in; you do not need an API key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.