> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rankraft.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# RankRaft skill for AI coding agents

> Teach Claude, Codex, ChatGPT, Gemini, Cursor and other agents to write correct code against the RankRaft AI API and SDKs.

The RankRaft skill is a small instruction pack for AI coding agents. With it installed, an agent asked to "pull our visibility into BigQuery" or "add these prompts from a CSV" writes working code the first time: it uses the right SDK, the right endpoints and filters, handles pagination and rate limits, and knows when you should use the MCP server instead of code.

It follows the open [Agent Skills](https://agentskills.io) format: a `SKILL.md` file plus a few reference pages, all plain Markdown. Any agent that reads skills can use it.

> [!NOTE]
>
> Want to **ask questions** about your data in a chat app rather than write code? You don't need the skill — connect the [MCP server](/mcp/connect) instead.

## Install

Get the skill once:

```bash theme={"system"}
git clone https://github.com/RankRaft/rankraft-skill
```

Then put it where your agent looks for skills:

**Claude Code**

**Recommended: the plugin**, which installs the skill and keeps it updated.

```text theme={"system"}
/plugin marketplace add RankRaft/rankraft-claude-plugin
/plugin install rankraft@rankraft
```

Or from a shell: `claude plugin marketplace add RankRaft/rankraft-claude-plugin`, then `claude plugin install rankraft@rankraft`. Scopes, updates and removal: [Claude Code plugin](/skills/claude-code-plugin).

**Or copy the skill:**

```bash theme={"system"}
# this project only
cp -r rankraft-skill .claude/skills/rankraft
# every project
cp -r rankraft-skill ~/.claude/skills/rankraft
```

**Claude (app)**

In Claude on the web or desktop, custom skills are uploaded as a zip:

1. Zip the folder: `cd rankraft-skill && zip -r ../rankraft-skill.zip . -x '.git/*'`
2. Open **Settings → Capabilities → Skills** and upload `rankraft-skill.zip`.
3. Make sure **code execution** is on; skills run inside it.

On Team and Enterprise plans, an owner may need to allow custom skills first.

**Codex**

Codex (CLI and IDE extension) loads skills from your skills folder:

```bash theme={"system"}
# every project
mkdir -p ~/.codex/skills && cp -r rankraft-skill ~/.codex/skills/rankraft
# this project only
mkdir -p .codex/skills && cp -r rankraft-skill .codex/skills/rankraft
```

Restart Codex. Ask "what skills do you have?" to check it is listed.

**ChatGPT**

For code you'll run yourself, add the skill to a ChatGPT **Project**:

1. Create a project (for example "RankRaft integration").
2. Paste the contents of `SKILL.md` into the project's **Instructions**.
3. Upload the files in `references/` as project files.

Every chat in that project then follows it. For coding inside your repository, use the **Codex** tab instead.

**Gemini CLI**

```bash theme={"system"}
# every project
mkdir -p ~/.gemini/skills && cp -r rankraft-skill ~/.gemini/skills/rankraft
# this project only
mkdir -p .gemini/skills && cp -r rankraft-skill .gemini/skills/rankraft
```

Restart Gemini CLI so it picks the skill up.

**Cursor**

```bash theme={"system"}
mkdir -p .cursor/skills && cp -r rankraft-skill .cursor/skills/rankraft
```

Cursor also reads skills from `.claude/skills/`, so a copy installed for Claude Code works here too.

**Other agents**

Copy the folder wherever your agent reads `SKILL.md` files. If it has no skills support (Windsurf, Cline, GitHub Copilot and others), paste `SKILL.md` into the project's rules or custom instructions and keep `references/` in the repository so the agent can open it.

## The skill repository

[github.com/RankRaft/rankraft-skill](https://github.com/RankRaft/rankraft-skill) is the skill itself: plain Markdown and one shell script, MIT licensed, nothing specific to one agent.

```text theme={"system"}
rankraft-skill/
├── SKILL.md                    # the entry point every agent reads
├── references/
│   ├── api-reference.md        # request and response shapes, filter fields, limits
│   ├── errors.md               # every error code and what to do about it
│   ├── recipes.md              # ready-made tasks and curl equivalents
│   └── why-the-sdks.md         # when calling the API by hand is worth it
└── scripts/
    └── smoke.sh                # checks a key, its access and your site ids
```

| File | The agent reads it when |
| - | - |
| `SKILL.md` | starting any RankRaft task: REST or MCP, SDK quick starts, the rules that cause most errors |
| `references/api-reference.md` | it needs exact request or response fields, or the filter fields an endpoint accepts |
| `references/errors.md` | handling or explaining an error |
| `references/recipes.md` | building something common: visibility over time, leaderboards, citation share, CSV prompt loads, warehouse exports, long backfills |
| `references/why-the-sdks.md` | deciding whether to use an SDK or raw HTTP |
| `scripts/smoke.sh` | checking that a key works |

The [Claude Code plugin](https://github.com/RankRaft/rankraft-claude-plugin) packages this same directory, synced automatically, so both stay identical.

## What it teaches

* **REST or MCP:** code that pulls data or manages prompts uses the REST API and an [SDK](/sdks/overview) (Enterprise); questions in a chat app use the [MCP server](/mcp/introduction) (every paid plan).
* **The SDKs:** `rankraft-js` and `rankraft-py`, with working quick starts.
* **Every endpoint**, with the filter fields each report accepts and the limits that apply.
* **The rules that cause most errors:** server-side only; the key goes in a header; dates are inclusive UTC days; cursors belong to one query; filter values are strings; unknown fields are rejected; prompts are disabled, never deleted.
* **Every error code** and what to do about it.
* **Recipes:** visibility over time, a competitor leaderboard, citation share by domain, loading prompts from a CSV, daily crawler traffic into a warehouse, and long backfills.

It also includes `scripts/smoke.sh`, which checks a key, its access level and your site ids in one command:

```bash theme={"system"}
RANKRAFT_API_KEY=rr_api_… bash scripts/smoke.sh
```

## Try it

With the skill installed, ask your agent something like:

* *"Write a script that exports our daily Visibility Score by engine for the last 90 days to a CSV."*
* *"Add the prompts in prompts.csv to our site, as a dry run first."*
* *"Load yesterday's AI crawler traffic into Postgres every morning."*

## Staying up to date

The skill follows the API's [OpenAPI specification](/api-reference/endpoints/get-open-api).

* **Claude Code plugin:** turn on auto-update once, or run `claude plugin marketplace update rankraft` and `claude plugin update rankraft@rankraft`. See [Keep it up to date](/skills/claude-code-plugin#keep-it-up-to-date).
* **Copied install:** run `git pull` in your `rankraft-skill` clone and copy the folder again.

## Source

[github.com/RankRaft/rankraft-skill](https://github.com/RankRaft/rankraft-skill) · Claude Code plugin: [github.com/RankRaft/rankraft-claude-plugin](https://github.com/RankRaft/rankraft-claude-plugin) · MIT licence


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.