# 技能（Skills）

Mirabase 官方技能：告诉 Agent 何时调用哪个 MCP 工具、按什么顺序、哪些操作先征得用户同意。包括九个按任务划分的技能，以及项目记忆和带引用知识库两个完整场景。

技能是一个文件夹，里面有一个 `SKILL.md`：开头的 `name` 和 `description` 说明它做什么、何时使用，正文是步骤。技能描述常驻 Agent 的上下文，正文在任务匹配时才加载，所以技能在使用前占用很少。官方技能采用 Agent Skills 格式，不依赖特定的 Agent 平台；它们调用的工具来自 Mirabase 的 [MCP 服务](https://mirabase.io/zh/developers/agents.md)。

## 官方技能

| 技能 | 用途 |
| --- | --- |
| `mirabase` | 入口技能：判断内容应存为文件、记忆还是对话记录，保存邮件、会议记录和网页，选择要加载的技能，处理任务的开始与结束。 |
| `mirabase-setup` | 连接 Agent，用 `mira.whoami` 检查 Key，解释 401、403、404 和 429。 |
| `mirabase-files` | 按路径读写、编辑、移动、复制和上传文件，用 ETag 避免覆盖他人的修改。 |
| `mirabase-recover` | 查看版本与差异、回滚、从废纸篓恢复、创建和读取快照。 |
| `mirabase-branches` | 在分支上修改多个文件、设检查点、展示差异供审查后合并，以及审查 Agent 的提案。 |
| `mirabase-sync` | 通过 CLI 同步本地目录，或通过变更流和 Webhook 跟踪变化。 |
| `mirabase-recall` | 搜索、为任务获取上下文包、带引用回答，并读取检索结果对应的完整 Entry。 |
| `mirabase-memories` | 记住、更正、审核和遗忘记忆，并选择正确的范围。 |
| `mirabase-access` | 为每个 Agent 签发受限的 Key，设置读写根路径、写入模式和标签范围，轮换和吊销 Key。 |
| `mirabase-project-memory` | 场景：编程 Agent 在多次会话之间保留一个仓库的约定、决定和进度。 |
| `mirabase-knowledge-base` | 场景：把一个文档目录载入 Space，文档更改后重新载入，并基于这些文档带引用回答。 |

- 每个描述都包含中英文的示例请求，并写明不适用的情形，帮助 Agent 加载正确的技能。
- 不可撤销的操作（彻底删除、遗忘记忆、吊销 Key、覆盖式合并）都要求先征得用户同意。技能从不打印或保存 Key，并把工具返回的内容当作数据而不是指令。
- 全部描述合计约 1,700 个 token；单个技能文件在 1,300 到 2,150 个 token 之间，只在使用时读取（按 `cl100k_base` 计）。

## 场景技能

**项目记忆（`mirabase-project-memory`）**：每个仓库使用一个独立的 Space（如 `ext:acme-web`）。会话开始时以 `purpose: "coding"` 调用 `mira.context`，从项目记忆中读取约定、决定和上次的进度；工作中把约定和决定各记为一条项目记忆，需要说明理由的决定另写一份简短的决定记录；会话结束时用 `mira.memory.correct` 更新这项工作的进度记忆（每项独立任务各保留一条）。代码、差异和日志不写入 Mirabase，它们已在仓库里。

**知识库（`mirabase-knowledge-base`）**：每个知识库使用一个独立的 Space。附带的载入脚本（Node 18 或更新版本，无依赖）把目录中的文档写到 `/kb/` 下，内容相同的文件不产生新版本，本地已删除的文件只列出、不删除；文档以 `memory_exclude` 写入，按原文检索和引用，不提炼为记忆。回答使用 `mira.answer`：`answered` 时给出答案和所引用文件的路径，`abstained` 时说明检索到的内容不足以回答，不用通用知识补充。

## 安装（即将上线）

> **即将上线**

官方技能与开源仓库一同发布，源代码在开源仓库发布后提供。发布后，按所用的 Agent 平台安装：

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：插件目录一次加入 MCP 服务、全部技能和钩子。钩子在会话开始时读取记忆，并在上下文压缩前、会话结束时以及每 20 条消息时，把用户和助手的文字保存到 `MIRABASE_SPACE` 指定的 Space（默认 Space），保存时遮盖疑似凭据；设置 `MIRABASE_CAPTURE=off` 可关闭保存。
- Codex：通过项目的 `AGENTS.md` 提供规则。插件中的 `codex/AGENTS.md` 是一段可粘贴的简短规则，覆盖存储规则和两个场景；如果你的 Codex 版本支持加载 Agent Skills，也可以像其他平台一样复制技能文件夹。
- 其他支持 Agent Skills 的平台（示例中的 Agent Skills 选项卡）：复制技能文件夹。只复制一部分时，务必包含入口技能 `mirabase`，其他技能会引用它。

> **说明：** 在此之前，MCP 服务已可直接使用：握手响应的 `instructions` 已说明何时读取、何时保存、保存到哪里，支持该字段的客户端会把它交给模型。连接方式见 [连接 Agent（MCP）](https://mirabase.io/zh/developers/agents.md)。

## 下一步

- [基于 Mirabase 开发](https://mirabase.io/zh/developers/build.md)：编写自己的技能，并了解技能、SDK、Webhook 和供应商插件如何配合。
- [连接 Agent（MCP）](https://mirabase.io/zh/developers/agents.md)：技能调用的全部工具及其参数。
- [权限](https://mirabase.io/zh/developers/permissions.md)：为每个 Agent 设置写入模式和读写根路径。
