How to use a skill
You need no special syntax. A skill triggers from a natural request: The assistant matches the request to the surfer-write-article skill and runs the playbook. You can also name the skill: The assistant lists the available skills, each with its name and a description of when it applies, then fetches the playbook it picked.Skills served over MCP are not slash commands. The Surfer MCP server registers
tools only, and no MCP prompts. Your client does not show them in its slash
command list or prompts menu. Ask in plain language or name the skill in your
message.Locally installed skills can also appear as slash commands, depending on your
client. For example, in Claude Code, run
/surfer-write-article after
installing it from GitHub.Available skills
Which skill do I need?
- Nothing written yet and you want a finished draft: .
- Nothing written yet and you want a plan for a human writer: (adds SEO Guidelines and AI Search facts) or (headings only).
- Content already exists: .
- Setting standards for future content: .
- You do not know what to work on: . It lists the workspace’s recommendations, lets you pick one, and hands the work to
surfer-optimize-contentorsurfer-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.
- One-off direction for a single article: no skill either. It goes in the custom instructions that
surfer-write-articlecollects.
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.1
Confirms the setup before spending a credit
The assistant verifies the workspace you supplied or asks which one to use
when several are active. For a new editor, 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
2
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.
3
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
4
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. Enterprise and some older plans reserve an AI Article credit when it starts; other plans include AI Articles in the Content Editor. See Credits and limits. Only the version you approve goes
back, and nothing is written until you sign off.
5
Generates or continues the article
It starts a new draft or resumes the article already in progress. If a
response is lost, it checks for the article before taking further action.
It reports an unclear outcome and stops.After generation completes, it reads the stored draft and its SEO, AI Search,
and total scores. If the AI Search score shows
error or unavailable, see
Troubleshooting.6
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:
- Revises the draft against the guidelines and facts.
- Replaces the editor’s content with the revision.
- Re-reads the version Surfer stored (see Content Editors).
- Waits for the scores to recalculate.
7
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.
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. You can also read each playbook’sSKILL.md in the skills repository.
Get the skills from GitHub
surferseo/skills is the source repository for the playbooks bundled with Surfer MCP. The skills are MIT licensed, so you can inspect and adapt them. Install a local copy if your client does not load skills from the server or you want to control when your playbooks update. Local skills still need a connected Surfer MCP server. The repository also includessurfer-connect for setup and connection problems. It is available through local installation; the MCP server supplies the six workflow skills listed above.
1
Install the skills
With Node.js 22.20 or newer, run the skills CLI
from your project directory to install every Surfer skill, including connection setup:To install one workflow, replace
'*' with its name, such as
surfer-create-outline. Add -a codex or -a claude-code to target one
assistant.2
Connect Surfer
Ask your assistant to use
surfer-connect, or follow the setup guide for
your client. If Surfer is already connected, you can use
the workflow skills immediately.3
Update your local playbooks
When you want the latest versions, run this command from your project
directory to update installed skills:Local copies update through the CLI. Skills served over MCP update with the
server deployment.