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

# Agent Skills

> Install Caesar's SKILL.md files so your agent learns search, full-document reads, and source citation — served directly by the API, with curl and npx skills options.

Caesar ships [agentskills.io](https://agentskills.io)-format skills that teach an agent to search, read full documents, and cite sources.

For the fastest single-skill install, use the Skills CLI:

```bash theme={"system"}
npx skills add caesar-data/skills --skill caesar-search
```

To install the full API-served bundle, use the Caesar installer:

```bash theme={"system"}
curl -fsSL https://alpha.api.trycaesar.com/skills/install.sh | bash
```

The installer adds the skills into `~/.claude/skills/` and a `caesar-subagent` definition into `~/.claude/agents/` (Claude Code's default locations), then prints: restart your agent session or run `/caesar-setup` to pick them up.

## Two install paths

| Path          | Command                                                                | Use when                                                           |
| ------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Skills CLI    | `npx skills add caesar-data/skills --skill caesar-search`              | You want the quickest install into an agent that supports skills.  |
| API installer | `curl -fsSL https://alpha.api.trycaesar.com/skills/install.sh \| bash` | You want all four skills and the Claude Code subagent in one step. |

Agents that use the `skills` npm CLI can install from the GitHub shorthand instead:

```bash theme={"system"}
npx skills add caesar-data/skills --skill '*' -g -y
```

To install only the runtime search skill:

```bash theme={"system"}
npx skills add caesar-data/skills --skill caesar-search -g -y
```

Use the repository source (`caesar-data/skills`) plus `--skill ...`; bare `npx skills add caesar-search` is not a valid source.

For Claude Code, prefer the curl installer because it also writes `~/.claude/agents/caesar-subagent.md`. The `npx skills` path installs the `SKILL.md` folders only.

## Served by the API itself

The `SKILL.md` files are embedded in the API server and served from `/skills` routes — so the API-hosted installer ships with every API deploy. They are also mirrored to the public [`caesar-data/skills`](https://github.com/caesar-data/skills) repo for `npx skills add`. The `/skills` routes require no authentication.

To update skills later, re-run the same installer. New skill content arrives with API deploys; the installer always fetches the latest version.

## The four skills

| Skill                   | What it teaches                                                                                                                                                                     |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `caesar-search`         | Default for web search, research, lookups, and questions that need information from the web. Results include `doc_id`s you can read as focused excerpts or full documents and cite. |
| `caesar-read`           | Read a web page as clean markdown with provenance. Use when you already have a URL or `doc_id`. Handles long pages with character-offset continuation.                              |
| `caesar-setup`          | Install, authenticate, verify, and update the `caesar-search` CLI. Run once, then use the other skills for actual searching.                                                        |
| `caesar-best-practices` | Reference for implementing Caesar in code — choosing between the CLI, SDKs, MCP server, and raw HTTP, plus cross-surface conventions.                                               |

## Routes

| Route                                   | Returns                                                          |
| --------------------------------------- | ---------------------------------------------------------------- |
| `GET /skills`                           | JSON index of skills, agents, and the install one-liner          |
| `GET /skills/{skill}/SKILL.md`          | Skill markdown (the four names above; anything else returns 404) |
| `GET /skills/agents/caesar-subagent.md` | The subagent definition                                          |
| `GET /skills/install.sh`                | The installer script                                             |

Browse what's available:

```bash theme={"system"}
curl -s https://alpha.api.trycaesar.com/skills
```

Each entry in the index has `name`, `description`, and `url` fields, so an agent can discover and fetch skills without the installer.

## Installing for other agents

The skill files are standard agentskills.io markdown. Any agent that reads `SKILL.md` files can use them. Use the Skills CLI when available:

```bash theme={"system"}
npx skills add caesar-data/skills --skill caesar-search
```

Or point the API installer at your agent's skills directory:

```bash theme={"system"}
curl -fsSL https://alpha.api.trycaesar.com/skills/install.sh | CAESAR_SKILLS_DIR=~/.agents/skills bash
```

| Variable                 | Effect                                                                                                                                                                            |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CAESAR_SKILLS_DIR`      | Install the skills into this directory instead of `~/.claude/skills`. When set, the `caesar-subagent` file is **not** installed — subagent definitions are a Claude Code concept. |
| `CAESAR_SKILLS_BASE_URL` | Download from a different API base URL (defaults to the host that served the script).                                                                                             |

<Note>
  For non-Claude agents, the `context: fork` and `agent` frontmatter fields are ignored and the skills still work inline.
</Note>

## How the runtime skills stay context-efficient

`caesar-search` and `caesar-read` declare `context: fork` and `agent: caesar-subagent` in their frontmatter. When invoked, the skill runs in a forked context executed by the `caesar-subagent` — a Bash-only subagent — so raw search and read JSON never lands in the main conversation's token budget. Only the distilled answer comes back.

Because the subagent has no file-read tool, the skills write CLI output with `-o /tmp/$SLUG.json` (which suppresses stdout so harness limits can't truncate it) and the subagent reads the file with `cat`. The subagent's hard rules: only cite URLs that appear in command output, preserve `doc_id` and `search_id` verbatim, and report the output file path so the main context can reference it later without re-searching.

## Relationship to the CLI

The skills are thin drivers for the [`caesar-search` CLI](/clients/cli/usage) — they run `caesar-search search`, `caesar-search read`, and friends rather than calling the API directly. If the CLI is missing, `caesar-setup` walks through [installing it](/clients/cli/install).

The runtime skills also carry a version gate: if the CLI rejects a flag or command as unknown, the installed CLI is outdated — the runtime skills (`caesar-search`, `caesar-read`) instruct the agent to run `caesar-search update` and retry. `caesar-search update` detects its install channel (npm, Homebrew, or standalone) and upgrades in place.

<Note>
  Strict agentskills.io validators flag the Claude Code extension frontmatter fields (`context: fork`, `agent`, `user-invocable`, `argument-hint`) as unknown. This is intentional — consumers ignore unknown fields. Don't "fix" these validation warnings.
</Note>

## For agents

* Install the search skill with `npx skills add caesar-data/skills --skill caesar-search`, or install the full bundle with the API installer above. Then invoke `/caesar-setup` once where available to verify the CLI and auth. Runtime search and read calls require `CAESAR_API_KEY` or a key stored with `caesar-search auth login`. After that, use `/caesar-search` for queries and `/caesar-read` for URLs or `doc_id`s.
* No installer access? Fetch the skill content directly — `GET /skills` lists every URL, and each `/skills/{skill}/SKILL.md` is plain markdown. These installer routes are public.
* The skill names are a server-side allowlist (`caesar-search`, `caesar-read`, `caesar-setup`, `caesar-best-practices`). Unknown names return a 404 envelope whose `hint` says to `GET /skills`.
* Runtime skills use the CLI and require API auth. Never paste a literal key into chat — use `caesar-search auth login` or the `CAESAR_API_KEY` env var.
* Skills do not auto-update. Re-run the curl installer to refresh them; only the CLI itself self-updates via `caesar-search update`.