outline-wiki-management

Outline Wiki Management

Through the built-in MCP service (Model Context Protocol) provided by Outline Wiki, in the conversation directly perform on the documents within its workspacesearch, read, create, edit, as well as the accompanying extended capabilities (image / file attachments, @mention, comments, Collection management, move / delete, etc.). This skill divides capabilities into two groups based on "tool source":

Core capabilities（Outline official MCP documentation the 4 listed): search / read / create / edit
Extended capabilities(actually exposed by the server but not explicitly listed in the official documentation): image attachment, @mention, comment, Collection management, move / delete

For extended capabilities not listed in the official documentation, before use verify via tools/list whether the server exposes the corresponding tools; different self-hosted deployments may have slightly different tool sets.

When to use / not use

Use

The user explicitly mentions Outline Wiki in the conversation
Need to search documents by keyword in an Outline Wiki workspace
Need to read the Markdown source and metadata of a document
Need to create a new document under a specified Collection
Need to update the title or Markdown body of an existing document
The client is Claude Code / Claude Desktop / Cursor / another MCP client that supports Streamable HTTP transport

Do not use

The user uses another wiki / knowledge base product (Notion / Confluence / GitHub Wiki / local Markdown folder / Obsidian, etc.)
Sharing, exporting, permission adjustments (not listed in the official MCP documentation and usually not exposed by the server either)— use the Outline Wiki UI itself or call the REST API directly
Needcolor highlightingand other rich-text features that Markdown cannot express (create_document / update_document does not accept raw ProseMirror nodes)—use the UI or call the REST API directly with the proseMirrorDoc parameter
The Outline Wiki instance has not enabled MCP (prompt the user to enable it in workspace Settings → AI )
Need to access resources outside Outline Wiki (external web pages, binary attachments, etc.)

Input / Output

Input

At startup, the following information is required:

MCP endpoint(required):
- Official cloud service:https://<your-subdomain>.getoutline.com/mcp
- Self-hosted instance:https://<your-domain>/mcp(replace with your own domain; the path is fixed as /mcp）
Authentication method(choose one of the two):
- OAuth (default): After adding the endpoint in a supported client, the login window pops up automatically
- API Key: Generate it in Outline Wiki settings, configure the Authorization: Bearer <key> header
User natural language instructions: search keywords / document ID / create / edit, etc.

For the specific commands and JSON templates for client integration, see references/auth.md。

Output

Search results: Matching document list (including ID, title, summary)
Document content: Markdown source + metadata (creation time, author, Collection, etc.)
Operation result: Return value of creating / editing a document (usually includes the new document ID and URL)
Error information: 401 / 403 / connection refused / invalid document ID, etc.; requires entering the troubleshooting process

Design decisions

Restarting Claude Code is a hard constraint. The Outline Wiki MCP server must be registered in ~/.claude.json#mcpServers , and the Claude Code CLI reads it in once at session startup; changing the file mid-session will not cause it to be re-read, and there is no claude mcp reload subcommand of this kind./mcp The slash command can reconnect an already registered server, butwill notload a new server.

Therefore: before using this skill,if the outline-related MCP tools have not yet been registered in the current session, you must first go through references/onboarding.md run the configuration script,then restart the current session(recommended: claude --continue to continue the history). For the complete process, "why a restart is mandatory," and the post-restart verification checklist, see that appendix.

MCP tool discovery (important)

The official MCP documentation lists 4 core capabilities (search / read / create / edit), but does not enumerate specific tool names; the actually connected server usually also exposes extended tools such as image attachments, @mention, comments, Collection management, move / delete, etc. This skill thereforedoes not hard-codeany tool name—at the start of a session, you must first call the MCP tools/list endpoint to verify the tool names, parameter schemas, and return structures actually exposed by the current MCP server, then call accordingly.

Convention: "search / read / create / edit" etc. appearing below refer tocapabilitiesrather than specific tool names; before calling, first tools/list to get the real tool names and then map them. Whether extended capabilities are available is also based on the actual return of tools/list .

