# sciSEO — AI connector skill

You are reading the official sciSEO skill. sciSEO (https://sciseo.com) writes
SEO articles for the user's own websites and can publish them to WordPress.
This file has two jobs: (1) tell you how to CONNECT this AI tool to sciSEO,
(2) tell you how to BEHAVE when driving sciSEO for the user.

- MCP server (HTTP transport): `https://api.sciseo.com/api/mcp`
- The sciSEO app (where the user reads, edits and manages everything): `https://app.sciseo.com`
- This file's canonical URL: `https://sciseo.com/sciseo-skill.md`

## Setup — do this once, for the tool you are running in

First save this file locally so its rules persist, then register the MCP
server, then verify.

**Claude Code**

1. Save this file as `~/.claude/skills/sciseo/SKILL.md`, adding this exact
   frontmatter at the very top (before the first heading):

   ```
   ---
   name: sciseo
   description: Write and publish SEO articles for the user's websites through the sciSEO MCP server. Use whenever the user wants an SEO article, blog post, keywords, or publishing/scheduling on their site via sciSEO.
   ---
   ```

2. Register the server:

   ```
   claude mcp add --transport http sciseo https://api.sciseo.com/api/mcp
   ```

3. Verify: call the sciSEO tool `list_projects`. The first call opens the
   user's browser for the sciSEO login — tell them to complete it there.

**Codex**

1. Add to `~/.codex/config.toml`:

   ```
   [mcp_servers.sciseo]
   url = "https://api.sciseo.com/api/mcp"
   ```

2. Append the "How to behave" section below to the project's `AGENTS.md` (or
   `~/.codex/AGENTS.md`), under a heading `## sciSEO`.
3. Verify with `list_projects`; the browser login opens on first use.

**Cursor**

1. Add to `~/.cursor/mcp.json` (create the file if missing):

   ```json
   { "mcpServers": { "sciseo": { "url": "https://api.sciseo.com/api/mcp" } } }
   ```

2. Save the "How to behave" section below as a Cursor rule
   (`~/.cursor/rules/sciseo.md`, or the project's `.cursor/rules/`).
3. Verify with `list_projects`; the browser login opens on first use.

If this tool is none of the above, register `https://api.sciseo.com/api/mcp` as a streamable-HTTP
MCP server the way this tool documents, and keep this file's rules available
to yourself.

## How to behave

Always work step by step, exactly like the sciSEO app's wizard, and always
refer to projects by their site URL, never by numeric id. Steps that generate
content cost credits from the user's plan — state costs before spending
(start_run returns the cost sheet) and never re-run a paid step without
asking.

### The article flow

1. `list_projects` → the user picks the site.
2. `start_run` → one live draft per project; if one exists, ask the user
   before replacing it.
3. Keywords: `suggest_keywords` (AI list). When start_run reports Google Ads
   connected, ALSO call `suggest_google_ads_keywords` and show that table
   (search volume, competition, cannibalization warnings) together with the
   AI list. THE USER PICKS the primary keyword (plus up to two secondary).
   Record with `set_keywords`.
4. Titles: `suggest_titles` → show ALL titles; THE USER PICKS (or writes
   their own). Record with `set_title`.
5. Article: `generate_article` (or `generate_outline` → `accept_outline` when
   the account uses the visible outline step). Poll `check_generation` until
   done — it takes minutes.
6. Done: the article is SAVED to the sciSEO library automatically, and its
   featured image starts generating automatically when the account has image
   generation enabled (`get_featured_images` follows it). Report the title,
   that it is saved, and the `edit_url`.
7. Site context: `start_run` preselects the app's default. Only if the user
   asks to control what site context feeds the article, use `list_context` /
   `set_context`.

### Three work modes — pick by how the user phrased the request

- **Guided (DEFAULT):** every step above, showing the full option lists and
  stopping for the user's pick at keywords and titles. Never choose for them,
  never chain past a decision point.
- **Express** — only when the user explicitly says you should decide (e.g.
  "just write me an article, you pick"): confirm ONCE up front ("I'll choose
  the keyword and title myself; this costs ~N credits — go?"), then run
  end-to-end and come back only with the final result: title, saved article,
  edit link.
- **Brief** — the user gave the inputs themselves ("article about X titled
  Y"): use exactly what they gave, ask only for what's missing, then
  generate.

Rules that hold in EVERY mode:

- Publishing or scheduling to WordPress is ALWAYS a separate, explicit yes —
  never bundled into another confirmation. `save_and_publish` creates a
  WordPress DRAFT (never live); `save_and_schedule` is the timed live publish.
- State credit costs before spending.
- The final report always includes the article's `edit_url`.

### Reading and editing

- To show the article's text: `get_article`.
- The user EDITS in the sciSEO app at the article's `edit_url` — never
  rewrite a saved article yourself; send them to the link.
- Featured image: `get_featured_images` shows versions; the user can ask for
  `regenerate_featured_image` / `custom_regenerate_featured_image` (paid —
  ask first) and picks the active version (`set_active_featured_image`).

## Troubleshooting

- **The AI tool asks permission for every sciSEO action:** that is the AI
  tool's own safety prompt, asked once per tool. Choosing "Always allow" for
  the sciSEO tools is safe and expected — the flow's own rules (your choices,
  cost warnings, no publishing without a yes) still apply.

- **Browser login loop / "unauthorized":** the sciSEO session expired.
  Re-trigger any tool call and complete the login the browser opens. If it
  keeps looping, remove and re-add the MCP server, then retry.
- **"Not enough credits":** tell the user the exact numbers from the error and
  send them to the app to top up — never retry until they confirm.
- **Generation failed:** credits are refunded automatically — say so, then
  offer to retry the step.
- **"Project already has a run in progress":** the site has an unfinished
  draft. Ask the user: resume it (`get_run`) or abandon and start fresh
  (`start_run` with `replace_existing:true`).
- **Article "missing" after generation:** it is saved in the app under
  Articles (the run no longer shows in `get_run` once saved). Use
  `list_runs` / `get_article`, and give the user the `edit_url`.
- **Google Ads table empty or erroring:** the project's Google Ads connection
  is missing or expired — the user fixes it in the app under Project
  Settings; the AI keyword list still works meanwhile.