outline-wiki-search

Outline Wiki Search

Through Outline Wiki MCP'sread-onlyoperation capabilities (search + read), locate documents in the workspace, and get the Markdown source and metadata. This skill is thesmallest one in the outline-wiki-* family—only 1 / 2 of the core capabilities (search / read), with no write operations.

Write / edit / upload related operations are handled by outline-wiki-upload SKILL.md is responsible; MCP configuration is handled by outline-wiki-setup SKILL.md is responsible.

When to use / not use

Use

• The user mentions in the conversation "search outline / find outline documents / search in the outline workspace"
• The user provides a document ID and asks to "read this document / get this markdown / open this outline"
• Need full-text search by keyword to match a document list
• Need to get a document's Markdown source + metadata (creation time / author / Collection, etc.)
• Need to first search to check for duplicates / locate, then decide the next action (regardless of whether the next step is upload or edit)

Do not use

• Write / edit / upload outline documents(including image attachments / @mention / comments / Collection management / move / delete / archive)—go to outline-wiki-upload SKILL.md
• Configure outline MCP(first-time setup / not visible after restart / 401)—go to outline-wiki-setup SKILL.md
• The user uses another wiki / knowledge base product (Notion / Confluence / Obsidian / GitHub Wiki)
• Sharing, export, permission adjustments (not listed in the official MCP documentation, and usually not exposed by the server)— go to the Outline Wiki UI itself or call the REST API directly
• Before a write operation, "read first"—this is the prerequisite step of outline-wiki-upload's "read - modify" process,notthis skill's scenario; when the user says "I want to modify this one," go directly to upload

Input / Output

Input

At startup, the followingprerequisitesmust be present—these are handled by outline-wiki-setup is responsible:

• MCP is registered: the current session can call the mcp__outline__* series of tools (if not registered,first go to outline-wiki-setup SKILL.md, and come back after running and restarting**)
• User natural language instruction: search keyword / document ID

Output