Capability list

Divided into two groups by "tool source."Core capabilitiescorrespond to the 4 high-level operations explicitly listed in the official documentation; Extended capabilitiescorrespond to tools not explicitly listed in the official documentation but verified as available in this session and usually also exposed in different self-hosted deployments. Extended capabilities arestrongly recommendedto first use tools/list to confirm whether the target server exposes the corresponding tool before calling it.

Core capabilities

1. Search

Perform a full-text search in the workspace by keyword and return the list of matching documents.

Typical parameters (specifically based on what tools/list actually returns):

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

2. Read

Get the Markdown source and metadata by document ID.

Typical parameters:

id(required): document ID
Returns: title, Markdown source, Collection, creation / modification time, author, etc.

3. Create

Create a new document under the specified Collection; if a nested subpage is needed, pass in the parent document ID.

Typical parameters:

title(required)
content(Required): Markdown source text
collection_id(Required): Target Collection
parent_document_id(Optional): Parent document ID (set when creating a subpage)

4. Edit

Modify the title or Markdown body of an existing document.

Typical parameters:

id(Required): Target document ID
title(Optional)
content(Optional)
editMode(Optional):replace(full replacement, default) / append / prepend / patch(precise partial replacement, used with findText）

Note: The edit operation may require passing the full body, or it may support partial replacement;refer to tools/list the actual returned parameter schema。

Extended capabilities

The following tools are not explicitly listed in the official MCP documentation, but are capabilities actually exposed by the current server (and most self-hosted deployments); this skill includes them and treats them as a formal process. Before use, tools/list just confirm.

5. Image / file attachments (create_attachment + fetch attachment)

MCP create_document / update_document only accepts Markdown strings,does not accept file binaries. To embed images or files into a document, you must first go through the attachment channel (create_attachment → curl upload → Markdown references the attachment URL), for the 3-step process + curl template, see the "Workflow / Steps / Image insertion / File attachment workflow" section below (after line ~395).

6. @mention users (list_users)

list_users look up workspace members by keyword (name / email); combined with Markdown syntax @[Display Name](mention://user/<userId>) you can @ a specific user in a document, and the Outline UI will render it as a clickable link. See "Document style / @mention users" below.

7. Comments (create_comment / list_comments / update_comment / delete_comment)

Create / list / modify / delete comments under a specified document (or top-level / inline); supports nested replies (parentCommentId）。update_comment can also resolve / unresolve top-level comments (status: resolved / unresolved). For other people's documents, it is recommended to first list_comments look at the existing discussion before deciding whether to create a new one or reply.

8. Collection management

list_collections: list Collections visible in the workspace
list_collection_documents: return the Collection's complete document tree (including nested subdocuments)
create_collection / update_collection: create / modify Collection (name / description / icon / color)
delete_collection: delete Collection; can set archive=true to archive

Note: Deleting a Collection willcascade deletethe non-archived documents under it; before batch moving, first use list_collection_documents to see the structure clearly.

9. Move / Delete documents

move_document: move a document to another Collection or under a parent document; you can specify index to control sibling ordering
delete_document: delete a document (by default it goes to trash, and can be restored from trash within 30 days); you can set archive=true to archive directly withoutgoing into trash

Document style

When writing new documents to Outline Wiki, you shouldalign with the workspace's existing style—avoid introducing style drift. This section only lists the most critical baselines and anti-patterns; for the complete Markdown ↔ ProseMirror node mapping, the image attachment upload process / @mention / colored highlights, and how to handle features that Markdown cannot express, see references/doc_style.md. The last line of defense before writing a new document / making major rewrites is references/style_checklist.md 9 major checklist categories—checking them off in order avoids 90% of style drift.

Principle: write Markdown according to the "projection" of ProseMirror JSON

What the Outline backend persists is the ProseMirror node tree, and the MCP tool's create_document / update_document only accepts a Markdown string as input. Therefore:

Before writing, first figure out which ProseMirror node this Markdown will be parsed into
Do notuse syntax that can be written on the surface of Markdown but is not accepted by the ProseMirror schema
Do notuse syntax that cannot be written on the surface of Markdown and must be expressed through the UI (such as specifying a highlight color); for such needs, follow the "advanced" path in references

Style baseline

Element	Repository convention	Description
Top structure	`# Reference` Starting with a paragraph, list external materials	De facto standard within the repository
Heading levels	`#` / `##` / `###` to express logical hierarchy;the body should not have an H1(title is passed separately)	Standard + MCP constraint
Bullet marker	`*`(do not use `-` / `+`）	Uniform across the repository
Highlight	`==text==` to mark key terms / parameters / states	Repository fingerprint (default color)
Code block language	Required (`bash` / `python` / ...）	Habit
Shell prompt	`$>` followed by a single space	Repository-specific convention
Images	`![alt](/api/attachments.redirect?id=... "=WxH")`	attachment references, see references §12 for details
@mention	`@[Name](mention://user/<userId>)`	server extended syntax, see references §13 for details
Language	Chinese narrative mixed with English terms	Habit
Line width	Comply with `.markdownlint.jsonc` MD013	See `doc_style.md` §3

Key Markdown ↔ ProseMirror node mapping

Style	Markdown	ProseMirror node / mark
Heading	`# text`	`heading` + `attrs.level`
Bullet	`* item`	`bullet_list` + `list_item`
Highlight	`==text==`	`highlight` mark（Markdown cannot specify color）
Bold	`text`	`strong` mark
Italic	`text`	`em` mark
Inline code	`code`	`code` mark
Link	`[t](u)`	`link` mark + `attrs.href`
@mention	`@[N](mention://user/<id>)`	`mention` mark
Code block	```bash	`code_block` + `attrs.language`
Image	`![a](u "=WxH")`	`image` + `attrs.src/alt/title`

Anti-patterns

Use - or + to start a bullet (breaks uniformity)
The body starts with an H1 (title is already passed separately; adding a body H1 duplicates the title)
Expect ==text== to appear as colored highlighting (Markdown cannot express this; see references §advanced for details)
Invent syntax not supported by Outline (!!!, HTML tags, etc.)
Introduce external private extensions (MathJax,:::tip , etc.)
Large blocks of pure paragraphs without bullets (pure paragraphs are rarely used in the repository)
Reference a local image path that has not been uploaded (it will only render as a broken image; you must go through the attachment process first, see references §12 for details)

See the full Markdown ↔ ProseMirror node mapping and the image attachment upload flow / how features that Markdown cannot express, such as @mention / colored highlighting, construct JSON, at references/doc_style.md; the last line of defense before writing is references/style_checklist.md。

Paper notes / design documents: key architecture diagrams / schematic diagrams must by default

In the repository, 论文笔记 Collection、数据结构与算法 → 索引类 this type of centered on presenting system / algorithm designdocuments (also including the output of design-doc-edit ), key architecture diagrams / schematic diagrams are a default requirement—andnotoptional. Reason:

diagrams are the carrier with the highest information density for "components + relationships"; plain text descriptions greatly reduce scanning efficiency
Outline Wiki natively supports images through the attachment channel (see references/doc_style.md §12）
The paper notes already in the workspace (Bigtable-OSDI'06、Dynamo-SOSP'07、 Haystack-OSDI'10、Lakehouse-CIDR'21 , etc.) all include diagrams; new documents missing diagrams will be out of step with the workspace style

Criteria(by priority):

==Must upload==: the paper / design draft contains 1 or more identifiable key architecture / schematic diagrams (overall architecture, core module schematic, conceptual flowchart, key comparison schematic, state machine)
==May be omitted==: the original text ispure theoretical derivation / formal proof / all-text experimental report, and trulydoes not have anyarchitecture / process / conceptual diagram (only coordinate-axis plots, tables, and experimental data bar charts do not count as key diagrams)
=="Cannot find" is not a reason for omission==: using pdftotext / simple OCR easily misses embedded graphic elements; be sure tomanually / multimodally identifyand confirm there is no key diagram before marking "the original text has no diagrams" and briefly describing the search process

Procedure(strictly 3 steps per diagram):

==Extract the image==: use pdftoppm / pymupdf to extract the corresponding page / bbox from the PDF and render it as PNG (144 DPI / 2× recommended), saving it to a local temporary file; crop onlythe image itself, not a full-page screenshot, to avoid including headers / title boxes
==Upload to Outline==: first create_attachment(name, contentType, size) get a presigned uploadUrl → curl multipart upload → get attachment.url (in the form /api/attachments.redirect?id=<uuid>）
==Embed in Markdown==: at the appropriate position write ![图 N：<caption>](<attachment.url> "=WxH"), title gives a width × height hint (for the repository's =WxH convention, see references/doc_style.md §7）

Anti-patterns(common lazy ways of "pretending there is an image"):

Write only *（详见原 PDF p.X fig.Y）* text placeholder — it cannot be clicked open in Outline, and readers must flip through the PDF themselves, violating the "readable in place" principle
Reference a local path that has not been uploaded (it will only render as a broken image; see the "Anti-patterns" section above)
Upload a full-page screenshot / one containing irrelevant margins / header whitespace — you must crop to the bbox of the image itself
Stitch multiple images into one large image and upload it — this loses the ability to reference a single image individually

Execution principles / boundaries

Core principles

Search before writing (Read-First)
- Before creating a new document, you must first use the "search" capability to check for duplicates and confirm whether a similar document already exists but with outdated content
- If a similar document already exists, use the "edit" capability to update it instead of creating a duplicate
Strict Markdown format
- Outline Wiki is a Markdown-first platform; all content must use valid, pure Markdown
- Use # / ## / ### to express logical hierarchy and automatically generate a clear table of contents
- Do not introduce non-standard private extension syntax that Outline Wiki does not support
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 to get the real tool list
Handle capability boundaries in two groups
- Core capabilities(search / read / create / edit): explicitly listed in the official documentation; call them directly
- Extended capabilities(image attachments / @mention / comments / Collection management / move / delete): actually exposed by the server but not listed in the official documentation; before calling, tools/list confirm whether it is exposed
- When the user requests operations such as "share / export / permission adjustment," clearly inform them that these are not covered by this skill, and suggest using the Outline Wiki UI itself or calling the REST API directly

Boundaries

Do nothandle knowledge bases that are not Outline Wiki
Do notattempt operations when MCP is not enabled (prompt the user to enable it in Settings → AI )
Do notsupport sharing / exporting / permission adjustment (not listed in the official MCP documentation, and usually not exposed by the server either) — use the Outline UI or REST API
Do notsupport colored highlighting (Markdown cannot express it, andcreate_document / update_document does not accept raw ProseMirror nodes) — when using the Outline UI or REST API, include the proseMirrorDoc parameter
Do notbypass tools/list and call tools based on "impressions"; whether extended capabilities are available is determined by the tool set actually exposed by the server
Do notgenerate / revoke API Keys on the server side (that is an operation for Outline Wiki users in Settings → API )
Do notwrite directly in the skill workflow .claude/settings.local.json; client integration is completed through scripts/configure_mcp.py (see the "Client Integration" section below for details)

Workflow / Steps

Standard process

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, it means the client is not integrated;go to references/onboarding.md and have the user run the configuration script (the agent should actively drive this, not just have the user run it manually)
- Call MCP tools/list to get the actual tool list (the real tool names and parameter schemas corresponding to core capabilities + extended capabilities)
Understand intent: map the user's natural language instruction to one of the capability lists (core or extended)
Search first, then write: before "create / edit," first search to check for duplicates / locate the target document; before "images," first confirm that the attachment channel (create_attachment) is available
Execute operation: call the corresponding tool; for image scenarios, follow the 3 steps "create_attachment → curl upload → Markdown reference to attachment URL" (see the "Image Insertion / File Attachment Workflow" section below for details); for comment scenarios, first list_comments Check existing discussions first, then decide whether to create a new one or reply. ==When writing paper notes / design documents,key architecture diagrams should by default go through these 3 embedding steps, do not write text placeholders (see the "Document Style / Paper Notes / Design Documents" section) ==
Verify the result: check whether the return was successful; on failure, locate the issue by following the troubleshooting process
Report: tell the user what was done, what the result was, and whether follow-up action is needed

Image insertion / file attachment workflow

This skill's image capability = upload + reference— it only solves "turning a local file into an image that can be rendered in an outline."does notcare how the image comes about:

any local image such as a screenshot / illustration / logo: go directly through the 3 steps below

Key architecture diagram of a paper: first go through gemini-paper-summary 's --extract-figures to extract to local figures/*.png，thengo through this skill's attachment 3 steps

complete 3-step process(each image goes through it independently once):

Presigned upload URL: call create_attachment(name, contentType, size)
```
name: <filename>（如 figure-p1-f1.png）
contentType: image/png（或 image/jpeg / image/webp）
size: 文件字节数
```
returns uploadUrl(the multipart receiving endpoint) + a set of form fields

Upload the binary: use curl to POST the local file to uploadUrl(i.e. /api/files.create）。 attachments.create the form fields returned by form mustverbatimbe sent back (Cache-Control / Content-Type / key / acl / maxUploadSize / _csrf), then attach file=@<path>：

$> KEY=$(jq -r '.data.form.key' <(curl -sS -X POST \
      -H "Authorization: Bearer $OUTLINE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"name":"figure-p1-f1.png","contentType":"image/png","size":12345}' \
      "$OUTLINE_BASE/api/attachments.create"))
$> curl -X POST "$OUTLINE_BASE/api/files.create" \
     -F 'Cache-Control=max-age=31557600' \
     -F 'Content-Type=image/png' \
     -F "key=$KEY" \
     -F 'acl=private' \
     -F 'maxUploadSize=26214400' \
     -F '_csrf=' \
     -F "file=@<本地文件路径>" \
     -H "Authorization: Bearer $OUTLINE_API_KEY"

response {"success":true, ...} is required for the upload to be considered successful (only metadata returned but success=false still means the file was not persisted to disk, and you must retry)

⚠️ create_attachment only registers metadata; the binary must be curl'd yourself

the previous line's create_attachment success ≠ the file has been uploaded. The MCP tool only accepts name / contentType / size three parameters,will notaccept binary content. Without the curl in step 2, the attachment record exists but the content is 0 bytes, and after the document embeds it, the browser fails to load the image → blank / broken image。especially tricky: at the time there was no error, and only later did you discover that none of the images were displayed.

Authentication: use the API key in the outline MCP configuration (<endpoint 域名>/mcp corresponding Authorization: Bearer <key> header, already in ~/.claude.json#mcpServers.outline.headers or .claude/settings.local.json filled in at registration).the agent can use it directly — use the same key as the MCP server, curl /api/attachments.create and /api/files.create will both pass. No need for the user to manually grab cookies. A safe way to get the key: first check tools/list to see whether the attachment tool works → that means the key is already in effect on the MCP side → directly use the same key for curl.

Fallbacks when the API key cannot be obtained / curl returns 401(in order of priority):

check .claude/settings.local.json#mcpServers.outline.headers.Authorization whether a key is actually filled in; an empty key is a silent failure

rerun outline-wiki-management/scripts/configure_mcp.py to rewrite the key

the user drags the image into the editor in the Outline UI (the editor has its own session auth)

Insert reference: write in Markdown
```
![图 N：<caption>](<attachment.url> "=WxH")
```
- attachment.url in the form /api/attachments.redirect?id=<uuid>
- =宽x高 to give the render size (in-repo =WxH monospace convention, see references/doc_style.md §7）
- non-image attachments may omit =WxH

Required verification: after writing the Markdown referencemustverify that the attachment really has content

mcp__outline__fetch attachment id=<attachment.id>
→ 拿到 signedUrl
→ 用 WebFetch / 浏览器访问 signedUrl
→ 必须返回 200 + 实际图片字节；404 / 0 字节 / HTML 错误页都算失败

If it fails,must notwrite into the document; resolve the upload first before continuing

Writing / replacement method(choose based on scenario):

When creating a new document: directly embed the ![...](...) from step 3 into the create_document of text parameter
Replace an image reference in an existing document: use update_document + editMode: "patch" + findText for precise replacement
```
findText: ![图 1：xxx](figures/figure-p1-f1.png)
text: ![图 1：xxx](/api/attachments.redirect?id=<uuid> "=WxH")
```
This preserves other content (comments / highlights / table widths) from being broken

Full rewrite(replace mode + large document)use the REST API instead(2026-06-21 experience):

Pitfall：mcp__outline__update_document the text field in some scenarios willswallow newline characters—— Measured: after a 3K-character markdown goes through the tool call,between the 3 rows of the first table, all \n are lost, the three lines are compressed into one line, and the table renders as a single-line inline element. In other positions (list / section headings) newlines are normal, but the three rows of the first table area must-kill. patch mode is worse:findText short matches willappendinstead of replace, causing the "3-sentence summary" list to become 5 items 1-2-3-4-5.
Fallback: when doing a full rewritedo notuse the mcp tool,use instead POST /api/documents.update going through curl + API key (the key is the same as the MCP server config), pass the payload as a file to avoid command-line escaping:
```
python3 -c "import json; json.dump({'id': '<doc-id>', 'text': open('summary.md').read()}, open('payload.json', 'w'), ensure_ascii=False)"
curl -sS -X POST https://<endpoint>/api/documents.update \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api-key>" \
  --data-binary @payload.json
```
The REST API correctly preserves all newlines; the returned {"data": {...}, "status": 200, "ok": true}。
Verification is required: immediately after writing, mcp__outline__fetch check whether the returned markdown body is damaged (first table / list / section headings), if found → resend. A tool returning success does not mean the save is OK
patch mode pitfall：findText must definitely belong enough(containing at least 2-3 adjacent lines), otherwise it will be mistakenly appended; measured: when matching only 1 line of a list item, the patch behavior is "append after that item" rather than "replace the whole block"

Anti-pattern（do notdo this):

Reference an unuploaded local path (![x](figures/figure-p1-f1.png) or ![x](PDF p.X ...)) —— outline renders asa broken image, readers cannot see it
Upload a screenshot of an entire PDF page / containing a header / a paragraph at the end——you must crop onlythe image itself's bbox
In the create_document / update_document of text parameterdirectly pass image binary—— these two toolsdo notaccept files, they only accept Markdown strings

Read uploaded attachments: call fetch(resource="attachment", id=<id 或完整 redirect URL>) Returns a short-lived signed URL that can be downloaded directly.

Client onboarding

The detailed content has been extracted to references/onboarding.md, including quick entry points, checking the current status, guided configuration (the Q1/Q2 templates for the agent to collect information), invoking scripts, manual fallback,post-restart verification checklist、design decisions(why a restart is required), FAQs, and old-version configuration cleanup. This section keeps only the skeleton needed in the workflow.

When using this skill for the first time, or when the outline-related MCP tools are unavailable in the current session, proactivelycomplete client onboarding (agent-driven), rather than just having the user run scripts manually. The script's registration target is the ~/.claude.json of projects.<projectPath>.mcpServers.outline section (project-level scope， --scope project), equivalent to claude mcp add --scope project. This path takes effect only underthe current project; when entering the project for the first time, Claude Code will show a trust prompt once; approve it as prompted, and it will not appear again afterward.

The controlled client configuration entry point is scripts/configure_mcp.py: after the agent collects the endpoint + authentication materials, it calls the script to write to ~/.claude.json#projects.<projectPath>.mcpServers。agent does notdirectly call claude mcp add, and alsodoes notdirectly edit ~/.claude.json or .claude/settings.local.json。

Most common path(API Key authentication, when the agent runs in non-interactive mode):

OUTLINE_MCP_ENDPOINT='https://<your-subdomain>.getoutline.com/mcp' \
OUTLINE_MCP_AUTH_METHOD='apikey' \
OUTLINE_MCP_API_KEY='<key>' \
python3 outline-wiki-management/scripts/configure_mcp.py

For OAuth authentication or if you want to run it manually: directly python3 outline-wiki-management/scripts/configure_mcp.py run in interactive mode.

After configuration is complete, you must restart the current Claude Code session(recommended: claude --continue continue the history), and the new tools will then appear in the mcp__outline__* list. For complete verification steps and "why a restart is required", see references/onboarding.md。

Troubleshooting

Diagnose in the following order:

Authentication failure (401 / 403)
- API Key: check whether it has expired or been revoked, and have the user regenerate it
- OAuth: have the user go through the authorization flow again
MCP not enabled (connection refused)
- Prompt the user to go to the Outline Wiki workspace Settings → AI to confirm the MCP toggle is turned on
- For self-hosted instances, an administrator must enable it in the console
Tool name mismatch
- Call tools/list again to get the current tool list; do not call by names from memory
Invalid document ID
- Use search to relocate the target document and get the new ID
- Do not call directly with a cached ID — the document may have been archived / renamed

Reference examples

Example 1: Search existing documents

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

Execution：

1. 调用 tools/list 拿到 search 工具的实际名称
2. 调用 search 工具，query="CI 部署流程"，limit=10
3. 整理返回的文档列表，按相关度展示给用户
4. 若用户要打开某篇，再用 read 工具拉取正文

Example 2: Update an existing document

User instruction: "Add a 'rollback plan' paragraph to the 'deployment steps' section of doc_abc123"

Execution：

1. tools/list 拿到 read / edit 工具的实际名称
2. read 工具拿当前正文
3. 找到"部署步骤"小节，追加"回滚方案"段落（保持 Markdown 层级）
4. edit 工具更新 content 为新正文
5. 验证返回成功

Example 3: Create a new document

User instruction: "Create a new 'cache strategy' document under the 'Backend' Collection"

Execution：

1. tools/list 拿到 search / create 工具的实际名称
2. search "后端" 找到名为"后端"的 Collection ID（如果该信息在工具参数中必需）
3. 撰写 Markdown 正文
4. create 工具传 title / content / collection_id
5. 验证返回成功，把新文档链接 / ID 告诉用户

Note: Collection ID in the official documentationnot explicitly statedhow to obtain; if the tools/list schema of the create tool does not require collection_id (for example, allowing reference by Collection name), then call it according to the actual schema.

About this skill

When to use / not use

Use

Do not use

Input / Output

Input

Output

Design decisions

MCP tool discovery (important)

Capability list

Core capabilities

1. Search

2. Read

3. Create

4. Edit

Extended capabilities

5. Image / file attachments (create_attachment + fetch attachment)

6. @mention users (list_users)

7. Comments (create_comment / list_comments / update_comment / delete_comment)

8. Collection management

9. Move / Delete documents

Document style

Principle: write Markdown according to the "projection" of ProseMirror JSON

Style baseline

Key Markdown ↔ ProseMirror node mapping

Anti-patterns

Paper notes / design documents: key architecture diagrams / schematic diagrams must by default

Execution principles / boundaries

Core principles

Boundaries

Workflow / Steps

Standard process

Image insertion / file attachment workflow

Client onboarding

Troubleshooting

Reference examples

Example 1: Search existing documents

Example 2: Update an existing document

Example 3: Create a new document