diff --git a/README.md b/README.md
index 962668e..1b49d28 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@ FlashGrep is an open-source project in the [openBitFun](https://github.com/openB
Search the index first, then verify only the small set of relevant files.
-[中文](#中文) · [Architecture](#architecture) · [MCP integration](#mcp-integration)
+[中文](#中文) · [Install FlashGrep for AI agents](#install-flashgrep-for-ai-agents) · [Architecture](#architecture) · [MCP integration](#mcp-integration)
## Why FlashGrep
@@ -140,6 +140,92 @@ A minimal MCP configuration looks like this:
The full host-specific setup, release bundle layout, tool schemas, and option reference are in [`mcp/README.md`](mcp/README.md).
+## Install FlashGrep for AI agents
+
+The release MCP bundle is the recommended installation path for agents that support MCP. It contains the Node.js MCP bridge, the six platform binaries, and the reusable `flashgrep-search` skill in one archive.
+
+Download the [latest release](https://github.com/openBitFun/FlashGrep/releases/latest) or pin the current [v0.2.17 release](https://github.com/openBitFun/FlashGrep/releases/tag/v0.2.17). The direct bundle link is [`flashgrep-mcp.zip`](https://github.com/openBitFun/FlashGrep/releases/latest/download/flashgrep-mcp.zip). Extract it to a stable directory and use that directory as `` below. Node.js 18 or newer is required.
+
+### Configure the MCP server
+
+For a host that opens the current workspace automatically, add this server entry and replace `` with the extracted bundle path:
+
+```json
+{
+ "mcpServers": {
+ "flashgrep": {
+ "command": "node",
+ "args": [
+ "/server.js"
+ ]
+ }
+ }
+}
+```
+
+Use the entry in the host's MCP configuration. Cursor uses a project-level `.cursor/mcp.json`. Trae uses its MCP server settings. Claude Code can use a project-level `.mcp.json` with the stdio form:
+
+```json
+{
+ "mcpServers": {
+ "flashgrep": {
+ "type": "stdio",
+ "command": "node",
+ "args": [
+ "/server.js"
+ ],
+ "env": {}
+ }
+ }
+}
+```
+
+Codex uses `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.flashgrep]
+command = "node"
+args = ["/server.js"]
+```
+
+To pin the server to a repository, add `"--repo", ""` to the JSON `args` array or `"--repo", ""` to the TOML `args` array. Without that option, the server uses the current workspace. Tool calls can also pass `repo_path` when an agent needs to search another workspace.
+
+### Install the optional search skill
+
+The bundle includes the skill at:
+
+```text
+/skills/flashgrep-search
+```
+
+Copy that directory into the host's local skill directory and keep `SKILL.md` and `agents/openai.yaml` together. For example, a Codex installation can use:
+
+```bash
+mkdir -p ~/.codex/skills
+cp -R "/skills/flashgrep-search" ~/.codex/skills/flashgrep-search
+```
+
+The MCP server provides the search tools. The skill tells an agent to use `glob_files` for file discovery and `search_code` for content searches, to continue while the index builds in the background, and to fall back to built-in search only when FlashGrep cannot open the workspace.
+
+Agents without a local skill mechanism can add the following text to their project or system instructions:
+
+```text
+For repository search, prefer FlashGrep MCP.
+Use glob_files for file discovery and search_code for content or pattern matching.
+Do not wait for index construction.
+Fall back to built-in search only when FlashGrep MCP is unavailable or cannot open the workspace.
+```
+
+### Verify the installation
+
+Ask the agent to run a search through FlashGrep:
+
+```text
+Use FlashGrep MCP to search for ManagedDaemonClient in the current workspace.
+```
+
+The agent should call `search_code`. `repo_status` can be used first when you need to confirm the repository path and index state.
+
## Architecture
FlashGrep has a clear split between the stable integration surface and the index implementation:
@@ -248,6 +334,54 @@ FlashGrep 是 openBitFun 组织下的高性能代码检索引擎,也是 OpenBi
- `published`、`reconciled`、`filesystem` 三种查询新鲜度;
- Linux、macOS、Windows 的 release 构建和 MCP 分发包。
+## 给其他 AI Agent 安装 FlashGrep
+
+推荐直接使用 [最新 Release](https://github.com/openBitFun/FlashGrep/releases/latest) 中的 [`flashgrep-mcp.zip`](https://github.com/openBitFun/FlashGrep/releases/latest/download/flashgrep-mcp.zip)。当前固定版本是 [v0.2.17](https://github.com/openBitFun/FlashGrep/releases/tag/v0.2.17)。压缩包已经包含 MCP server、六个平台的后端二进制和 `skills/flashgrep-search`。
+
+解压后把目录记为 ``,确认 Node.js 版本不低于 18,然后在 Agent 的 MCP 配置中加入:
+
+```json
+{
+ "mcpServers": {
+ "flashgrep": {
+ "command": "node",
+ "args": ["/server.js"]
+ }
+ }
+}
+```
+
+Cursor 使用项目级 `.cursor/mcp.json`,Trae 使用 MCP server 设置,Claude Code 使用项目级 `.mcp.json`。Codex 在 `~/.codex/config.toml` 中加入:
+
+```toml
+[mcp_servers.flashgrep]
+command = "node"
+args = ["/server.js"]
+```
+
+默认搜索当前工作区。需要固定仓库时,在 `args` 中加入 `--repo` 和仓库路径。跨目录搜索也可以在工具调用里传 `repo_path`。
+
+支持 Skill 的 Agent 可以把以下目录复制到本地 Skill 目录:
+
+```text
+/skills/flashgrep-search
+```
+
+该 Skill 会让 Agent 优先使用 `glob_files` 和 `search_code`,不等待索引构建,并在 MCP 无法打开工作区时回退内建搜索。没有 Skill 机制的 Agent 可以把这段规则加入项目或系统指令:
+
+```text
+For repository search, prefer FlashGrep MCP.
+Use glob_files for file discovery and search_code for content or pattern matching.
+Do not wait for index construction.
+Fall back to built-in search only when FlashGrep MCP is unavailable or cannot open the workspace.
+```
+
+安装后让 Agent 执行一次 `search_code` 搜索即可验证,例如:
+
+```text
+请使用 FlashGrep MCP 在当前工作区搜索 ManagedDaemonClient。
+```
+
从源码构建和启动:
```bash