outline-wiki-upload

Outline Wiki Upload

Through the Outline Wiki MCP'swriteoperation capabilities (create + edit + extended capabilities + style baseline), write Markdown documents that match the repository fingerprint into the workspace. This skill is part of the outline-wiki-* family,the heaviestone—containing 2 core write capabilities + 5 extended write capabilities + style mapping (ProseMirror node mapping table) + style checklist (9 major categories).

Read / search is handled by outline-wiki-search SKILL.md; MCP configuration is handled by outline-wiki-setup SKILL.md.

When to use / not use

Use

The user says "create / write / edit / modify / update / push / upload / publish / sync / copy a document to outline"
The user says "outline document contains images / upload images to outline / insert images into an outline document"
The user says "@someone / comment / move / delete / archive / organize outline documents"
The user says "manage outline collection / create collection / change collection description"
Writing a new document / substantially rewriting an existing document (with images / with mermaid / with attachment references)
After running gemini-paper-summary / similar upstream tools, you need to push the generated local markdown + figures to outline—this skill is the necessary path (attachment 3 steps + Markdown replacement)

Do not use

Search / read outline documents—go through outline-wiki-search SKILL.md
Configure outline MCP(first-time integration / not visible after restart / 401)—go through outline-wiki-setup SKILL.md
Search before writing to check for duplicates / locate—also within the scope of outline-wiki-search (search + read is read-only, and together with this skill's write forms the complete "search first, then write" workflow)
The user uses another wiki / knowledge base product (Notion / Confluence / Obsidian / GitHub Wiki)
Sharing, exporting, permission adjustments (not listed in the official MCP documentation, and usually not exposed by the server)— go through the Outline Wiki UI itself or call the REST API directly
Needcolored highlightingand other rich-text features that Markdown cannot express (create_document / update_document does not accept raw ProseMirror nodes)— go through the UI or call the REST API directly and include the proseMirrorDoc parameter

Input / Output

Input

At startup, the followingprerequisitesmust be in place—these are handled by outline-wiki-setup :

MCP is registered: the current session can call the mcp__outline__* series of tools (if not registered,first go through outline-wiki-setup SKILL.md, and come back after running it and restarting)
Collection ID(required when writing documents; if the schema allows referencing by name, call according to the schema)
User's natural language instructions: create / edit instructions, document content, target Collection

Output

Create / edit result: new document ID + URL; or the updated version returned after patch
Image attachment ID: returned after completing the 3 attachment steps /api/attachments.redirect?id=<uuid>
Error messages: MCP call failure / attachment 0 bytes / Markdown line breaks swallowed, etc.

Design decision (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 Markdown surface but is not accepted by the ProseMirror schema

Do notuse syntax that cannot be written on the Markdown surface and must be expressed through the UI (such as specifying highlight color); such requirements go through the references/doc_style.md "advanced" path

For the detailed Markdown ↔ ProseMirror node mapping table, see references/doc_style.md. This SKILL.md only lists the style quick-reference table + key anti-patterns,the complete §1-§13 mapping + image attachment upload flow + @mention syntax + color highlights that cannot be writtenare all in references.

OKF upload format (agent-readable baseline)

Why: documents pushed to Outline must be able to be read back and understood—— outline-wiki-search by an agent. Reading back the markdown body, parsing by external OKF consumers, and retrieval chunking all depend on a machine-readable metadata header + predictable body structure. OKF = Open Knowledge Format ("markdown + frontmatter, readable by both humans / agents"), and the authoritative implementation is llm-wiki-compiler; this repository's llm-wiki-management SKILL.md implements the v0.1 subset, and this skill followsthe same definition, adapting the carrier only for Outline.

Carrier selection (measured): the OKF standard uses ---...--- frontmatter, but Outline's MCP parses Markdown into ProseMirror and then serializes it,---...--- cannot survive the round trip—--- gets eaten, YAML leaks into visible body text (confirmed by dual-probe measurement on the same server on 2026-07-01).```yaml A fenced block, however, is stored as code_block and preserved verbatim. So the Outline-side carrier = the first block of the body ```yaml fenced block(standard fields + adapted carrier),do notuse ---...---。

Two Outline adaptation points：

title externalized: OKF's title is carried by Outline's native title field, and is not written into the body (writing a bare H1 duplicates the title; writing a bare ---...--- will leak again).
**Metadata carrier = the first block of the body yaml 围栏**：其余字段放正文**第一个**块的 yaml code block, which ProseMirror stores as code_block and preserves as-is, appearing first when read back.

Minimal skeleton for the first block of the body(title goes through the Outline field, not into the block):

```yaml
type: paper-note
description: 一句话摘要；agent 索引摘要从它来
tags: [llm, architecture]
created: 2026-07-01
updated: 2026-07-01
x-outline:
  collection: 论文笔记
  source-skill: gemini-paper-summary
```

## 正文第一节

The only hard threshold is type: an OKF consumer "skips the document only if frontmatter parsing fails or type is missing, and tolerates everything else"—whether an agent can read it backdepends only on type being non-empty。
Recommended items：description / tags（≥ 1） / created / updated （YYYY-MM-DD); fill in whatever you can, to improve retrieval / summarization / timeliness.
Do not put in this block：okf_version(the standard only puts it at the bundle root index.md declaration, single document without bundle),title(carried by the Outline field).
x-outline Extension block(optional): Outline-specific provenance (collection / docId / source skill), using OKF x-<producer> private keys; don't stuff things here that standard fields can express.
type enum: knowledge page type entity / concept / source / comparison / synthesis(same as wiki, consistent across skills) + Outline-specific design-doc / paper-note / runbook / reference / guide; when it belongs to neither, you may define a custom kebab-case and explain it in description .
Body structure discipline: the yaml block is the first block of the body (nothing before it); headings start from ## and don't skip levels or duplicate names at the same level (the agent uses headings as chunking anchors); one topic per document; links use Outline links / absolute URLs, don't write bare local relative paths.

For the complete field table + measured details on carrier selection + the relationship with the standard / wiki subset + how to patch the yaml block when rewriting, see references/doc_style.md → OKF agent-readable baseline。

MCP tool discovery (important)

The official MCP documentation lists 4 core capabilities (search / read / create / edit) and does not enumerate specific tool names; the server actually connected usually also exposes extended tools such as image attachments, @mention, comments, Collection management, move / delete. This skill thereforedoes not hardcodeany tool names— 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, and then call accordingly.

Convention: "create / edit / image attachment / comment / Collection management" etc. appearing below refer to capabilitiesrather 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 subject to the actual return of tools/list .

Capability list

Divided into two groups by "tool source".Core capabilitiescorrespond to the create / edit two of the 4 high-level operations explicitly listed in the official documentation (search / read are handled by outline-wiki-search SKILL.md );Extended capabilitiescorrespond to tools not explicitly listed in the official documentation but measured as available in this session and usually also exposed in different self-hosted deployments. Extended capabilitiesstrongly recommendedfirst use tools/list to confirm whether the target server exposes the corresponding tool, then call it.

Core capabilities

1. 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)

