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

# Agent Skill

> Install the official Octolens Agent Skill to give Claude Code, Cursor, and other AI coding agents built-in expertise for working with your Octolens workspace via the CLI or the REST API.

The **Octolens Agent Skill** is a drop-in package of expertise that teaches AI coding agents how to work with Octolens correctly — which commands and endpoints to reach for, how to filter mentions, how to set up keywords and alerts, and the gotchas to avoid. Once installed, your agent reaches for it automatically whenever a task involves Octolens.

It's an [open Agent Skill](https://agentskills.io) — one `SKILL.md` plus a reference doc per surface — so it works in any compatible agent (Claude Code, Cursor, and more).

<Note>
  The skill is the *knowledge layer*; the [CLI](/docs/cli/overview) and [REST API](/docs/api/v2/overview) are the *connection*. The skill tells your agent to prefer the CLI for shell work, scripting and CI, and REST v2 for raw programmatic access — and how to use each.
</Note>

The skill does **not** document the [MCP server](/docs/mcp/v2/overview). MCP is still a first-class Octolens surface with [its own docs](/docs/mcp/v2/overview) — it is simply self-documenting: an agent that can call the tools can already read their schemas, so a skill teaching them adds nothing. The skill earns its keep on the two surfaces an agent *cannot* introspect: the CLI's command surface and the REST v2 endpoint surface.

***

## Install

```bash theme={null}
npx skills add octolens/skill
```

That's it — the skill installs into your agent's skills directory and activates on its own when you ask anything Octolens-related. You can also browse it on [skills.sh](https://skills.sh/octolens/skill) or view the source on [GitHub](https://github.com/octolens/skill).

***

## What it does

With the skill installed, you can ask your agent things like:

* "Pull the last week of negative Reddit mentions and summarize the top complaints."
* "Add 'next.js deployment' as a keyword and route buy-intent mentions to my #leads Slack channel."
* "Export all competitor mentions from this quarter to CSV."
* "Chart share of voice for my brand vs. its two top competitors."

The agent knows to:

* **Choose the right surface** — the CLI for shells, scripts, cron jobs, CI and bulk export; REST v2 for application code, non-Node runtimes, and anything the CLI doesn't cover.
* **Script against the CLI contract** — `--json` purity, the frozen [exit-code map](/docs/cli/contract/exit-codes), the [error envelope](/docs/cli/contract/error-envelope), and [`RESPONSE_LOST`](/docs/cli/contract/response-lost) (verify, don't retry).
* **Filter mentions correctly** — the simple and advanced filter grammar, valid platforms/sentiment/tag values, and ID-based keyword filtering.
* **Manage your workspace** — create and update keywords and feeds, wire up Slack / email / webhook destinations, and run analytics.
* **Avoid common mistakes** — stale v1 filter fields, timestamp formats, scope errors, paginated lists that quietly return one page, and more.

***

## Which surface, when

| You are…                                                                                                                                   | Use                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| Writing a shell script, a CI job or a cron, working in a terminal, or exporting in bulk                                                    | **CLI**                                                                                       |
| Calling from application code, a non-Node runtime, a box where you can't install a binary, or reaching for something the CLI doesn't cover | **REST v2**                                                                                   |
| Working interactively inside an MCP-capable agent                                                                                          | **[MCP server](/docs/mcp/v2/overview)** (not covered by the skill — its tools describe themselves) |

The CLI is a client of the same REST v2 API, but it adds guarantees the raw endpoints don't: a frozen exit-code map you can branch on instead of parsing message text, exactly one JSON document on stdout under `--json`, automatic rate-limit retry, a per-request `--timeout` that guarantees termination, and name→id resolution (`--keyword 'acme corp'` rather than a lookup call first).

***

## How it works

Agent Skills use *progressive disclosure*: the agent loads only a short description at startup, then pulls in the full instructions when a task matches. Your context window stays lean until Octolens is actually relevant.

<CardGroup cols={2}>
  <Card title="CLI" icon="terminal" href="/docs/cli/overview">
    The preferred surface for shells, scripts, CI and bulk export. Browser login or an API key.
  </Card>

  <Card title="REST API" icon="code" href="/docs/api/v2/overview">
    For application code, backend jobs and non-Node runtimes. Bearer auth with an API key.
  </Card>
</CardGroup>

***

## Requirements

* An Octolens plan with API access (Pro, Scale, or Enterprise).
* For the CLI path: a shell you can run `octolens` in — sign in with `octolens login`, or set `OCTOLENS_API_KEY` on headless boxes.
* For the REST path: an API key from **Settings → API**.