TopCited Skills

Name: topcited-skills
Author: TopCited

Agent Skills that teach an AI coding agent — Claude Code, Codex, or anything else
that can read Markdown — how to do SEO and GEO (Generative Engine
Optimization: being found and cited by ChatGPT, Claude, Gemini and Perplexity),
and how to drive TopCited on your behalf through the
topcited CLI.

These are the same skills TopCited's own hosted agent runs on. This repo is the
single source of truth for them.

Skill	What it gives your agent
`seo-geo`	A cited, dated knowledge base: technical SEO, entity & authority, content strategy, GEO, measurement, distribution playbooks. Read before making a judgment call, instead of answering from memory.
`topcited-api`	How to drive TopCited with the `topcited` CLI: install, sign-in, a command cheat-sheet, the agent contract (JSON, exit codes, `--wait`, `--dry-run`), and per-feature guides (when, why, what it costs, how it fails).
`visibility-workflow`	An eight-stage engagement that takes a brand from "no idea if we're visible" to a measured, improved baseline — using the two skills above.

Install all three. visibility-workflow orchestrates the other two and
topcited-api defers SEO judgment to seo-geo; they reference each other by
relative path, so they need to sit as siblings.

Install

Claude Code (plugin)

/plugin marketplace add TopCited/topcited-skills
/plugin install topcited-skills@topcited

Any agent (manual)

Clone and drop the skills into your personal skills directory:

git clone https://github.com/TopCited/topcited-skills.git
cp -r topcited-skills/skills/* ~/.claude/skills/

For a project rather than your whole machine, use .claude/skills/ in the repo
instead.

Any agent (no install)

Everything here is plain Markdown, so an agent that can fetch a URL needs no
install at all — point it at a raw file and it will follow the links from there:

https://raw.githubusercontent.com/TopCited/topcited-skills/main/skills/seo-geo/SKILL.md
https://raw.githubusercontent.com/TopCited/topcited-skills/main/skills/topcited-api/SKILL.md
https://raw.githubusercontent.com/TopCited/topcited-skills/main/skills/visibility-workflow/SKILL.md

Each SKILL.md opens with YAML frontmatter (name, description) and a routing
table saying what to read next. Two caveats when fetching rather than cloning:
the internal links are relative paths, so resolve them against the file's own
directory; and topcited-api / visibility-workflow need the topcited CLI
installed (below).

Pin to a tag or commit SHA instead of main if you need the content to stay put.

Install the CLI and sign in

seo-geo needs nothing. topcited-api and visibility-workflow drive TopCited
through the topcited CLI:

curl -fsSL https://topcited.ai/install.sh | sh    # or: npx @topcited/cli …
topcited auth login                               # approve in the browser

auth login prints a URL and a code and waits while you approve; it stores an
API key named topcited-cli on <hostname>. For CI or a headless agent, create a
key under Settings → Profile → API keys instead and set it in the
environment. Keys act as you with full rights over your account, expire after
90 days, and you can hold up to 5.

Variable	Required	Default	What it is
`TOPCITED_API_KEY`	no (yes for CI)	—	A personal key; overrides the one `auth login` stored. Treat it like a password.
`TOPCITED_BASE_URL`	no	`https://api.topcited.ai`	API base.
`TOPCITED_BRAND`	no	—	Brand the CLI acts on for one session.
`TOPCITED_UI_URL`	no	`https://topcited.ai`	Web app base, used only to build links shown to you.

The API and the web app are different hosts — if you override one, override both.
topcited doctor checks config, sign-in, connectivity and version skew.

A note on spending

Most TopCited operations consume T-coins (credits) from your plan. The skills are
written to check topcited usage — which is free — and to run --dry-run and
ask you before spending. The CLI never prompts without a terminal, so if you wire
these skills into an unattended automation you are removing that confirmation
step; put your own budget guard in front of it.

Repo layout

skills/
  seo-geo/              SKILL.md + knowledge/
  topcited-api/         SKILL.md + references/
  visibility-workflow/  SKILL.md + stages/ + templates/
.claude-plugin/         Claude Code plugin + marketplace manifests

The API reference is the public OpenAPI spec at
https://api.topcited.ai/api/v1/openapi.public.json; the guides under
topcited-api/references/ cover only what the CLI's --help can't.

Contributing

Issues and PRs welcome, especially: a knowledge file that has gone stale (each
carries a last-verified date and its sources), a guide that no longer
matches the CLI or the API, or a stage that reads as jargon to a non-expert.

License

MIT. The knowledge files cite third-party sources; those citations are
links, not redistribution of the cited work.