Returns a catalog of skills grouped by category. Use get_skill() to load
the full workflow recipe for any skill, then follow its steps using the
available MCP tools.

Categories: seo, content, ads, analytics, action, enterprise, geo, cua

The recipe includes step-by-step instructions, which tools to call, what data to gather,
and how to present results. Use this as a guide, not a rigid script — adapt steps based
on the user's actual needs.

Args:
    skill_id: The skill identifier (e.g. "seo/keyword_research", "content/blog_topic_ideas", "ads/google_ads/standard_campaign")

Returns the Unilytics skill-authoring best practices (progressive disclosure,
gotchas, sub-agents, measured-not-claimed gates, trigger descriptions, the
self-learning loop, and the VERBATIM-import rule) plus a starter SKILL.md
template. Grounded in how Claude Code's own skill system works. Call this when
the user asks you to create, port, or refactor a skill.

get_skill() returns the SKILL.md contract + the list of its reference_files
and data_files. Call this to load a specific one (e.g. "reference/keyword-
pipeline.md" or "data/verify_row.py") only when you reach the step that needs
it — keeps context lean. For a stored script, read it then run it.

Args:
    skill_id: The skill id (user/... or project/... for editable skills).
    path: The file path within the skill (e.g. "reference/competitor-analysis.md").
        `file_path` is accepted as an alias (matches the file tools).

Use this to author a skill from Claude, or to CUSTOMIZE a built-in (pass
extends="<builtin_skill_id>" and the built-in's body is seeded for you).

FILE LAYOUT (a skill is SKILL.md + supporting files — progressive disclosure):
  - SKILL.md        the always-loaded contract: workflow + definition-of-done.
                    Keep it lean; link to the files below, don't inline them.
  - reference/*.md  docs the agent READS on demand (style guides, pipelines).
  - data/*          assets the skill carries, including RUNNABLE scripts
                    (e.g. data/verify_row.py — a checker the agent reads and
                    EXECUTES as a gate). Put scripts and data files here, NOT
                    under reference/, so get_skill surfaces them as runnable.

Args:
    name: Skill name (becomes the slug). Required.
    skill_markdown: The SKILL.md contents (frontmatter + workflow). Required
        unless `extends` is given (then it's seeded from the built-in, but you
        may override).
    description: Short description (else taken from frontmatter).
    category: Category label (e.g. "seo", "content").
    scope: "user" (private to you) or "project" (shared with collaborators).
    project_id: Required when scope="project".
    extends: A built-in skill_id to copy as the starting point (Customize).
    visibility: "private" | "project" | "public".
    verbatim_source: When PORTING an existing document, pass the original text
        here. The store runs a coverage-based fidelity check and returns a
        report — a FAIL means content was SILENTLY CONDENSED (do not report
        "done"; re-port the missing segments). Splitting + intentional edits
        are allowed. Call author_skill() first for the full authoring guide.

Three composable ways to change files in ONE version. Prefer file_edits for
small changes — it sends only the changed text, not the whole file.

  file_edits   — surgical find/replace on an EXISTING file. Maps path ->
    list of edits, e.g.
        {"reference/style-guide.md": [{"find": "—", "replace": "-", "count": 5}]}
    Each `find` must match exactly `count` times (default 1); a 0-match or a
    count mismatch is rejected so you fix the string rather than write blind.
    Use a longer, unique `find` for a single edit, or set `count` to replace
    all occurrences. THIS IS THE CHEAP PATH for fixing a few characters.

  file_changes — create a new file or whole-file replace. Maps path ->
    full markdown, e.g. {"SKILL.md": "...", "reference/new.md": "..."}.
    Use for new files or large rewrites.

  delete_files — remove files, e.g. ["reference/old.md"]. SKILL.md can't be
    deleted (it is the contract).

FILE LAYOUT (where files go — get_skill surfaces them by these prefixes):
  - reference/*  docs the agent READS (style guides, pipelines, specs).
  - data/*       assets the skill CARRIES, incl. runnable scripts. Put a
                 checker like data/verify_row.py HERE (not reference/) so it
                 travels with the skill and get_skill lists it as runnable —
                 the agent then read_skill_file()s it and EXECUTES it as a gate.

Built-in skills are read-only — update is rejected; create_skill(extends=...)
first, then update that copy.

Args:
    skill_id: The editable skill id (user/... or project/...).
    file_changes: {path: markdown} — create/replace whole files.
    file_edits: {path: [{find, replace, count?}]} — surgical edits to existing files.
    delete_files: [path, ...] — files to remove.
    change_summary: Short note on what changed (for version history).
    expected_version: If set, the save fails with a conflict unless the
        skill is still at this version (safe concurrent editing).
    verbatim_source: When PORTING/refactoring existing content, pass the
        original text. The store returns a fidelity report on the resulting
        files — a FAIL means content was silently condensed (re-port the
        missing segments; don't claim done). Splitting + intentional edits OK.

Args:
    skill_id: The editable skill id (user/... or project/...).

Call this at the START of running a skill — it carries durable lessons,
workarounds, and user preferences that make each run better than the last.

Args:
    skill_id: The skill id (built-in like "seo/keyword_research", or user/project).

After completing a skill, ASK THE USER whether anything failed, could be done
better, or is worth remembering for next time. On their confirmation (they may
add items), append it here. Works for built-in skills too — the learning lives
on the per-skill memory, never modifying the built-in body.

Args:
    skill_id: The skill the learning belongs to.
    text: The learning/workaround/preference to remember (one concise entry).

Call this only when append_skill_memory returns memory_full. Read the memory,
distill the durable lessons into a concise summary, and pass it here — it
replaces the old entries with your summary.

Args:
    skill_id: The skill whose memory to compact.
    summary: The distilled summary of durable lessons to keep.

Args:
    domain: Domain to analyze (e.g. "example.com")
    country: Two-letter country code (default: "us")

Combines Serpstat keyword overview with Keywords Everywhere volume data.

Args:
    keyword: Keyword to research (e.g. "best crm software")
    country: Two-letter country code (default: "us")

Args:
    domain: Domain to check rankings for (e.g. "example.com")
    country: Two-letter country code (default: "us")
    page: Results page number (default: 1, 50 results per page)

Combines Serpstat backlink overview with Moz domain authority data.

Args:
    domain: Domain to analyze backlinks for (e.g. "example.com")

Args:
    domain: Domain to find competitors for (e.g. "example.com")
    country: Two-letter country code (default: "us")

Args:
    url: Full URL to audit (e.g. "https://example.com")
    strategy: "desktop" or "mobile" (default: "desktop")

If a URL is provided, also checks structured data (schema.org markup).

Args:
    domain: Domain to audit (e.g. "example.com")
    url: Optional specific URL to also check for schema markup

Args:
    keyword: Search query (e.g. "best project management tools")
    location_code: Google Ads location code (default: 2840 = United States)

Args:
    url: Full URL to audit (e.g. "https://example.com/page")

Args:
    domain: Domain to check (e.g. "example.com")
    country: Two-letter country code (default: "us")

Args:
    domain: Competitor domain (e.g. "competitor.com")
    country: Two-letter country code (default: "us")

Args:
    url: Full URL to scrape (e.g. "https://example.com/blog/post")
    include_metadata: Include meta tags and OpenGraph data (default: False)

Args:
    query: Research query (e.g. "latest SEO trends 2026")
    research_type: One of "general", "news", "brand_research", "competitor_audit"

Args:
    keywords: List of keywords to compare (e.g. ["chatgpt", "gemini", "claude"])
    time_range: Time period — "past_7_days", "past_30_days", "past_90_days", "past_12_months", "past_5_years"

Supports Facebook pages, Instagram profiles, YouTube channels, and Twitter/X profiles.

Args:
    url: Profile URL (e.g. "https://facebook.com/nike")
    platform: One of "facebook", "instagram", "youtube", "twitter"
    max_posts: Maximum recent posts to fetch (default: 10)

Queries multiple AI models with the same prompt and analyzes brand mentions.
Use this for Generative Engine Optimization (GEO) analysis.

Args:
    prompt: The question to ask AI models (e.g. "What is the best CRM for startups?")
    brand: Optional brand name to track in responses (e.g. "HubSpot")

Call this first to discover your project_id, then use list_connections()
to see connected data sources, and search_console_data() to query your data.

Call list_projects() first to get your project_id.

Args:
    project_id: The project UUID from list_projects()

Requires a connected GSC data source. Call list_projects() then list_connections()
to find your project_id and account_id.

Args:
    project_id: Your project UUID (from list_projects)
    account_id: GSC account ID (from list_connections, e.g. "sc-domain:example.com")
    endpoint: What data to fetch:
        - "top_pages": Top organic pages with clicks (last 3 months)
        - "queries": All search queries
        - "ranking_keywords": Keywords with click/impression metrics
        - "clicks_impressions": Click and impression data over time
        - "complete_data": Full GSC data with all dimensions (last 2 months)

Call this before running expensive workflows to make sure you have enough
credits. Each data tool call costs 0.10 credits. Discovery tools (list_projects,
list_connections, list_skills, get_skill) are free.

Requires a connected GA4 data source. Call list_projects() then list_connections()
to find your project_id and account_id.

Args:
    project_id: Your project UUID (from list_projects)
    account_id: GA4 property ID (from list_connections, e.g. "375869549")
    endpoint: What data to fetch:
        - "complete_data": Full analytics with device breakdown (last 2 months)
        - "sessions": Session and user metrics (last 3 months)
        - "conversions": Conversion and e-commerce metrics (last 3 months)
        - "device_breakdown": Metrics by device category (last month)
        - "traffic_acquisition": Traffic by source/medium (last 2 months)

Requires a connected Google Ads data source. Call list_projects() then list_connections()
to find your project_id and account_id.

Args:
    project_id: Your project UUID (from list_projects)
    account_id: Google Ads account ID (from list_connections, e.g. "123-456-7890")
    endpoint: What data to fetch:
        - "clicks_impressions": Click and impression totals (all time)
        - "campaign_performance": Campaign metrics with spend (last 3 months)
        - "ad_performance": Ad-level metrics with CPC (last month)
        - "complete_data": Full Google Ads data with all key metrics (last 2 months)
        - "keywords": Keyword performance — text, match type, clicks, impressions
        - "ad_copy": Ad creative copy — headlines, descriptions, final URLs

Takes seed keywords and returns related keyword ideas with monthly search
volumes, competition level, and trends. Uses the official Google Ads API.

Args:
    keywords: Seed keywords to generate ideas from (e.g. ["seo tools", "digital marketing"])

Returns ad creatives (text, image, video), target domains, and links to
the Google Ads Transparency Center for each ad.

Args:
    advertiser_name: Brand domain to search (e.g. "nike.com", "apple.com"). Use domain, not just brand name.
    region: Region code (default: "2840" = US). Common: "2356" India, "2826" UK, "2124" Canada, "2036" Australia.
    limit: Max ad creatives to return (default: 30, max: 100)

Returns active ad creatives, spend ranges, and targeting info.

Args:
    query: Brand or keyword to search (e.g. "Nike", "best crm software")
    country: Two-letter country code (default: "US")
    limit: Max results to return (default: 25)

Returns available audience segments filtered by type and optional search query.

Args:
    segment_type: Segment type — "IN_MARKET", "AFFINITY", or "LIFE_EVENTS"
    query: Optional filter (e.g. "fitness", "travel") to narrow results

Based on your keywords and industry, recommends in-market segments,
affinity audiences, demographics, and bid modifiers.

Args:
    keywords: Target keywords for the campaign (e.g. ["hotels in goa", "beach resorts"])
    campaign_type: "standard" or "pmax" (Performance Max). Default: "standard"
    industry: Business industry (e.g. "travel", "ecommerce", "saas"). Default: "general"

Unlike the standard scrape, this waits for JavaScript to fully execute
before extracting content. Use this for single-page applications, dynamic
content, or any page where content loads via JS.

Returns full SEO audit signals from the rendered HTML: title, meta tags,
headings, Open Graph, structured data, canonical, images, and issues.

Args:
    url: Full URL to scrape (e.g. "https://app.example.com")
    wait_for: Milliseconds to wait for JS to render (default: 5000, max: 15000)

Firecrawl processes all URLs in parallel — much faster than scraping one
by one. Use for competitor analysis, content gap analysis, SERP page
comparisons, link prospecting, or any task requiring data from multiple pages.

Returns markdown content and metadata for each URL.

Args:
    urls: List of URLs to scrape (max 10)
    js_rendering: Wait for JavaScript rendering on each page (default: False)

Recursively follows internal links from the starting URL. Use for site-wide
audits, content inventory, internal link analysis, finding orphan pages,
detecting missing meta tags across a site, or any task needing full-site data.

Returns per-page SEO signals: title, meta description, headings, issues.

Args:
    url: Starting URL (e.g. "https://example.com")
    max_pages: Maximum pages to crawl (default: 50, max: 100)

Fast URL discovery that maps out a site's structure. Use for sitemap
audits (compare against sitemap.xml), finding unindexed pages, understanding
site architecture, or scoping a crawl before running it.

Args:
    url: Website URL (e.g. "https://example.com")

Takes a rendered screenshot after JavaScript execution. Use for visual
audits, above-the-fold analysis, competitor page comparison, UX review,
or documenting current page state.

Args:
    url: Full URL to screenshot (e.g. "https://example.com")
    full_page: Capture full scrollable page vs viewport only (default: False)

Returns internal vs external links with anchor text, nofollow attributes,
and link counts. Use for link audits, outbound link analysis, internal
linking reviews, finding link building opportunities on competitor pages,
or checking nofollow distribution.

Args:
    url: Full URL to extract links from (e.g. "https://example.com/page")
    js_rendering: Wait for JavaScript rendering before extracting (default: False)

Use this to set up a project from Claude — then add tracked keywords/prompts
and upload files to it. Returns the new project_id (use it in later tool calls).

Args:
    name: The project / brand / business name (required).
    domain: The project's website URL (optional, e.g. "example.com").
    keywords: Keywords to track — a list, or a comma-separated string.
    competitors: Competitor domains — a list, or a comma-separated string.
    industry: The project's industry (optional).

Appends to the project's existing lists (no duplicates). Call list_projects()
first to get the project_id. At least one of keywords/competitors/locations
must be provided.

Args:
    project_id: The project UUID (from list_projects or create_project).
    keywords: Keywords to add — a list, or a comma-separated string.
    competitors: Competitor domains to add — a list, or comma-separated string.
    locations: Target locations to add — a list, or comma-separated string.

EXPECTED SHAPE — each prompt is an object with at minimum a `text` field:
    {"text": "best managed file transfer tools", "topic": "MFT",
     "tags": ["mft"], "prompt_type": "category"}
Only `text` is required. Optional: topic, tags (list or comma-string),
prompt_type ("brand"|"category", default "category"), regions, language,
personas, platforms, analysis_types.

If you have a sheet/CSV, MAP its columns to this shape before calling
(e.g. a "Prompt" column -> text, "Topic" -> topic, "Tags" -> tags). If this
tool returns a structured error, fix the data per the error and retry.

Args:
    project_id: The project UUID (from list_projects or create_project).
    prompts: List of prompt objects (see shape above).

A folder groups a related set of skills (e.g. a "Content Refresh" folder),
its knowledge-base files, and its memory — the project's working context.
Call list_projects() first for the project_id.

Args:
    project_id: The project UUID (from list_projects or create_project).
    name: The folder name (e.g. "Content Refresh").

Args:
    project_id: The project UUID (from list_projects).

Args:
    folder_id: The folder ID (from list_folders or create_folder).

This does NOT copy skill files — it records that this folder contains the skill.
Call list_folders() for folder_id; skill_id comes from the skill store (Phase 0/1).

Args:
    folder_id: The folder ID (from list_folders or create_folder).
    skill_id: The skill ID to attach.

Greedy centroid assignment on an ABSOLUTE shared-URL count (no transitive chaining). A join on
exactly one shared URL is allowed only if that URL is specific (low corpus document frequency),
is not a generic hub host, and the prompt is not a brand comparison — and such joins are NEVER
auto-accepted (they come back with needs_review=true). Query-drift SERPs are quarantined.
Page assignment is rank-weighted: a rank-1 brand hit outweighs a rank-10 one.

items = [{id, text, impressions?, serp: [{url, rank, near_miss}], serp_urls?: [...] (legacy),
          citation_urls?: [...] (a SEPARATE signal — never joins clusters), spell?, mapped_pages?}]
config = per-project {brand:{domain}, competitors[], cluster:{T, one_shared_max_df, hub_hosts,...},
         signals:{a_min_hits, a_high_confidence_max_rank}} — nothing client-specific is hardcoded.

Returns {clusters, assignments, n_items, n_clusters, needs_review, n_quarantined, caveat}.

Returns {results: [{url, rank, near_miss}], urls: [top-N urls], spell}. Fetches the top-20;
`near_miss` marks ranks beyond top_n (a real ranking, but weak evidence — use it to find
refresh candidates, not to claim the page ranks). `spell` carries Google's did_you_mean /
showing_results_for so callers can detect query drift.