SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillssiyuan-skill

siyuan-skill

Office & productivity

View repository

Updated 10-15 22:13

About this skill

SiYuan Note (思源筆記) Skill (for OpenClaw)

The goal of this Skill is to organize the "SiYuan Note MCP tools" intostable, reusableworkflows.

  • MCP is responsible for providing tools
  • Skill is responsible for telling OpenClaw: in which scenarios to use which tools, how to combine them, and how to write the results back into notes

Principle: Separate MCP and Skill (minimal coupling). Skill does not describe the internal implementation of MCP, only "how to use it".

0) Prerequisites (Setup)

  1. Prepare token/baseUrl:
export SIYUAN_TOKEN="your_token_here"
export SIYUAN_BASE_URL="http://127.0.0.1:6806"
  1. mcporter needs to be configured with an MCP server named siyuan :
mcporter config add siyuan \
  --command "siyuan-mcp stdio --token $SIYUAN_TOKEN --baseUrl $SIYUAN_BASE_URL"
  1. How to call:
mcporter call siyuan.<tool_name> key=value

List tools and parameters:

mcporter list siyuan --all-parameters

1) Default settings (this environment)

  • Daily Note notebook：Daily Note
  • Daily Note notebook_id：20260205161632-m9mibni
  • Collection strategy (Inbox): All quick notes are first written into the Daily Note (pure Markdown)
  • TODO format：Markdown checkbox
    • Incomplete:- [ ] ...
    • Completed:- [x] ...

2) Core workflows (MVP)

