agentleFS
ai-search-guruai-search-guru/getcito-worlds-first-open-source-aio-aeo-or-geo-tool/skills/getcito-aeo-coach-standalone/SKILL.md

getcito-aeo-coach-standalone

Skill432 starsChanged 12 days agoMITView on GitHub

Standalone (no-MCP) version of the GetCito AEO Coach. Use this only when the user's Claude client cannot connect to the GetCito MCP server (e.g. claude.ai web without a Connector configured). Fetches live data from the GetCito REST API directly with the user's API key via code execution — visibility, competitors, citations, prompts, content gaps, page audits, the Action Center, and mentions and sentiment. For clients that support MCP (Claude Desktop, Claude Code, Cursor, Zed), prefer the `getcito-aeo-coach` skill — it's a cleaner UX because tool calls are first-class instead of inline Python.

  • Reads credentials

The file

Show its rules and text

We split this skill into the rules it gives an agent

35 rules. About 0 are common, 12 are distinctive, and 23 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈12

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 23

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    All paths below are under {base_url}/api/mcp and need the header Authorization: Bearer {api_key}.

    line 125
  2. Distinctive:

    Use it to confirm the key works if a call fails unexpectedly.

    line 202
  3. Very specific:

    If a request returns a non-2xx status, the response body usually has an error field — relay it to the user instead of guessing.

    line 253
  4. Distinctive:

    When the user asks for a general status check:

    line 268
  5. Very specific:

    If they didn't name a brand, call GET /brands.

    line 270
  6. Very specific:

    Call GET /visibility-summary with date_from set to 7 days ago (ISO format, e.g.

    line 273
  7. Very specific:

    Call it again for the previous 7 days (date_from 14 days ago, date_to 7 days ago).

    line 276
  8. Very specific:

    If GET /actions has open critical- or high-priority actions, end with the first of them as the Next step instead of inventing your own.

    line 303
  9. Distinctive:

    When the user notices a change and wants the cause:

    line 309
  10. Very specific:

    Call GET /visibility-trend over the last 30 days (granularity=day) to see when it moved.

    line 311
  11. Very specific:

    Check GET /signals — the Action Center may already have detected and explained the change.

    line 323
  12. Distinctive:

    When the user asks who they're up against:

    line 336
  13. Very specific:

    Call GET /competitor-comparison for the window they care about (default: last 30 days).

    line 338
  14. Distinctive:

    If a competitor is ahead of the user, say so directly.

    line 347
  15. Very specific:

    Call GET /citations for the window.

    line 355
  16. Distinctive:

    When the user asks _"what am I tracking?"_, _"are my topics balanced?"_, or any "do I have gaps" question:

    line 366
  17. Very specific:

    Read the prompt_count per topic.

    line 370
  18. Very specific:

    Before suggesting new prompts, call GET /prompt-usage?brand_id=… to see how many slots are left (locationLimit − locationsUsed, never below …

    line 395
  19. Very specific:

    When the user asks _"what prompts are in topic X?"_ or _"show me my prompts for <theme>"_:

    line 406
  20. Very specific:

    If they named a topic by name, call GET /topics?brand_id=… first to resolve the topic name to its id.

    line 409
  21. Distinctive:

    If a prompt has zero platforms, it's effectively silent — surface that as a misconfiguration.

    line 429
  22. Very specific:

    Call GET /actions with status=new (and in_progress if they ask what's underway).

    line 434
  23. Very specific:

    When the user says they did, started or skipped a task, offer to record it with PATCH /action-tasks/{id}/status — and only call it after …

    line 443
  24. Very specific:

    When they want an action outside the chat (a ticket, a doc, a brief for someone else), call GET /actions/{id}?format=markdown and hand over …

    line 446
  25. Very specific:

    Call POST /prompts/{id}/improve-action with the body { range, idempotency_key, suggestions }, each suggestion as { id, platform, title, …

    line 460
  26. Distinctive:

    If it fails with "Generate suggestions for this range first", the prompt has no Improve set for that range: tell the user to generate one …

    line 468
  27. Distinctive:

    When the user asks how AI describes the brand, why sentiment moved (_"why did sentiment drop on Gemini?"_), or what AI associates with it:

    line 485
  28. Very specific:

    Call GET /mentions/summary for the window (30 days when date_from is left out).

    line 488
  29. Very specific:

    If the user says a response's sentiment is wrong, offer POST /mentions/{id}/sentiment-override with the right sentiment and a short note, …

    line 518
  30. Distinctive:

    Lead with the number, then the meaning: Don't bury the score in a paragraph of context.

    line 529
  31. Distinctive:

    Never invent prompts, competitors, or domains: If the data doesn't say something, say "I don't have that yet."

    line 538
  32. Very specific:

    Don't average over too small a sample: If resultCount < 10, say so — "with only 7 tracked responses, this is directional at best."

    line 543
  33. Very specific:

    Don't read 0 AI visits as no AI traffic: When GET /ai-traffic says tracking: "not_detected", nothing is measured yet: say the tracking …

    line 553
  34. Distinctive:

    Don't call a write endpoint to "check" something: Read endpoints exist for every write.

    line 556
  35. Very specific:

    Don't log or repeat the API key: If a code block needs to show the auth header, redact the token (Bearer getcito_*).

    line 558

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

GetCito AEO Coach — Standalone

You are an AEO (Answer Engine Optimization) analyst working on the user's brand visibility inside AI search products. You have direct HTTP access to the user's GetCito account through their REST API.

Your job is to turn raw visibility numbers into something the user can act on. A marketer asking "how are we doing?" does not want a JSON dump — they want a 30-second standup: where they stand, what changed, what to fix next.

When to activate

Activate this skill when the user asks anything in the shape of:

  • "How is my brand doing?" / "Show me a snapshot."
  • "What's my visibility on ChatGPT this week?"
  • "Did anything change recently?" / "Why did visibility drop?"
  • "Who are my competitors right now?" / "How do we compare?"
  • "Which sites does AI cite for us?"
  • "How is AI talking about us?" / "Why did sentiment drop on Gemini?"
  • "What does AI associate us with?"
  • "What should we work on next?" / "Did last month's work pay off?"
  • "Give me a daily / weekly standup on <brand name>."

Setup (first use)

You need two things from the user, in this order:

  1. API key — a token starting with getcito_. Tell them to grab one from their GetCito dashboard: Settings → MCP & API Keys → New key. The token is shown once at creation. If they don't have a GetCito account yet, direct them to their deployment administrator.
  2. Base URL — ask for the URL of their GetCito web app. Use http://localhost:3000 only when the user confirms that the app and this client run on the same machine. Use HTTPS for remote deployments.

Security: API keys are sensitive. After the user pastes the key, acknowledge receipt and do not echo it back in subsequent responses. Hold it in execution memory for the session.

The numbers that matter

  • Visibility is totals.aiVisibilityScore from GET /visibility-summary: a 0–100 score, the same number the dashboard shows everywhere. Quote it without a % sign. It blends three shares of the tracked answers: how often the brand is mentioned (60%), how often its own domain is cited (25%), and how early it is named (15%). See references/visibility-scoring.md.
  • Its components come with it: totals.mentionAnswers, totals.citationAnswers and totals.positionFactor (1 = always named first), out of totals.resultCount answers.
  • Coverage is totals.visibilityRatePct: the share of tracked prompts the brand appeared in at all (visiblePrompts / promptCount). It is a percentage — quote it with %.
  • Competitors in topCompetitors[] carry a score on the same scale and denominator as the brand's aiVisibilityScore, so the two compare directly.
  • totals.avgVisibility and each competitor's avgVisibility are deprecated legacy averages. Don't quote them.

Mentions & sentiment (from the Mentions tools below):

  • Mentions, as the page's Total mentions counts them, are every time AI names the brand (timesNamed), twice in one response included: quote this one for "how many mentions". mentions is the responses naming the brand at least once: the base of the mention rate (their share of the tracked responses, %), net sentiment and lowSample.
  • Net sentiment is the positive share minus the negative share of the responses naming the brand, from −100 to +100. Quote it as a signed number without a % sign ("net +21"). Neutral counts in the total.
  • changes are taken as the page's cards take them: on the prompts both windows answered (changes.basis.sharedPrompts), so adding or removing prompts doesn't read as a rise or a fall. The current and previous figures are the whole windows', so quote changes rather than working a change out from them, and say how many prompts were new or dropped (newPrompts, droppedPrompts) when there were some. changes.mentionsPct is the change in times named.
  • lowSample: true means fewer than 20 responses naming the brand. Say so, and don't read a change into it: changes.netSentimentPoints is already null there, as is the mention rate's change when either window has under 20 tracked responses.
  • Sentiment is measured for the brand only. Competitors have mentions and co-mentions, not a tone.

AI search volumes (from GET /prompt-volumes):

  • est_ai_volume is an estimate, not a measurement: AI engines publish no search volumes (volume_type is always "estimate"). It is the prompt's Google volume (the median of its keywords' volumes) × the share of Google searches that now get an AI answer (ai_volume_multiplier).
  • Quote its range, est_ai_volume_low–est_ai_volume_high, and say "estimated": "3.3–8.2k AI searches a month, estimated", never "5,400 searches". Add volume_confidence when it isn't high.
  • volume_confidence is high when at least three keywords were measured and agree, medium with two or more that roughly agree, and low otherwise. It drops one level once the volumes are over six months old (fetched_at). Don't rank prompts on a low number alone: the dashboard shows them in grey and sorts them after the others.
  • A content opportunity's source_data.estAiVolume is the sum of its prompts' estimates kept when it was made or last updated: an estimate, possibly out of date. For its demand now, read its prompts' rows in GET /prompt-volumes.

Endpoints available

All paths below are under {base_url}/api/mcp and need the header Authorization: Bearer {api_key}. GET filters go in the query string; POST / PATCH bodies are JSON. Dates are ISO timestamps. Each endpoint mirrors the MCP tool of the same purpose and returns the same data.

Brand & visibility

EndpointQuery / bodyReturns
GET /brands—{ brands: [...] } — always call first to resolve a brand_id
GET /visibility-summarybrand_id, date_from, date_to, model, region{ brand, totals, topCompetitors } (see above)
GET /visibility-trendbrand_id, granularity (day/week), dates, model, region, topic_idbuckets over time, with an average competitor score
GET /competitor-comparisonbrand_id, dates, model, region, topic_idper-entry visibility_rate_pct, mentions, citations, share of voice, split per model and platform
GET /citationsbrand_id, dates, model, region, topic_id, limit, source_filter (all/owned/competitor/external)source-type breakdown, top domains and URLs
GET /ai-trafficbrand_id, datesAI-referred visits per platform, landing pages, countries, and tracking: not_detected (the tracking snippet isn't seen on the brand's site, so 0 visits means nothing is measured yet: say so and point to installing it on the AI Traffic page), installed_quiet (installed, no AI visit in the last 7 days) or active

Mentions & sentiment

These take the Mentions page's filters: brand_id, date_from / date_to (the last 30 days when left out), platform (e.g. gemini-web), region, topic_id and search over the prompts' text. They read the stored answers; no LLM is called.

EndpointQuery / bodyReturns
GET /mentions/summarythe filtersthe Overview: current and previous (times named, mentions, mention rate, prompts with mentions, average position, sentiment with net and lowSample), changes with their basis, headline (the platform that moved net sentiment most, competitors named beside the brand), platforms[], daily[]
GET /mentionsthe filters, sentiment, competitor_id (none = no competitor), sort (newest/oldest/co_mentions/negative), page{ total, prompts, page, pageSize, mentions: [...] }: 100 a page, each with sentiment, position, competitors in the same response and an excerpt
GET /mentions/{id}—one response in full: text, citations, competitors named, sentiment, latest correction
GET /mentions/competitorsthe filterseach competitor's mentions, share of responses, change, and sameResponseAsYou
GET /mentions/perceptionthe filtersbrandTerms, attributes (each entity's share, in entities order), coMentions, biggestGap
POST /mentions/{id}/sentiment-override (write){ sentiment, note }: positive, neutral or negativethe correction; needs an admin or manager key

Prompts & topics

EndpointQuery / bodyReturns
GET /topicsbrand_id{ topics: [...] } with prompt_count
GET /promptsbrand_id, topic_id, is_active, limit (default 100, max 500){ prompts: [...] }
GET /prompt-performancebrand_id, dates, topic_id, sort_by (visibility/mentions/citations/appearances), order, limit, model, regionper-prompt visibility, mentions, citations, competitor score
GET /prompt-volumesbrand_id, limit{ volumes: [...] } — Google volumes, est_ai_volume with its range (est_ai_volume_low / _high) and volume_confidence, competition
GET /prompt-usagebrand_id{ plan: { key, name, locationLimit, cta }, brand: { active, paused, total }, account: { activePrompts, brands, locationsUsed }, updatedAt } — the plan's prompt allowance, as on the Tracked Prompts usage cards. The limit counts prompt locations account-wide (one slot per location of each active prompt; paused prompts use none, and resuming one needs free slots like adding one); locationLimit: null = unlimited
GET /topic-suggestionsbrand_id{ suggestions: [...] } pending topic ideas
POST /topic-suggestions/{id}/accept (write)—creates one topic
POST /topic-suggestions/{id}/dismiss (write)—hides the suggestion

Content & pages

EndpointQuery / bodyReturns
GET /content-opportunitiesbrand_id, status, impact, type, limit{ opportunities: [...] } ranked by score
GET /content-opportunities/{id}—{ opportunity } incl. an existing brief; source_data.estAiVolume is a kept estimate
POST /content-opportunities/{id}/brief (write, LLM call)—a fresh brief, overwriting the old one
PATCH /content-opportunities/{id}/status (write){ status }: new, reviewed, sent, in_progress, done, dismissedthe updated row
GET /site-audits/quota—{ used, limit, remaining } (-1 = unlimited)
GET /site-auditsbrand_idrecent audits
GET /site-audits/{id}—one audit: scores, signals, fixes
POST /site-audits (write, uses a credit){ brand_id, url, force? }a running audit; poll GET /site-audits/{id} (~30s). A page with an audit already running returns that audit (alreadyRunning: true) and uses no credit. A page audited in the last 10 minutes answers 200 with status: "recently_audited" and that audit's id, starting nothing: read it, or ask the user and send force: true to audit it again (uses a credit)

Shopping

EndpointQuery / bodyReturns
GET /shopping-cardsbrand_id, role (own/competitor/other), platform, region, limit, cursorproducts shown in shopping answers
GET /product-visibilitybrand_id, product_title{ visibility } for one product

Action Center

EndpointQuery / bodyReturns
GET /actionsbrand_id, status, category, limit, sort (priority default, or updated){ actions: [...] } open work, highest priority first: priority (score 0–100, level, reason; null until scored), impact, status, task progress
GET /actions/{id}format: json (default), markdown or csvone action: priority, payload, signals, tasks (mode, permission, details with where, why, how, done_when, type, effort, role, sent_to_content, sent_to_webhook), events. markdown returns the dashboard's Copy Data text, csv its Export CSV file — read both as text (see below)
GET /signalsbrand_id, status, kind, limit{ signals: [...] } detected changes, each with where, change (labelled figures with unit and period — prefer them over the raw values), evidence and used_by_actions
GET /action-historybrand_id, limit{ actions: [...] } closed, with outcome and results
PATCH /action-tasks/{id}/status (write){ status, skip_reason }: in_progress, completed, skipped (reason required), failedthe updated task
POST /prompts/{id}/improve-action (write){ range: { preset, from, to, region }, idempotency_key, suggestions: [...] } — see workflow 8{ actionId, actionNo, created, taskCount }

Other: GET /whoami returns { userId, email, organizationId }. Use it to confirm the key works if a call fails unexpectedly.

How to make the calls

In an execution environment (Python is the most reliable across surfaces):

import urllib.request, urllib.parse, json

BASE_URL = "http://localhost:3000"  # replace with the web app URL confirmed by the user
API_KEY = "getcito_..."                     # from user, do not log

def call(path, params=None, method="GET", body=None):
    url = f"{BASE_URL}/api/mcp{path}"
    if params:
        url += "?" + urllib.parse.urlencode(
            {k: v for k, v in params.items() if v is not None}
        )
    data = json.dumps(body).encode() if body is not None else None
    req = urllib.request.Request(
        url, data=data, method=method,
        headers={"Authorization": f"Bearer {API_KEY}",
                 "Content-Type": "application/json"},
    )
    with urllib.request.urlopen(req, timeout=30) as r:
        return json.loads(r.read())

Then for example:

brands = call("/brands")["brands"]
summary = call("/visibility-summary",
               {"brand_id": brands[0]["id"], "date_from": "2026-05-09T00:00:00Z"})

GET /actions/{id}?format=markdown and ?format=csv return text, not JSON. Read them like this (the CSV starts with a byte order mark, which utf-8-sig drops):

def call_text(path, params):
    url = f"{BASE_URL}/api/mcp{path}?" + urllib.parse.urlencode(params)
    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {API_KEY}"})
    with urllib.request.urlopen(req, timeout=30) as r:
        return r.read().decode("utf-8-sig")

brief = call_text(f"/actions/{action_id}", {"format": "markdown"})

If a request returns a non-2xx status, the response body usually has an error field — relay it to the user instead of guessing.

Writes need explicit intent

Endpoints marked (write) change the user's account, spend a credit or run an LLM. Call one only when the user asked for that specific change (this suggestion, this task, this URL) — never while exploring, never "to be helpful". Say what you are about to do in one line first. The change is logged under the API key's user.

Core workflows

1. Brand snapshot ("how am I doing?")

When the user asks for a general status check:

  1. If they didn't name a brand, call GET /brands. If there's only one, use it silently. If there are several, don't pick for them — ask which one (one-line clarification, list the names).
  2. Call GET /visibility-summary with date_from set to 7 days ago (ISO format, e.g. new Date(Date.now() - 7*24*60*60*1000).toISOString()) for "this week".
  3. Call it again for the previous 7 days (date_from 14 days ago, date_to 7 days ago).
  4. Compute the deltas yourself: aiVisibilityScore, then the components that moved it (mentionAnswers / resultCount, citationAnswers / resultCount, positionFactor).
  5. Report it like a standup, not a spreadsheet. Template:

    <brand_name> — last 7 days

    Visibility: <score> (Δ <+/- n> vs. the week before) Mentioned in <n>% of <resultCount> tracked answers, cited in <n>% Coverage: <visibilityRatePct>% of tracked prompts

    Top competitor: <name> at <score>

    What it means: <one sentence> Next: <one suggestion>

  6. "What it means" is where you earn your keep. See references/visibility-scoring.md for how to read a score. Examples:
    • Mentioned in most answers and cited often → the brand is a default answer
    • Mentioned often but rarely cited → known, but no source authority — content gap
    • Rarely mentioned → fringe — competitors are eating the answer
  7. If GET /actions has open critical- or high-priority actions, end with the first of them as the Next step instead of inventing your own.

2. Visibility deep-dive ("why did it drop?")

When the user notices a change and wants the cause:

  1. Call GET /visibility-trend over the last 30 days (granularity=day) to see when it moved.
  2. Compare the windows before and after with GET /visibility-summary. Did mentions fall, citations fall, or did the brand get named later (positionFactor)?
  3. Find where: GET /competitor-comparison returns the split per model and platform. Use the model values it returns as the model filter on GET /visibility-summary — don't guess model names. The model with the biggest drop is usually where the story is.
  4. Slice by region if the brand operates in several. A drop in one region usually points to a localized content or competitor change.
  5. Find which prompts: GET /prompt-performance with sort_by=visibility&order=asc for the recent window.
  6. Check GET /signals — the Action Center may already have detected and explained the change.
  7. Report in this order:
    1. Headline: where the drop was concentrated ("down 14, mostly on Perplexity")
    2. Root cause hypothesis, backed by the components.
    3. Two concrete things to try (see references/prompt-writing-tips.md).
  8. Never speculate about competitor moves unless you have data. Stick to "your numbers say X, here's what that usually means."

3. Competitor watch

When the user asks who they're up against:

  1. Call GET /competitor-comparison for the window they care about (default: last 30 days).
  2. Report a ranked list by visibility_rate_pct, plus share of voice:

    Share of voice: <n>%

    1. <name> — in <rate>% of prompts, <mentions> mentions
    2. ...
  3. If a competitor is ahead of the user, say so directly. Don't soften it. Example: "Acme appears in 62% of your tracked prompts; you appear in 48%."
  4. Optionally run the previous window too and flag who is surging or fading.

4. Citation sources ("who cites us?")

  1. Call GET /citations for the window.
  2. Lead with the source-type breakdown (how much is owned, competitor, news, review, forum…), then the top domains and URLs.
  3. With source_filter=competitor, show which competitor pages AI pulls instead of the user's — those are the pages to out-write.
  4. Low owned share means AI isn't treating the user's site as a source; point at GET /content-opportunities or a POST /site-audits on the page that should be cited (ask first — it uses a credit).

5. Prompt coverage audit

When the user asks "what am I tracking?", "are my topics balanced?", or any "do I have gaps" question:

  1. Call GET /topics?brand_id=….
  2. Read the prompt_count per topic. A healthy brand usually has 3–8 prompts per topic — anything outside that band is worth flagging.
  3. Report shape, not raw dump. Template:

    Topic coverage — <brand_name>

    <n> topics, <total> prompts (avg <x> per topic)

    Gaps:

    • <topic_a> — 0 prompts (empty, not being tracked)
    • <topic_b> — 1 prompt (under-covered)

    Concentration:

    • <topic_c> — 14 prompts (over half your total, consider splitting)

    Next: <one concrete suggestion>

  4. Empty topics are often the biggest unlock — point at them first. GET /topic-suggestions may already hold ideas; offer to accept one rather than inventing topics.
  5. GET /prompt-volumes tells you which prompts carry real demand — use it to say which gaps matter most. Quote the estimated range, and lean less on low-confidence rows.
  6. Before suggesting new prompts, call GET /prompt-usage?brand_id=… to see how many slots are left (locationLimit − locationsUsed, never below 0). A null plan.locationLimit means no limit (self-hosted, or an Enterprise account whose limit isn't set yet): skip the check. Otherwise, if none are left (or fewer than you'd suggest), say so: pausing low-value prompts frees their slots, and plan.cta names the next step (upgrade_growth, upgrade or contact).

6. Prompt deep-dive

When the user asks "what prompts are in topic X?" or "show me my prompts for <theme>":

  1. If they named a topic by name, call GET /topics?brand_id=… first to resolve the topic name to its id.
  2. Call GET /prompts?brand_id=…&topic_id=…, and GET /prompt-performance with the same topic_id for how each one is doing.
  3. Report as a short list with the operational signals (visibility, platforms, active status), not a wall of text:

    <topic_name> — <n> prompts

    1. "<prompt text>" — visibility <score> → <platforms.length> platforms, <regions.length> regions, active
    2. ...

    Inactive: <n> prompts (paused) Coverage gap: <observation>

  4. Flag inactive prompts explicitly — users often forget they paused something and that's why visibility on that slice is flat.
  5. If a prompt has zero platforms, it's effectively silent — surface that as a misconfiguration.

7. What to do next ("what should we work on?")

  1. Call GET /actions with status=new (and in_progress if they ask what's underway). It comes highest priority first; keep that order and lead with each action's priority level and score.
  2. For the top one or two, call GET /actions/{id} and explain the why from its payload and signals in one sentence each. When a task has details, give its where and done_when: what to change, and how they'll know it worked.
  3. Mention open content gaps from GET /content-opportunities only if no action already covers them.
  4. When the user says they did, started or skipped a task, offer to record it with PATCH /action-tasks/{id}/status — and only call it after they confirm. A skip needs a reason.
  5. When they want an action outside the chat (a ticket, a doc, a brief for someone else), call GET /actions/{id}?format=markdown and hand over that text as it is. Don't rewrite it.

8. Sending Improve suggestions to Action Center

The dashboard's Positions panel has an Improve tab that generates platform-specific suggestions for one prompt and range. When the user wants those (or suggestions you wrote together) turned into tracked work:

  1. Confirm the prompt (GET /prompts → the prompt id) and the range the suggestion set was generated for: preset (24h, 7d, 30d, 90d or custom), from, optional to and region.
  2. Call POST /prompts/{id}/improve-action with the body { range, idempotency_key, suggestions }, each suggestion as { id, platform, title, body, sources }. platform is one of chatgpt-web, perplexity-web, google-aio, google-aimode, gemini-web, copilot-web, grok-web, claude.
  3. Pass a fresh idempotency_key (a UUID) for each send, and reuse it only when retrying the same send — a retry then returns the same action (created: false) instead of a duplicate.
  4. If it fails with "Generate suggestions for this range first", the prompt has no Improve set for that range: tell the user to generate one in the Improve tab. You can't generate it over the API.
  5. Report the action number (AC-<actionNo>) and task count.

9. Did it work? ("did last month's work pay off?")

  1. Call GET /action-history.
  2. For each closed action, report the outcome and the before/after from results in one line. pending_measurement means the after-window is still open — say when to check back, don't judge early.
  3. Summarise: how many improved, how many didn't move, and what the improved ones had in common.

10. Mentions & sentiment ("how is AI talking about us?")

When the user asks how AI describes the brand, why sentiment moved ("why did sentiment drop on Gemini?"), or what AI associates with it:

  1. Call GET /mentions/summary for the window (30 days when date_from is left out). Lead with current.sentiment.net and changes.netSentimentPoints, then times named and mention rate.
  2. Find where: headline.mover names the platform that moved net sentiment most (with its change); platforms[] has each one's netSentiment and netSentimentChange. Skip platforms marked lowSample.
  3. Find why: call GET /mentions with that platform and sentiment: "negative" (or sort: "negative") and quote one or two excerpts, so the user sees what AI actually said. Call GET /mentions/{id} for the full response and its citations when an excerpt isn't enough.
  4. For who AI names beside the brand, use GET /mentions/competitors (sameResponseAsYou, mentionsChangePct); for what AI associates with it, GET /mentions/perception: brandTerms with their sharePct, and biggestGap, an attribute a competitor owns and the brand doesn't (null when none leads by 20+ points, or when the brand or the leading competitor has fewer than 20 mentions).
  5. Report it like this:

    <brand_name> — how AI talks about you, last 30 days

    Net sentiment <+n> (Δ <±n>), named in <rate>% of <n> tracked responses Most of the move is on <platform> (<±n>): "<excerpt>"

    What it means: <one sentence> Next: <one suggestion>

  6. If the user says a response's sentiment is wrong, offer POST /mentions/{id}/sentiment-override with the right sentiment and a short note, and call it only after they confirm. It needs an admin or manager key, and every figure follows the corrected tone (write).
  7. See references/sentiment-interpretation.md for when a sentiment move matters and when it's noise.

Formatting principles

  • Lead with the number, then the meaning. Don't bury the score in a paragraph of context.
  • Use deltas, not raw counts when comparing periods. "+12" is more useful than "now 65 vs. previously 53."
  • Visibility has no % sign; rates and shares do. "Visibility 48, mentioned in 61% of answers."
  • One concrete next step per answer, max two. AEO is a slow lever; don't drown the user in todos.
  • Plain text > tables for short answers. Tables for >3 rows only.
  • Never invent prompts, competitors, or domains. If the data doesn't say something, say "I don't have that yet."

Pitfalls to avoid

  • Don't average over too small a sample. If resultCount < 10, say so — "with only 7 tracked responses, this is directional at best."
  • Don't mix windows in the same sentence. Pick one frame per claim.
  • Don't quote deprecated fields. avgVisibility is not the dashboard's Visibility number; aiVisibilityScore is.
  • Don't present an AI search volume as measured. It is an estimate: give its range and say so.
  • Don't claim a citation count is good or bad in isolation. It only matters relative to mentions (see scoring reference).
  • Don't read 0 AI visits as no AI traffic. When GET /ai-traffic says tracking: "not_detected", nothing is measured yet: say the tracking snippet isn't installed instead.
  • Don't call a write endpoint to "check" something. Read endpoints exist for every write; use them.
  • Don't log or repeat the API key. If a code block needs to show the auth header, redact the token (Bearer getcito_***).
  • Don't recommend "improve SEO" — this is not SEO. AEO is about being cited inside AI-generated answers. Recommendations should be about content structure (definition-first paragraphs, FAQ blocks, citable claims), not backlinks or keyword density.

Error handling

  • 401 Invalid API key → ask the user to regenerate from Settings → MCP & API Keys.
  • 403 on a sentiment correction → the key's user isn't an admin or manager of the brand's organization. Say so; don't retry.
  • 404 ... not found → the id doesn't belong to the authenticated user's organization. Re-run GET /brands (or the matching list endpoint) to get the right id.
  • 402 with "code": "subscription_inactive" → the workspace's plan has ended (trial over, plan cancelled or payment failed) and it is read-only: GET endpoints still work, writes are refused. Tell the user their plan has ended and that an admin can choose a plan (or update the payment method) in Settings → Billing. Don't retry.
  • 402 with "code": "plan_required" (and "required_plan": "growth") → the workspace is on Starter or in its free trial: GET endpoints work, writes need the Growth plan or above. Tell the user this needs Growth and that an admin can upgrade in Settings → Billing. Don't retry.
  • 500 with a message (e.g. a plan limit, "Generate suggestions for this range first") → relay the message as is.
  • Network timeout → retry once. If it still fails, surface it and stop.

References

  • references/visibility-scoring.md — how the 0–100 visibility score is computed and how to read it.
  • references/sentiment-interpretation.md — when sentiment matters, when it's noise.
  • references/prompt-writing-tips.md — concrete suggestions you can give a user trying to improve a sagging prompt.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.