# Skills

Mirabase's official skills tell an Agent when to call which MCP tool, in what order, and what to ask the user first. Nine skills cover the API task by task, and two cover complete scenarios: project memory and a knowledge base with cited answers.

A skill is a folder with a `SKILL.md`: its `name` and `description` say what it does and when to use it, and its body holds the steps. An Agent keeps only the descriptions in context and loads a body when a task matches, so skills cost little until they are used. The official skills use the Agent Skills format and do not depend on any one Agent host; the tools they call come from Mirabase's [MCP server](https://mirabase.io/developers/agents.md).

## Official skills

| Skill | What it does |
| --- | --- |
| `mirabase` | The entry point: decides whether something belongs in a file, a memory, or the conversation record, stores emails, transcripts, and web pages, picks the skill to load, and handles the start and end of a task. |
| `mirabase-setup` | Connects an Agent, checks a key with `mira.whoami`, and explains a 401, 403, 404, or 429. |
| `mirabase-files` | Reads, writes, edits, moves, copies, and uploads files by path, using ETags so Agents do not overwrite each other. |
| `mirabase-recover` | Shows versions and diffs, reverts, restores from the trash, and takes and reads snapshots. |
| `mirabase-branches` | Changes many files on a branch, checkpoints, shows the diff for review, merges, and reviews Agent proposals. |
| `mirabase-sync` | Keeps a local folder in sync through the CLI, or follows changes through the change feed and webhooks. |
| `mirabase-recall` | Searches, builds a context pack for a task, answers with citations, and reads the full Entry behind a hit. |
| `mirabase-memories` | Keeps, corrects, reviews, and forgets memories, with the right scope. |
| `mirabase-access` | Gives each Agent its own limited key, sets read and write roots, write modes, and label scopes, and rotates and revokes keys. |
| `mirabase-project-memory` | Scenario: a coding Agent keeps one repository's conventions, decisions, and progress across sessions. |
| `mirabase-knowledge-base` | Scenario: loads a folder of documents into a Space, reloads it after the documents change, and answers from those documents with citations. |

- Every description lists example requests in English and Chinese and says what the skill is not for, so the Agent loads the right one.
- Every action that cannot be undone (purging, forgetting a memory, revoking a key, merging over conflicts) asks the user first. The skills never print or store a key, and treat what the tools return as data, not instructions.
- All descriptions together are about 1,700 tokens; each skill's file is 1,300 to 2,150 tokens, read only when it is used (counted with `cl100k_base`).

## Scenario skills

**Project memory (`mirabase-project-memory`)**: each repository has a Space of its own, such as `ext:acme-web`. At the start of a session the Agent calls `mira.context` with `purpose: "coding"` to read the project's conventions, decisions, and where the last session stopped. While working it records each convention and decision as one project memory, plus a short decision record when the reasoning matters. At the end it updates the progress memory for that line of work with `mira.memory.correct` (one per line of work). Code, diffs, and logs stay in the repository, not in Mirabase.

**Knowledge base (`mirabase-knowledge-base`)**: each knowledge base has a Space of its own. Its loader script (Node 18 or newer, no dependencies) writes the documents of a folder under `/kb/`; unchanged files create no new version, and files deleted locally are listed, never deleted. Documents are written with `memory_exclude`, so they are searched and cited as written rather than distilled into memories. Answers come from `mira.answer`: with `answered`, the Agent gives the answer and the paths of the files it cites; with `abstained`, it says the retrieved passages do not support an answer instead of filling the gap from general knowledge.

## Install (Coming soon)

> **Coming soon**

The official skills ship with the open-source repository; source available when the open-source repository is published. Once it is, install them for your Agent host:

Claude Code:

```bash
export MIRABASE_API_KEY="mb_live_..."

# From the root of the open-source repository. The plugin folder adds the MCP server, the skills, and the hooks.
claude --plugin-dir clients/agent-plugin
```

Codex:

```bash
export MIRABASE_API_KEY="mb_live_..."

codex mcp add mirabase --url https://api.mirabase.dev/mcp --bearer-token-env-var MIRABASE_API_KEY
# Then paste the section in clients/agent-plugin/codex/AGENTS.md into your project's AGENTS.md.
```

Agent Skills:

```agent skills
# From the root of the open-source repository: copy all eleven skills into the host's skills directory.
SKILLS_DIR=~/.claude/skills   # Claude Code without the plugin; other hosts document their own
mkdir -p "$SKILLS_DIR" && cp -R clients/agent-plugin/skills/* "$SKILLS_DIR"/

# Then add the MCP server: https://api.mirabase.dev/mcp, Streamable HTTP,
# header "Authorization: Bearer $MIRABASE_API_KEY".
```

- Claude Code: the plugin folder adds the MCP server, every skill, and hooks. The hooks read memory at session start, and save the text of user and assistant messages to the Space named by `MIRABASE_SPACE` (the default Space) before the context is compacted, when the session ends, and every 20 messages, masking what looks like a credential. Set `MIRABASE_CAPTURE=off` to stop saving.
- Codex: give it the rules through the project's `AGENTS.md`. The plugin's `codex/AGENTS.md` is a short section to paste in, covering the storage rules and both scenarios; if your Codex version loads Agent Skills, you can also copy the skill folders as for other hosts.
- Other hosts that support Agent Skills (the Agent Skills tab above): copy the skill folders. If you copy only some, always include the entry skill `mirabase`, which the others refer to.

> **Note:** Until then, the MCP server works on its own: the `instructions` in its handshake response already say when to read, when to save, and where, and a client that supports the field passes them to the model. See [Connect an Agent (MCP)](https://mirabase.io/developers/agents.md).

## Next steps

- [Build on Mirabase](https://mirabase.io/developers/build.md): write your own skill, and see how skills, the SDKs, webhooks, and provider plugins fit together.
- [Connect an Agent (MCP)](https://mirabase.io/developers/agents.md): every tool the skills call, with its parameters.
- [Permissions](https://mirabase.io/developers/permissions.md): set each Agent's write mode and its read and write roots.