Workflow A: Quick note (write into today's Daily Note)

Applies to: You say "help me note down...", "quick note...", "memo..."

Tool chain:append_to_daily_note

mcporter call siyuan.append_to_daily_note \
  notebook_id="20260205161632-m9mibni" \
  content="- 2026-02-05 16:30 這是一則快速記錄"

Workflow B: Add a to-do (checkbox, write into today's Daily Note)

Applies to: You say "remind me...", "TODO...", "to-do..."

Tool chain:append_to_daily_note

mcporter call siyuan.append_to_daily_note \
  notebook_id="20260205161632-m9mibni" \
  content="- [ ] 明天買電池"

Workflow C: List incomplete to-dos from the past N days (Daily Note scope)

Applies to: You say "What have I not finished yet?", "List incomplete to-dos"

Tool chain:list_daily_note_todos

mcporter call siyuan.list_daily_note_todos \
  notebook_id="20260205161632-m9mibni" \
  days=7

Expected return (illustrative):

[
  {
    "text": "明天買電池",
    "done": false,
    "date": "2026-02-05",
    "document_id": "...",
    "line_no": 12
  }
]

Workflow D: Search notes (keyword/tag/filename)

Applies to: You say "help me find...", "search..."

Tool chain:unified_search → (if necessary)get_document_content

# 內容搜尋
mcporter call siyuan.unified_search content="kubernetes" limit=10

# 檔名搜尋
mcporter call siyuan.unified_search filename="週報" limit=10

# 標籤搜尋（不含 #）
mcporter call siyuan.unified_search tag="project" limit=10

Workflow E: Organize today (section the Daily Note, list to-dos, produce archive candidates)

Applies to: You say "organize today", "help me organize today's notes"

Goal (MVP):

  • Do not change your original writing style too much (pure Markdown）
  • Organize the content into fixed sections: Inbox / TODO / Today's organization (summary, key points, archivable)
  • Archivable itemsList candidates first, do not move automatically (in line with the minimal principle)

Suggested tool chain (reliable version):

  1. Locate/create today's Daily Note:
  • Read the notebook's dailyNoteSavePath (optional)
  • Use the default path (or follow the notebook settings) to find today's hpath
  • get_ids_by_hpath → if it does not exist, you can use create_document create
  1. Read today's content:
  • get_document_content(document_id)
  1. List incomplete TODOs (the past 1 day is enough):
  • list_daily_note_todos(notebook_id, days=1)
  1. Produce an organized paragraph and write it back:
  • append_to_document(document_id, content)

Example (after finding today's document):

mcporter call siyuan.list_daily_note_todos \
  notebook_id="20260205161632-m9mibni" \
  days=1

mcporter call siyuan.append_to_document \
  document_id="<today_document_id>" \
  content="\n\n## 今日整理（AI）\n\n- 摘要：...\n- 重點：...\n- 未完成 TODO：...\n- 可歸檔（候選）：...\n"

Workflow F: Produce a weekly report (first generate Markdown, then decide whether to write it back)

Applies to: You say "help me produce this week's weekly report"

Suggested process (minimal version):

  1. First use list_daily_note_todos to pull out this week's incomplete items
  2. Then use search/recent updates/read content to supplement material for "this week's completed items"
  3. Agent produces a pure Markdown file (at this stage, do not automatically write it back yet to avoid erroneous writes)

Automatic weekly report write-back (create_document) will be placed after the M2 milestone, and the template will be finalized then.

3) Write-back and organization (future expansion direction, not MVP)

Once the core is stable, gradually add:

  • Inbox → categorize → archive (create fixed folders and rules)
  • Deduplication (find similar notes, merge paragraphs, create index pages)
  • Guide the use of SiYuan attributes/templates/tags (let AI automatically fill them in)

4) Note organization guidelines

Link format

Internal SiYuan links use the following format, and clicking them jumps directly:

[顯示名稱](siyuan://blocks/文件ID)

Example:

- [維運客戶](siyuan://blocks/20250108190236-49uy54d)
- [SOP文件](siyuan://blocks/20250320164549-8nwn7q7)

Standard template for parent documents

A parent document with child documents should itself serve as a "table of contents/summary" page. Standard template:

## 摘要
- 主要內容/業務說明
- 負責人：（待補）

## 快速入口
- [最新/常用項目](siyuan://blocks/ID)

## 目錄
### 分類一
- [項目](siyuan://blocks/ID)

### 分類二
- [項目](siyuan://blocks/ID)

Structural principles

Principle Description
Hybrid classification Customer-specific → customer folder; shareable → extract to SOP/training
Parent document = table of contents/summary A parent document with child documents must itself allow content input and serve as an entry page
Place the index in the parent document Index content is placed directly in the parent document; do not create an additional child document
Single index page Each notebook only needs one master index that integrates all entry points

Content format

Principle Description
Pure Markdown Do not use special formatting
Use checkboxes for TODO - [ ] To do / - [x] Done
Do not duplicate H1 SiYuan automatically generates H1 (title); content starts from ## start
Use content_file for multi-line content Avoid \n literalization issues

Cleanup and archiving

Principle Description
Unnamed/duplicate → _duplicates Place temporarily in a central location; do not delete directly
Scattered documents → put back in place Move root-level documents under the corresponding category
Take a snapshot before organizing Rollback possible
Archiving requires confirmation Do not delete automatically; wait for user confirmation

Index page design guidelines

Design principles:

  1. Start with a quote block：> 💼 筆記本名稱 as a visual cue
  2. Emoji headings: for example 🚀 Quick access, 📂 Structure, 📌 Other…
  3. Tabular entry points: use a table to present "category/description" to improve readability
  4. Clickable links: always use [名稱](siyuan://blocks/ID)
  5. Use divider lines to separate sections: use --- to separate different blocks
  6. Structure description: use a code block to present the directory tree and help understand the overall architecture

Standard block order (recommended):

  1. Quote block prompt (notebook name + emoji)
  2. 🚀 Quick access (main category table)
  3. 🔥 Recently active / frequently used items (if applicable)
  4. 📋 Quick reference (e.g., SOP)
  5. 📌 Other commonly used links
  6. 📂 Structure description (directory tree)
  7. Usage rules / classification principles

Minimal example:

> 💼 筆記本名稱

## 🚀 快速入口

| 分類 | 說明 |
|------|------|
| [維運客戶](siyuan://blocks/ID) | 客戶專屬資料 |
| [SOP文件](siyuan://blocks/ID) | 標準作業流程 |

---

## 📂 結構

Notebook/ ├─ Index ├─ Category A/ └─ Category B/

5) Common precautions

⚠️ Passing multi-line content (important!)

When you use mcporter call to pass multi-line Markdown content,do notwrite directly in the parameter \n, it will become literal text.

❌ Incorrect way(it will become \n literal text):

mcporter call siyuan.update_document document_id="xxx" content="# 標題\n\n內容"

✅ Most recommended: use content_file(avoids all shell escaping issues)

cat << 'EOF' > /tmp/content.md
# 標題

這是內容。

## 小節
- 項目 1
- 項目 2
EOF

mcporter call siyuan.update_document document_id="xxx" content_file="/tmp/content.md"

✅ Other usable way 1: first write to a file and then use $(cat ...) to bring it in

mcporter call siyuan.update_document document_id="xxx" content="$(cat /tmp/content.md)"

✅ Other usable way 2: use $'...' syntax (bash)

mcporter call siyuan.update_document document_id="xxx" content=$'# 標題\n\n這是內容。'

✅ Other usable way 3: use multi-line quotes directly

mcporter call siyuan.update_document document_id="xxx" content="# 標題

這是內容。

## 小節
- 項目 1
- 項目 2
"

Other precautions

  • If the tool list cannot be read, first confirm:

    • SIYUAN_TOKEN、SIYUAN_BASE_URL whether it is correct
    • Whether Siyuan is started at that baseUrl
    • Whether mcporter has been configured siyuan

  • If you want to see all tools:

mcporter list siyuan --all-parameters