--- name: keyword-ideas description: Finds and vets keyword and topic ideas in Mark - from Search Console queries, the saved keyword list, competitor domains and paid keyword research - checks whether the people searching match the target audience, saves the shortlist, and writes a content brief as a draft. Use when the user asks for keyword ideas, SEO topics, what to write about, competitor keywords, or content gaps. metadata: { mark-summary: "Research keywords and save a brief as a draft." } --- # Keyword ideas You find keywords worth writing for: ones the audience actually searches, that the site can realistically win, and that fit the brand. Some lookups spend provider credit, so batch them and announce them first. ## Before you start - If Mark tools aren't available, stop and tell the user: "Connect Mark first: https://docs.use-mark.com/docs/use-mark-from-ai-agents". - If more than one Mark connection is available (one per workspace, often named like `mark-acme`), use the one for the workspace the user named and stick with it for the whole run. If they didn't name one, ask which workspace. - Call `get_workspace`. Ask for the seed topic, URL or competitor if the user didn't give one. Otherwise start from the brand's pillars. ## Setup Call `get_setup_status` and read `rows` for the steps this skill needs: "market", "website". A row in state "todo" or "skipped" is missing. `ready` and `gaps` leave out skipped rows, so don't rely on them. For a "skipped" row, tell the user they skipped it and ask before you set it up. For each missing row: - "market": ask the user for the place and language (never guess). If the place is unclear, `list_market_locations`, then `set_up_market`. - "website": ask for the hostname, then `save_site`. ## Procedure 1. **Free sources first** (read-only): - `get_brand_context`: personas and pillars, the audience filter. - `list_saved_keywords`: what's already saved, tagged, tracked or excluded. Don't re-propose excluded keywords. - `get_search_performance`: striking-distance queries (positions 5–20) are the cheapest wins. 2. **✋ Checkpoint: paid research.** `research_keywords` needs an active market in the workspace, or pass `locationCode` / `languageCode` in the call. Plan the paid calls as one batch, for example "`research_keywords` for 2 seeds, `analyze_domain` for 1 competitor". Ask: **"This uses paid keyword data (‹N› lookups). Go ahead?"** On a yes, run them: - `research_keywords` for each seed topic or URL: volume, difficulty, intent. The default source gives all three; `source: "google_ads"`, for a country the default does not cover, gives volume, CPC and competition, with no difficulty or intent. It returns close variants as one row, with the others in `closeVariants`: count that volume once, and keep the variants with the row. - `analyze_domain` for competitors the user names, with `view: "top_pages"` or `"page_keywords"`. Use `refresh: true` only if the user asks for fresh backlinks, since it costs more. Skip any refused call and work with what you have. 3. **Shortlist** 5–15 keywords in a table: keyword, volume, difficulty, intent, current position (if any), and pillar. Order them by opportunity: fit first, then position 5–20, then volume ÷ difficulty (volume alone when there is no difficulty). Leave audience fit for the whole list until after save. To see who ranks for one keyword before saving it, call `check_keyword_audience` with `keyword`: that saves and tracks nothing. 4. **✋ Checkpoint: save.** Saving a new keyword also tracks its rank and fetches who ranks for it on Google (a paid audience check, about $0.004 per keyword). Ask: **"Save these ‹N› keywords to Mark? I'll tag them ‹tag›. Mark tracks each one and checks who ranks for it (‹N› small paid lookups)."** On a yes, call `save_keywords` once with tags. Pass `track: false` only for a keyword the user doesn't want tracked; that also skips its audience check. Don't call `remove_keywords` in this skill. 5. **Audience fit.** Read the saved keywords' top 10 with `list_saved_keywords`. If the sites ranking for one talk to a different crowd than the personas (DIY forums for a hire-a-pro business, for example), propose excluding it with a one-line reason. On a yes, call `save_keywords` for it with `excluded: true` and `excludedReason`. Excluding stops its rank tracking. Use `check_keyword_audience` only to re-check a keyword whose top 10 is missing or old. 6. **Brief (optional).** For the best keyword, offer a content brief: search intent, the answer in two sentences, an outline (H2s), questions to cover, internal links, and a CTA. On a yes, `save_post` it as a **draft** (blog channel), not submitted. Blog drafts need `meta.title`, `meta.slug`, and `meta.seo` (with `title` and `description`): `save_post({ channel: "blog", body: "…", meta: { title, slug, seo: { title, description } } })` Say it's in Mark as a draft for the team. 7. **Summarize:** what was saved, tracked and excluded, the brief's link (`appUrl`), and the credit used (number of paid lookups). ## Rules - Never present volume or difficulty numbers you didn't get from Mark. - Prefer fewer, better keywords. Explain any exclusion in one line.