# For AI agents

> Give your AI coding agent the Oasis API docs as plain text, or install the oasis-api skill.

Source: https://oasis-protection.com/docs/api/ai-agents/

Oasis is new, so AI coding agents don’t know it. An agent that hasn’t read the docs guesses at an API it has never seen, and the code it writes won’t compile. Give it the real API: this site serves the docs as plain text, and the `oasis-api` skill teaches an agent the API in one file.

## The docs as plain text

| URL                                        | Holds                                                                         |
| ------------------------------------------ | ----------------------------------------------------------------------------- |
| [`/llms.txt`](/llms.txt)                   | An index of the site, with a link to each set below. Start here.              |
| [`/llms-full.txt`](/llms-full.txt)         | Every page of the site, in full.                                              |
| [`/llms-small.txt`](/llms-small.txt)       | Every page of the site, shortened.                                            |
| [`/_llms-txt/api.txt`](/_llms-txt/api.txt) | The developer API pages only. The best fit for an agent that writes a plugin. |

Every page also has a Markdown copy at its URL with `.md` added. This page is at [`/docs/api/ai-agents.md`](/docs/api/ai-agents.md), and [Running operations](/docs/api/operations/) is at [`/docs/api/operations.md`](/docs/api/operations.md). Each HTML page also points to its copy with a `<link rel="alternate" type="text/markdown">` tag, so an agent that reads the page can find it.

To give an agent the whole API, paste this into your prompt:

```plaintext
Read https://oasis-protection.com/_llms-txt/api.txt before you write any code that uses the Oasis API.
```

## The oasis-api skill

The `oasis-api` skill teaches an agent the Oasis API in one file. Your agent loads it when a task needs block logging, rollbacks or lookups on a server that runs Oasis. The skill changes with the API, so install it in a way that keeps it current.

### Claude Code

Add the Oasis marketplace and install the plugin:

```plaintext
/plugin marketplace add oasis-protection/skills
/plugin install oasis-api@oasis
```

Then turn on updates, once: run `/plugin`, open **Marketplaces**, select `oasis`, and select **Enable auto-update**. Claude Code then brings in each new version of the skill when a session starts.

### Codex

Terminal window

```sh
codex plugin marketplace add oasis-protection/skills
codex plugin add oasis-api@oasis
```

Run `codex plugin marketplace upgrade oasis` to bring in a new version.

### Any other agent

For Cursor and the other agents that read skills, install it with the `skills` tool:

Terminal window

```sh
npx skills add oasis-protection/skills --skill oasis-api
```

The `skills` tool doesn’t update a skill on its own. Run `npx skills update` now and then to get the newest version. A skill installed this way reminds you: your agent tells you to run the command, and never runs it for you.

All three install the same skill from the [`oasis-protection/skills`](https://github.com/oasis-protection/skills) repository.

### What the skill teaches

* **Depend on it.** The repository, the coordinates, `compileOnly` or `provided`, `depend` or `softdepend`, and `Oasis.api(this)` in `onEnable`.
* **Read history.** `find`, `history`, `kept`, pages of eight, and `next()`. How to build a `Selection`, leave edits out with `not()`, why an empty list throws, and how to handle a read that fails with an `OasisException`.
* **Log an edit.** The `EditLog` methods, which `block` form keeps a chest’s items, which forms read on the calling thread, and the causes only Oasis writes.
* **Run an operation.** Requests, `requestedBy`, `audience`, `estimate()`, `start()`, `type()`, kept and left, `forceKept()`, cancel, one operation at a time, and the failure reasons.
* **Purge history.** Requests, `count()`, `start()`, a purge of whole worlds, a world that is not loaded, one purge at a time, and the failure reasons.
* **Load the worlds a plugin keeps.** A `WorldLoader` with `owns`, `load` and `release`, the hold between `load` and `release`, and `WORLD_GONE` for a world nobody can load.
* **Threads.** Every future completes on the main thread, the logger takes edits from any thread, and an agent never calls `join()` on the main thread.
* **Nothing counts.** Why a page has no total, and where a size comes from instead.
* **The person and the actor.** What each one is, and how the logger and the reader use the same two words.
* **The vocabulary.** The kinds, causes and actors, and the rule to start an operation rather than change the world back by hand.