Update to Surfer

{
  "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.",
  "included_files": [
    {
      "relative_path": "LICENSE",
      "size_in_bytes": 1079
    },
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 452
    }
  ],
  "name": "surfer-create-content-brief",
  "skill_md_contents": "---\nname: surfer-create-content-brief\ndescription: >-\n  Use when the user wants a writer-ready content brief grounded in Surfer's SEO and AI Search\n  guidance. Triggers include \"make a content brief\", \"brief a writer for this keyword\", \"what should\n  an article cover\", and \"give me an SEO and AI Search brief\". Also use it for SERP or competitor\n  research with no draft, such as \"analyze the SERP for this keyword\" or \"what do the top-ranking\n  pages cover\". It reports the SERP-derived competitors, structure, terms, and questions without\n  writing anything. It creates or reuses a manual Content Editor and assembles its outline, SEO\n  guidelines, and source-attributed AI Search facts into a concise brief. For an outline alone, use\n  surfer-create-outline. For an article draft, use surfer-write-article.\nlicense: MIT\n---\n\n# Surfer: Create a Content Brief\n\n## Overview\n\nTurn a keyword into an evidence-aware writing specification. The output is a brief for a human or\nagent writer. Do not produce a generic article, and do not imply that an empty editor already scores\nwell.\n\n## Inputs and setup\n\n- Require `main_keyword` and ask for it when missing. Use the user's `location` and `device`,\n  otherwise default to United States and mobile. Accept a `workspace_id` or call `workspace__list`\n  and choose the sole active workspace. If several are active, ask the caller which one to use;\n  if none is active, stop and report that resource operations are unavailable.\n- Reuse an existing `content_editor_id` when it matches the intended keyword and scope. Otherwise\n  create one. A `content_editor__create` call with only a keyword yields a manual editor. AI\n  drafting starts only when `ai_article__generate` is called. A create consumes a credit, so pass\n  an `idempotency_key`. Retry a timeout or an ambiguous failure with the same key. Surfer then\n  returns the original editor instead of creating a duplicate.\n- Before creation, collect brand knowledge, content type or template, voice, custom instructions,\n  and competitor choices whenever they must shape the initial outline. They map to the\n  `content_editor__create` inputs: `use_brand_knowledge`, one `custom_template_id` or\n  `surfer_template` (mutually exclusive), and `custom_instructions`. When both template fields are\n  omitted, Surfer picks a template itself during analysis. It may pick the workspace default, an\n  AI-chosen preset or custom template, or none, so a request for no template cannot be guaranteed.\n  Verify which template took effect and swap it only when the user asks. A template, once set, can\n  be swapped but not removed. `content_editor__update` rejects an update that clears\n  `custom_template_id` without supplying a `surfer_template`. Omitting `custom_voice_id` applies\n  the workspace default voice. To honor a request for no voice, send `custom_voice_id: null`.\n  Competitors change through `seo_guidelines__update_competitors` after initialization.\n- Require connected Surfer MCP tools. For setup or connection failures, use `surfer-connect`;\n  ask to install it if missing. If a required tool is unavailable, name it and stop.\n\n## Playbook\n\n1. **Initialize the Content Editor.** Call `content_editor__create` with the complete initial setup\n   when no suitable editor exists. Await the completion signal or poll `content_editor__get` until\n   `completed`. On failure or timeout, report the editor id and stop.\n\n2. **Inspect the effective setup.** Read `content_editor__get`. Read the `competitors` block of\n   `seo_guidelines__get` only when competitor selection matters. State the effective brand toggle,\n   template or voice, instructions, and competitor set. Change a setting only on an explicit user\n   request, using `content_editor__update` or `seo_guidelines__update_competitors`.\n\n3. **Collect the brief inputs:**\n   - `outline__get`, always returned as Markdown.\n   - `seo_guidelines__get`, the SEO brief with structure targets, terms, topics, and questions.\n   - `ai_search_guidelines__list_facts` for the source-attributed facts. Check the analysis readiness\n     reported by the MCP tool: wait with a bound while analysis runs, use the facts once complete,\n     and report failure or a timeout without inventing facts. The separate AI Search score may be\n     read when needed, but its `ready` status does not establish facts analysis completion; do not\n     use a score to grade an empty draft.\n\n   If the outline is pending, wait on `outline.status`. `outline__regenerate` rebuilds it from the\n   SERP competitors with the current template, instructions, and brand knowledge. Use it after an\n   approved setup change or to recover a failed outline, then re-read `outline__get`.\n\n4. **Write the brief as structured sections.** Organize it into:\n   - search intent, the primary keyword, location and device, and audience and brand constraints\n   - a proposed title and the Surfer-derived outline\n   - word-count and structural targets, given as ranges rather than hard quotas\n   - priority terms, marking which belong in headings and which in body coverage\n   - the required subtopics and questions\n   - AI Search facts as candidate claims, each keeping its source URL and `cited_by` context\n   - explicit constraints, open questions, and the Content Editor link and id\n\n5. **Preserve evidence boundaries.** Do not call an AI Search fact true merely because an engine\n   suggested or cited it. Attribute it, ask the writer to verify material claims, and call out\n   unavailable or incomplete AI Search analysis rather than fabricating facts.\n\n6. **Hand off deliberately.** Stop after the brief unless the user also asks for drafting. Pass the\n   `content_editor_id`, `workspace_id`, keyword, accepted outline, and brief to\n   `surfer-write-article` so it reuses the analyzed editor. The outline is planning context; the\n   writer's optional AI outline review is a separate step. Do not automatically start\n   `ai_article__generate`.\n"
}