2. 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, together with findText）

Note: the edit operation may require passing the complete body, or it may support partial replacement;subject to tools/list the parameter schema actually returned。

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 part of the formal workflow. Before use, tools/list just confirm.

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

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

4. @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 the document, and the Outline UI will render it as a clickable link.

5. 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 check the existing discussion before deciding whether to create a new one or reply.

6. 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 a Collection (name / description / icon / color)
delete_collection: delete a Collection; you can set archive=true to archive it

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

7. Move / Delete documents

move_document: move a document under another Collection or 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 to trash

Document style (repository fingerprint quick reference)

For the complete Markdown ↔ ProseMirror mapping, the image attachment upload workflow, colored highlights, and how to handle other features that Markdown cannot express, see references/doc_style.md. The last line of defense before writing a new document / making major rewrites is the 9 major categories of checklist in references/style_checklist.md —checking them off in order can avoid 90% of style drift.

Style baseline (quick reference table)

Element	Repository convention	Description
OKF metadata block	First block of the body ```yaml (hard requirement `type`; recommended `description`/`tags`/`created`/`updated`/`x-outline`）	agent-readable baseline, see the doc_style OKF section
OKF title	Use Outline's native title field,do notput it in the yaml block	avoid duplication
OKF `okf_version`	Single documentdo not write(the standard is only declared at the bundle root `index.md` )	single document has no bundle
Top structure	First block of the body = OKF yaml; afterward, if a Reference section is used, follow the `## Reference`	standard + OKF constraints
Heading levels	`#` / `##` / `###` Express logical hierarchy;body text must not use H1(title is passed separately)	Standard + MCP constraint
Bullet marker	`*`(do not use `-` / `+`）	Repository unified
Highlight	`==text==` Mark key terms / parameters / states	Repository fingerprint (default color)
Code block language	Required (`bash` / `python` / ...）	Convention
Shell prompt	`$>` followed by one space	Repository-specific convention
Image	`![alt](/api/attachments.redirect?id=... "=WxH")`	attachment reference, see doc_style.md §7 / §12 for details
@mention	`@[Name](mention://user/<userId>)`	server extension syntax, see doc_style.md §13 for details
Mermaid identifier	```mermaidjs（not `mermaid`）	Repository fingerprint
Language	Chinese narration + English terminology mixed	Convention
Line width	Follow `.markdownlint.jsonc` MD013	Threshold see doc_style.md §3

Anti-patterns (read before writing)

The first block of the body is not an OKF ```yaml metadata block, or the block is missing a non-empty type(the only hard gate for agent read-back)
Writing OKF title repeatedly into the yaml block (title is already carried by the Outline field)
Writing okf_versionin the yaml block (the standard is only declared in the bundle root index.md , a single document should not have it)
Writing ---...--- frontmatter bare in the body—the Outline round trip will eat ---, and the YAML leaks into visible body text (confirmed by testing)
Using - or + to start bullets (breaks uniformity)
Body starts with H1 (title is already passed separately; adding a body H1 duplicates the title)
Expecting ==text== to appear with colored highlighting (cannot be written in Markdown, see doc_style.md §Advanced)
Inventing syntax not supported by Outline (!!!, HTML tags, etc.)
Introducing external private extensions (MathJax,:::tip , etc.)
Large sections of pure paragraphs without bullets (pure paragraphs are rarely used in the repository)
Referencing an unuploaded local image path (it will only render as a broken image; the attachment flow must be followed first)

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

In the repository, 论文笔记 Collection、数据结构与算法 → 索引类 this kind ofdocument centered on presenting system / algorithm design(also including the output of design-doc-edit ),key architecture diagrams / schematic diagrams are a default requirement—not an optional item. For the criteria and the complete workflow, see references/style_checklist.md §9。

Execution principles / boundaries

Core principles

Read-First
- Before creating a new document, you must first use outline-wiki-search to check for duplicates and confirm whether a similar but outdated document already exists
- If a similar document already exists, use edit to update it instead of creating a duplicate
Strict Markdown format
- Outline Wiki is a Markdown-first platform; all content must use valid, clean Markdown
- Use # / ## / ### Reflects logical hierarchy, automatically generates a clear table of contents
- Does not introduce non-standard private extension syntax not supported by Outline Wiki
Tool name verification (Tools-First)
- Do not assume the spelling of tool names or whether they have a prefix (e.g. outline_）
- Before any operation, first tools/list get the real tool list
Capability boundaries are handled in two groups
- Core capabilities(create / edit): explicitly listed in the official documentation, call 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
Confirm destructive operations first
- Deleting / archiving others' documents, moving documents, changing Collections, etc.Destructive operationsmust first be explicitly confirmed within the session
- For others' documents, it is recommended to use create_comment to propose rather than overwrite directly

Boundaries

Nothandle knowledge bases that are not Outline Wiki
Notattempt operations when MCP is not enabled (first go through outline-wiki-setup）
Notsupport sharing / export / permission adjustment (not listed in the official MCP documentation, and usually not exposed by the server either) — use the Outline UI or REST API
Notsupport colored highlighting (Markdown cannot express it,create_document / update_document does not accept raw ProseMirror nodes) — when using the Outline UI or REST API, include the proseMirrorDoc parameter
Notbypass tools/list and call tools based on "impression"
Notgenerate / revoke API Keys on the server side (that is an operation for Outline Wiki users in Settings → API )

Workflow / Steps

Standard process

Verify configuration and tools: at the start of the session——
- confirm that outline-related MCP tools are registered in the current session; if not registered,first go through outline-wiki-setup SKILL.md, and after running and restarting, come back
- 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 instructions to one of the capability lists (core or extended)
Search before writing(in collaboration with outline-wiki-search ): before "create / edit" is involved, first search to check for duplicates / locate the target document; before "images" are involved, first confirm that the attachment channel (create_attachment) is available
Execute operations：
- Call the corresponding tool
- Organize the body: when writing a new document / making major rewrites, the bodyfirst blockwrites OKF ```yaml metadata block (hard threshold type; recommended description / tags / created / updated + optional x-outline; title uses the Outline field,does notWrite okf_version), the title starts from ## and does not skip levels (see "OKF Upload Format" above)
- For image scenarios, follow the 3 steps "create_attachment → curl upload → Markdown reference to attachment URL" (see "Image Insertion / File Attachment Workflow" below)
- For comment scenarios, first list_comments look at the existing discussion before deciding whether to create a new one or reply
- When writing paper notes / design documents, key architecture diagrams should by default be embedded using these 3 steps, and do not write text placeholders (see the "Document Style / Paper Notes" section above)
- Destructive operations(delete / move_document / delete_collection) confirm first
Verify the result: check whether the return indicates success; on failure, locate the issue according to 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 outline."It does notcare how the image comes about:

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

Key paper architecture diagrams: the image source is not this skill's responsibility—use gemini-paper-summary from SKILL.md to extract to local --extract-figures Getting it locally figures/*.png then go through this skill's 3 attachment steps

Complete 3-step process(run it once for each image independently):

Presigned upload URL: call create_attachment(name, contentType, size)
```
name: （如 figure-p1-f1.png）
contentType: image/png（或 image/jpeg / image/webp）
size: 文件字节数
```
returns uploadUrl(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 returned by form field 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, ...} before the upload is considered successful (if only metadata is returned but success=false it still means the file has not been written to disk, and you must retry)
⚠️ create_attachment only registers metadata; the binary must be curled yourself

The previous line create_attachment succeeding ≠ the file has been uploaded. MCP tools only accept 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: it does not report an error at the time, and you only discover afterward that none of the images are displayed.

Authentication: use the API key from the outline MCP configuration (<endpoint 域名>/mcp corresponding Authorization: Bearer <key> header, already filled in when registering ~/.claude.json#mcpServers.outline.headers or .claude/settings.local.json ).the agent can use it directly— use the same key as the MCP server, and curl /api/attachments.create and /api/files.create both work. The user does not need to manually grab cookies.

The safe way to obtain the key: first check whether the tools/list attachment tool works → it means the key is already in effect on the MCP side → directly use the same key with curl.

Fallback when the API key cannot be obtained / curl returns 401(by priority):
1. Check whether .claude/settings.local.json#mcpServers.outline.headers.Authorization actually has the key filled in; an empty key is a silent failure
2. Rerun outline-wiki-setup/scripts/configure_mcp.py to rewrite the key
3. The user drags and drops an image into the editor in the Outline UI (the editor has built-in session auth)
Insert a 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 the repo, =WxH and other monospace conventions, see doc_style.md §7)
- Non-image attachments may omit =WxH

Required verification: after writing the Markdown reference,mustverify that the attachment actually has content

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

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

Writing / replacement method(choose according to the scenario):

When creating a new document: directly embed the ![...](...) from step 3 into create_document 's text parameter
Replacing 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 damaged

Rewrite the whole document(replace mode + large document)Switch to the REST API(2026-06-21 experience):

Pitfall:：mcp__outline__update_document 's text field will, in some scenarios,swallow line breaks— it was measured that after a 3K-character markdown goes through a tool call,between the 3 rows of the first table, the \n are all lost, the three rows are compressed into one row, and the table renders as a single-line inline element. Line breaks elsewhere (list / section headings) are normal, but the three rows of the first table arefatal. 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 rewriting the whole document,do notuse the mcp tool,switch to POST /api/documents.update using curl + API key (the key is the same as the MCP server configuration), pass the payload via 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 line breaks; it returns {"data": {...}, "status": 200, "ok": true}。
Verification is required: right after writing, mcp__outline__fetch and 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 to disk is OK
Pitfall of patch mode：findText must belong enough(at least 2-3 adjacent lines), otherwise it will be mis-appended; in practice, when only 1 line of a list item is matched, the patch behavior is "append after that item" rather than "replace the whole paragraph"

Anti-patterns（Don'tdo this):

Referencing a local path that hasn't been uploaded (![x](figures/figure-p1-f1.png) or ![x](PDF p.X ...))—— outline renders it asbroken image, readers can't see it
Uploading a full-page PDF screenshot / one that includes the header / the paragraph at the end of a section——you must crop onlythe image itself's bbox
In create_document / update_document 's text parameterPassing image binary directly—— These two toolsdo notaccept files, they only accept Markdown strings

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

Client onboarding (first use)

This section is just a one-sentence index——the full flow for first-time onboarding / restart verification / troubleshooting is handled by outline-wiki-setup SKILL.md. This skill assumes MCP is already registered and available; if it isn't, go through the setup skill first, finish the restart, then come back.

Troubleshooting

Diagnose in the following order:

Authentication failure (401 / 403)
- This falls under outline-wiki-setup 's scope (key expired / OAuth invalid), restart first or re-run the configuration script
MCP not enabled (connection refused)
- Go through outline-wiki-setup to troubleshoot the configuration
Tool name mismatch
- Call tools/list again to get the current tool list; don't call by a name you remember
Invalid document ID
- Use outline-wiki-search to re-locate the target document and get the new ID
- Don't call directly with a cached ID——the document may have been archived / renamed
Image attachment is 0 bytes / 404
- Re-run the 3 attachment steps (create_attachment → curl upload → Markdown reference)
- Verify that fetch returns a signedUrl that can download bytes with 200
First-row table \n is lost
- Switch to the REST API POST /api/documents.update(same key as the MCP server configuration)

Reference examples

Example 1: Creating a new document

User instruction: "Create a new 'Cache Strategy' document under the 'Backend' Collection"

Execution：

1. 用 outline-wiki-search 查 '后端' Collection ID（若 create schema 要求）
2. 撰写 Markdown 正文：正文首块写 OKF yaml 元数据块
   （type: reference / tags / description / created / updated），
   再按 doc_style.md 风格基线 + style_checklist.md（§0 OKF + §1-§9）组织正文
3. 调用 create_document 工具传 title / content / collection_id
   （title 走 Outline 字段，不写进 yaml 块）
4. 验证返回成功，把新文档链接 / ID 告诉用户

Note: how to obtain the Collection ID isnot specifiedin the official documentation; if tools/list 's create tool schema does not require collection_id (for example, it allows referencing by Collection name), then call it according to the actual schema.

Example 2: Updating an existing document

User instruction: "Add a 'Rollback Plan' paragraph to the 'Deployment Steps' subsection of doc_abc123"

Execution：

1. 用 outline-wiki-search 读 doc_abc123 拿当前正文
2. 找到"部署步骤"小节，追加"回滚方案"段落（保持 Markdown 层级）
3. edit 工具更新 content 为新正文（editMode: "replace"）
4. 验证返回成功

Example 3: Pushing images from gemini-paper-summary to outline

User instruction: "Push the ~/out/<slug>/summary.md + figures/*.png generated by gemini-paper-summary to the outline workspace"

Execution：

1. 用 outline-wiki-search 查目标 Collection + 是否已有同名文档
2. 正文首块写 OKF yaml 元数据块（type: paper-note / tags / description /
   created / updated）——title 走 Outline 字段
3. 对每张 figures/*.png 走 attachment 3 步（详见上文"图片插入"）
4. 用 outline-wiki-search 的 read 拿当前 summary.md 中所有
   ![图 N](figures/figure-pX-fN.png) 引用
5. 用 update_document + editMode: "patch" + findText 精准替换每张图为
   ![图 N](/api/attachments.redirect?id=<uuid> "=WxH")
6. 验证 fetch 返回每张图 signedUrl 能 200 下载
7. （可选）删本地 figures/ 目录

Related references

outline-wiki-setup SKILL.md — Companion: MCP configuration and initial setup
outline-wiki-search SKILL.md — Companion: search / read outline documents (the collaborator for this skill's "pre-write search duplicate check")
references/doc_style.md — Markdown ↔ ProseMirror node mapping (§1-§13) + image attachment upload flow (§12) + @mention (§13) + OKF agent readable baseline (upload format control) + advanced
references/style_checklist.md — Must run before writing style checklist (§0 OKF metadata + §1-§9 style)
llm-wiki-management SKILL.md — Repository of the OKF v0.1 subset anchors (this skill's OKF upload format follows the same definition)

About this skill

When to use / not use

Use

Do not use

Input / Output

Input

Output

Design decision (write Markdown according to the "projection" of ProseMirror JSON)

OKF upload format (agent-readable baseline)

MCP tool discovery (important)

Capability list

Core capabilities

1. Create

2. Edit

Extended capabilities

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

4. @mention users (list_users)

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

6. Collection management

7. Move / Delete documents

Document style (repository fingerprint quick reference)

Style baseline (quick reference table)

Anti-patterns (read before writing)

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

Execution principles / boundaries

Core principles

Boundaries

Workflow / Steps

Standard process

Image Insertion / File Attachment Workflow

Client onboarding (first use)

Troubleshooting

Reference examples

Example 1: Creating a new document

Example 2: Updating an existing document

Example 3: Pushing images from gemini-paper-summary to outline

Related references