• Search results: matching document list (including ID, title, summary)
• Document content: metadata (title / Collection / time / author, etc.) goes through MCP fetch； Markdown bodyBecause Claude Code truncates MCP multiple content blocks (see §Core Principles #5) it needs to go through the REST bypass POST /api/documents.info
• Error message: tool name mismatch / invalid document ID / connection refused, etc.

MCP tool discovery (important)

This skill does not hardcode any tool names—at the start of the session, you must first call MCP's tools/list Endpoint: verify the tool names, parameter schemas, and return structures actually exposed by the current MCP server, then call accordingly. Convention: "search / read" etc. appearing below refer tocapabilitiesrather than specific tool names; before calling, first tools/list to get the real tool names and then map them.

Different self-hosted deployments may have slightly different tool sets; extended capabilities (such as comments / image attachments) also depend on what tools/list actually returns—but this skill only uses the two core capabilities, search / read.

Capability List

Divided into two groups by "tool source".Core CapabilitiesCorresponds to the search / read two of the 4 high-level operations explicitly listed in the official documentation;Extended CapabilitiesCorresponds to write operations not explicitly listed in the official documentation (outside the scope of this skill, handled by outline-wiki-upload ).

Core Capabilities

1. Search

Performs a full-text search in the workspace by keyword, returning a list of matching documents.

Typical parameters (specifically subject to what tools/list actually returns):

• query: search keyword (required)
• collection_id(optional): limit the Collection scope
• limit / offset(optional): pagination

2. Read

Retrieves by document ID themetadata(title / Collection / time / author, etc.).The body (Markdown body) cannot be read in Claude Code—see the "Body Reading" note below.

Typical parameters:

• id(required): document ID
• Returns (MCP fetch in CC): title + metadata,no text body

Body Reading (Important)：Outline MCP fetch(document) server sidedoes return the body— the response contains 2 text content blocks: block[0] = JSON metadata, block[1] = full markdown body (curl direct connection to /mcp measured num_blocks: 2）。but Claude Code's MCP client only presents the first content block, block[1]'s body is discarded, so in CC fetch only metadata is visible. This is known behavior on the CC client side (a multi-content-block handling defect),not an Outline server issue. To get the body, use REST POST /api/documents.info(for curl see §Troubleshooting item 1); remove the bypass once CC fully supports multiple blocks,fetch directly returns the body.

Execution Principles / Boundaries

Core Principles

1. Search before writing (Read-First collaboration)
   • This skill itselfis read-only, but it often serves as the "search before writing" preliminary step for outline-wiki-upload; when the agent judges "should this go through search or upload", it looks at whether the user's intent includes a write action ("find it and change it" → upload; "find it and tell me the content" → search)
2. Tool name verification (Tools-First)
   • Do not assume the spelling of tool names or whether they have a prefix (such as outline_）
   • Before any operation, first tools/list get the real tool list
3. Do not assume the tool set
   • The core search / read are usually stably exposed; but across self-hosted deployments there may still be differences
4. Result presentation
   • Search results are displayed sorted by relevance; do not directly read by cached ID (documents may be archived / renamed)
5. Read the body via the REST bypass (CC truncates multiple content blocks, measured 2026-07-01)
   • Outline MCP fetch(document) The server returns 2 content blocks (metadata + body),Claude Code only presents the first, the body is dropped—a CC client-side issue, not server
   • Get the body via REST POST /api/documents.info(for curl see §Troubleshooting item 1); metadata still uses MCP fetch, the two paths divide the work
   • list_documents returns a single block and is unaffected; its context is a body fragment (for short documents it's close to the full text, for long documents it gets truncated,don'tjudge the full text based on this)
   • Once CC fully supports multiple content blocks, revoke the REST bypass

Boundaries

• Do nothandle knowledge bases that are not Outline Wiki
• Do notattempt operations when MCP is not enabled (first go through outline-wiki-setup）
• Do notperform any write operations (create / edit / move / delete / archive / comment)— use outline-wiki-upload
• Do notbypass tools/list and call tools from "impression"

Workflow / Steps

Standard process

1. Verify configuration and tools: at the start of the session—
   • confirm that the outline-related MCP tools are registered in the current session; if not registered,first go through outline-wiki-setup SKILL.md, and after the run completes and restarts, come back
   • call MCP tools/list to get the actual tool names and parameter schemas for search / read
2. Understand the intent: map the user's natural language instruction to search or read
3. Execute the operation：
   • search → by keyword + optional collection_id + pagination parameters (MCP list_documents, returns metadata + context excerpt fragments, works normally)
   • read metadata → MCP fetch(resource=document, by document ID)
   • read body → MCP fetch cannot be obtained in CC (§Core principles #5), use REST POST /api/documents.info(§Troubleshooting item 1)
4. Verify the result: check whether the return succeeded
5. Report: tell the user the list of documents found / the Markdown source read / the metadata
6. Handoff(optional): if the user subsequently wants to write / edit the currently found document, clearly tell them "the next step goes through outline-wiki-upload"

Troubleshooting

Diagnose in the following order:

1. fetch returns only metadata and the body cannot be read (most common) — caused by Claude Code truncating MCP multiple content blocks (§Core principles #5),notan empty document / wrong ID / authentication problem, don't troubleshoot in those directions. Get the body via the REST bypass below; or list_documents(query) 's context to get a body fragment (for short documents it's close to the full text, for long documents it gets truncated)
2. Tool name mismatch — re-call tools/list to get the current tool list; don't call from memory
3. Invalid document ID — Use search to relocate and get a new ID; do not call with a cached ID (the document may have been archived / renamed)
4. Authentication failure (401 / 403) — outline-wiki-setup scope (key expired / OAuth invalid), restart first or rerun the configuration script
5. MCP not enabled / connection refused — go to outline-wiki-setup to troubleshoot the configuration

Read body via REST bypass(failure item 1 expanded) — token / <base> same as MCP configuration (same key as the MCP server, already written during setup):

# <base> = outline MCP url 去掉尾部 /mcp
curl -sS -X POST "<base>/api/documents.info" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"id":"<docId>"}' | jq -r '.data.text'

<token> location, see outline-wiki-setup the scope at that time:

• user → ~/.claude.json#mcpServers.outline.headers.Authorization
• project → repository root .mcp.json
• local → ~/.claude.json#projects.<path>.mcpServers.outline

Reference examples

Example 1: Search existing documents

User instruction: "Help me search Outline Wiki for documents related to 'CI deployment process'"

Execution：

1. 确认 mcp__outline__* 工具已在 session 注册（否则先走 outline-wiki-setup）
2. 调用 tools/list 拿到 search 工具的实际名称
3. 调用 search 工具，query="CI 部署流程"，limit=10
4. 整理返回的文档列表，按相关度展示给用户
5. 若用户要打开某篇，再用 read 工具拉取正文

Example 2: Read by document ID

User instruction: "Show me the Markdown source of the document doc_abc123"

Execution：

1. 调用 tools/list 拿到 read 工具的实际名称
2. MCP fetch(resource=document, id="doc_abc123") → 标题 + 元数据
   （Collection / 时间 / 作者）；正文因 CC 截断多 block 拿不到（§核心原则 #5）
3. 拿正文走 REST：POST /api/documents.info {"id":"doc_abc123"} → data.text
4. 把标题 + 元数据 + Markdown 正文一并展示
5. 若用户后续要"改这篇"，明确告知下一步走 outline-wiki-upload

Example 3: search duplicate check (in collaboration with upload)

User instruction: "I want to create a new 'Cache Strategy' document under the 'Backend' Collection, first help me check if there is a duplicate name"

Execution：

1. 调用 search 工具，query="缓存策略"，collection_id=<后端 Collection ID>
2. 列出已有同名 / 相似标题文档
3. 若无 → 提示用户可走 outline-wiki-upload 创建
4. 若有 → 提示用户走 outline-wiki-upload 的"编辑已有文档"流程（不新建重复）

Related references

• outline-wiki-setup SKILL.md — companion: MCP configuration and first-time onboarding
• outline-wiki-upload SKILL.md — companion: write / edit outline documents
• Out of scope for this skill：
  • Document style (outline-wiki-upload/references/doc_style.md) — refer to when writing
  • Style checklist (outline-wiki-upload/references/style_checklist.md) — check against when writing