New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Siyuan

by Tommy-yw in Tommy-yw/RunbookHermes

SiYuan Note API for searching, reading, creating, and managing blocks and documents in a self-hosted knowledge base via curl.

MITAuto-check: notesKnowledge Management

Install Siyuan

skills CLI
$ npx skills add Tommy-yw/RunbookHermes --skill siyuan -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install Tommy-yw/RunbookHermes siyuan --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/Tommy-yw/RunbookHermes.git skills-src && mkdir -p .claude/skills && cp -r skills-src/optional-skills/productivity/siyuan .claude/skills/siyuan && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
siyuan
GitHub stars
546
Used in
3 other repos
Token cost
~2.3k tokens
SKILL.md length
441 words
Files
1
Skills in repo
38
Repo updated
First seen
Licence
MIT

At a glance

SiYuan Note API for searching, reading, creating, and managing blocks and documents in a self-hosted knowledge base via curl.

  • Works in 3 steps: Install and run SiYuan (desktop or Docker) → Get your API token: Settings > About >… → Store it in ~/.hermes/.env
  • Tasks that involve Knowledge bases
  • SKILL.md covers Prerequisites, API Basics, Quick Reference and Common Operations, plus 3 more sections
  • Calls curl and jq; needs SIYUAN_TOKEN

What it does

Siyuan is an agent skill from Tommy-yw/RunbookHermes. SiYuan Note API for searching, reading, creating, and managing blocks and documents in a self-hosted knowledge base via curl.

Its SKILL.md is about 2.3k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Knowledge Management, covering Knowledge bases. It works with SQL. The repository describes itself as: Hermes-native AIOps agent for evidence-driven incident response, approval-gated remediation, and runbook learning. The licence is MIT.

When your agent uses it

  • Tasks that involve Knowledge bases

Example prompts

  • “/siyuan”

Requirements

  • Node.js
  • Docker
  • A credential in SIYUAN_TOKEN

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

  1. Install and run SiYuan (desktop or Docker)
  2. Get your API token: Settings > About > API token
  3. Store it in ~/.hermes/.env

What it can do on your machine

Read from SKILL.md and the folder at commit 7fd2b9a. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • curl
    • jq

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • github.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names these keys or tokens, usually read from environment variables:

    • SIYUAN_TOKEN

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Siyuan loads about 2.3k tokens when it runs. Until then it costs about 33 tokens; SKILL.md has 441 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~33
When it runs · the whole SKILL.md, loaded when a task matches
~2.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NoteMentions a .env fileSKILL.md:32
    3. Store it in `~/.hermes/.env`:

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from Tommy-yw/RunbookHermes at commit 7fd2b9a, republished under its MIT licence (© Tommy-yw). 441 words, ~2,315 tokens.

Download SKILL.mdSave it as .claude/skills/siyuan/SKILL.md (or your agent's skills folder).
name
siyuan
description
SiYuan Note API for searching, reading, creating, and managing blocks and documents in a self-hosted knowledge base via curl.
version
1.0.0
author
FEUAZUR
license
MIT
prerequisites.env_vars
SIYUAN_TOKEN
prerequisites.commands
curl, jq

SiYuan Note API

Use the SiYuan kernel API via curl to search, read, create, update, and delete blocks and documents in a self-hosted knowledge base. No extra tools needed -- just curl and an API token.

Prerequisites

  1. Install and run SiYuan (desktop or Docker)
  2. Get your API token: Settings > About > API token
  3. Store it in ~/.hermes/.env:
    SIYUAN_TOKEN=your_token_here
SIYUAN_URL=http://127.0.0.1:6806
    SIYUAN_URL defaults to http://127.0.0.1:6806 if not set.

API Basics

All SiYuan API calls are POST with JSON body. Every request follows this pattern:

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/..." \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"param": "value"}'

Responses are JSON with this structure:

json
{"code": 0, "msg": "", "data": { ... }}

code: 0 means success. Any other value is an error -- check msg for details.

ID format: SiYuan IDs look like 20210808180117-6v0mkxr (14-digit timestamp + 7 alphanumeric chars).

Quick Reference

OperationEndpoint
Full-text search/api/search/fullTextSearchBlock
SQL query/api/query/sql
Read block/api/block/getBlockKramdown
Read children/api/block/getChildBlocks
Get path/api/filetree/getHPathByID
Get attributes/api/attr/getBlockAttrs
List notebooks/api/notebook/lsNotebooks
List documents/api/filetree/listDocsByPath
Create notebook/api/notebook/createNotebook
Create document/api/filetree/createDocWithMd
Append block/api/block/appendBlock
Update block/api/block/updateBlock
Rename document/api/filetree/renameDocByID
Set attributes/api/attr/setBlockAttrs
Delete block/api/block/deleteBlock
Delete document/api/filetree/removeDocByID
Export as Markdown/api/export/exportMdContent

Common Operations

Search (Full-Text)
bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/search/fullTextSearchBlock" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "meeting notes", "page": 0}' | jq '.data.blocks[:5]'
Search (SQL)

Query the blocks database directly. Only SELECT statements are safe.

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/query/sql" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"stmt": "SELECT id, content, type, box FROM blocks WHERE content LIKE '\''%keyword%'\'' AND type='\''p'\'' LIMIT 20"}' | jq '.data'

Useful columns: id, parent_id, root_id, box (notebook ID), path, content, type, subtype, created, updated.

Read Block Content

Returns block content in Kramdown (Markdown-like) format.

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/getBlockKramdown" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data.kramdown'
Read Child Blocks
bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/getChildBlocks" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'
Get Human-Readable Path
bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/getHPathByID" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'
Get Block Attributes
bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/attr/getBlockAttrs" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'
List Notebooks
bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/notebook/lsNotebooks" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' | jq '.data.notebooks[] | {id, name, closed}'
List Documents in a Notebook
bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/listDocsByPath" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"notebook": "NOTEBOOK_ID", "path": "/"}' | jq '.data.files[] | {id, name}'
Create a Document
bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/createDocWithMd" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notebook": "NOTEBOOK_ID",
    "path": "/Meeting Notes/2026-03-22",
    "markdown": "# Meeting Notes\n\n- Discussed project timeline\n- Assigned tasks"
  }' | jq '.data'
Create a Notebook
bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/notebook/createNotebook" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My New Notebook"}' | jq '.data.notebook.id'
Append Block to Document
bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/appendBlock" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parentID": "DOCUMENT_OR_BLOCK_ID",
    "data": "New paragraph added at the end.",
    "dataType": "markdown"
  }' | jq '.data'

Also available: /api/block/prependBlock (same params, inserts at the beginning) and /api/block/insertBlock (uses previousID instead of parentID to insert after a specific block).

Update Block Content
bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/updateBlock" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "BLOCK_ID",
    "data": "Updated content here.",
    "dataType": "markdown"
  }' | jq '.data'
Rename a Document
bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/renameDocByID" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "DOCUMENT_ID", "title": "New Title"}'
Show full SKILL.md (178 more words)Show less
Set Block Attributes

Custom attributes must be prefixed with custom-:

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/attr/setBlockAttrs" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "BLOCK_ID",
    "attrs": {
      "custom-status": "reviewed",
      "custom-priority": "high"
    }
  }'
Delete a Block
bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/deleteBlock" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "BLOCK_ID"}'

To delete a whole document: use /api/filetree/removeDocByID with {"id": "DOC_ID"}. To delete a notebook: use /api/notebook/removeNotebook with {"notebook": "NOTEBOOK_ID"}.

Export Document as Markdown
bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/export/exportMdContent" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "DOCUMENT_ID"}' | jq -r '.data.content'

Block Types

Common type values in SQL queries:

TypeDescription
dDocument (root block)
pParagraph
hHeading
lList
iList item
cCode block
mMath block
tTable
bBlockquote
sSuper block
htmlHTML block

Pitfalls

  • All endpoints are POST -- even read-only operations. Do not use GET.
  • SQL safety: only use SELECT queries. INSERT/UPDATE/DELETE/DROP are dangerous and should never be sent.
  • ID validation: IDs match the pattern YYYYMMDDHHmmss-xxxxxxx. Reject anything else.
  • Error responses: always check code != 0 in responses before processing data.
  • Large documents: block content and export results can be very large. Use LIMIT in SQL and pipe through jq to extract only what you need.
  • Notebook IDs: when working with a specific notebook, get its ID first via lsNotebooks.

Alternative: MCP Server

If you prefer a native integration instead of curl, install the SiYuan MCP server:

yaml
# In ~/.hermes/config.yaml under mcp_servers:
mcp_servers:
  siyuan:
    command: npx
    args: ["-y", "@porkll/siyuan-mcp"]
    env:
      SIYUAN_TOKEN: "your_token"
      SIYUAN_URL: "http://127.0.0.1:6806"

© Tommy-yw, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in optional-skills/productivity/siyuan of Tommy-yw/RunbookHermes.

Open the folder on GitHubat commit 7fd2b9a

Used in 3 other repositories

We found 3 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 3 other GitHub owners. This page covers the copy in Tommy-yw/RunbookHermes, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Siyuan next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Siyuan compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Siyuan this skillTommy-yw/RunbookHermes5463 repos~2.3kAutomated safety check: NotesMIT
CLI Anything SiyuanHKUDS/CLI-Anything52k—~875Automated safety check: PassApache-2.0
Ima Knowledge Basecountbot-ai/CountBot784—~506Automated safety check: PassMIT
HypatiaMarchLiu/hypatia239—~7.9kAutomated safety check: NotesMIT
Migrateguhcostan/claude-mega-brain126—~975Automated safety check: PassMIT
Psr Autoloading Knowledgedykyi-roman/awesome-claude-code104—~2.1kAutomated safety check: PassMIT

Similar skills

  • CLI Anything Siyuan

    HKUDS/CLI-Anything

    SiYuan (思源笔记) CLI — manage notebooks, documents, blocks, and search your knowledge base from the terminal.

    52k GitHub stars~875 tokensUpdated 19 days ago
    Knowledge ManagementAuto-check passed

  • Ima Knowledge Base

    countbot-ai/CountBot

    通过 IMA OpenAPI 处理知识库任务。支持知识库内容搜索、命中详情查看、条目浏览、列出知识库、上传文件、导入网页。用户提到知识库、资料库、上传到知识库、导入网页、搜知识库时使用。

    784 GitHub stars~506 tokensUpdated today
    Knowledge ManagementAuto-check passed

  • Hypatia

    MarchLiu/hypatia

    Interact with the Hypatia AI memory system using natural language.

    239 GitHub stars~7.9k tokensUpdated 12 days ago
    Knowledge ManagementAuto-check: notes

  • Migrate

    guhcostan/claude-mega-brain

    Scan the project and migrate existing documentation into OKF format.

    126 GitHub stars~975 tokensUpdated 2 mo ago
    Knowledge ManagementAuto-check passed

  • Psr Autoloading Knowledge

    dykyi-roman/awesome-claude-code

    PSR-4 autoloading standard knowledge base for PHP 8.4 projects.

    104 GitHub stars~2.1k tokensUpdated 1 mo ago
    Knowledge ManagementAuto-check passed

  • Psr Overview Knowledge

    dykyi-roman/awesome-claude-code

    PHP Standards Recommendations (PSR) overview knowledge base.

    104 GitHub stars~2.7k tokensUpdated 1 mo ago
    Knowledge ManagementAuto-check passed

More from Tommy-yw/RunbookHermes

All 38 skills in this repo

  • Fastmcp

    Tommy-yw/RunbookHermes

    Build, test, inspect, install, and deploy MCP servers with FastMCP in Python.

    546 GitHub starsUsed in 3 repos~2.1k tokens
    Auto-check passed

  • Drug Discovery

    Tommy-yw/RunbookHermes

    Pharmaceutical research assistant for drug discovery workflows.

    546 GitHub starsUsed in 1 repo~2.3k tokens
    Auto-check passed

  • Youtube Content

    Tommy-yw/RunbookHermes

    Fetch YouTube video transcripts and transform them into structured content (chapters, summaries, threads, blog posts).

    546 GitHub starsUsed in 1 repo~785 tokens
    Auto-check passed

  • Oss Forensics

    Tommy-yw/RunbookHermes

    Supply chain investigation, evidence recovery, and forensic analysis for GitHub repositories.

    546 GitHub starsUsed in 3 repos~5k tokens
    Auto-check passed

  • P5js

    Tommy-yw/RunbookHermes

    Production pipeline for interactive and generative visual art using p5.js.

    546 GitHub starsUsed in 1 repo~6.8k tokens
    Auto-check passed

  • Touchdesigner MCP

    Tommy-yw/RunbookHermes

    Control a running TouchDesigner instance via twozero MCP — create operators, set parameters, wire connections, execute Python, build real-time visuals.

    546 GitHub starsUsed in 2 repos~3.4k tokens
    Auto-check passed

Works with

Categories

Questions about Siyuan

What does Siyuan do?

SiYuan Note API for searching, reading, creating, and managing blocks and documents in a self-hosted knowledge base via curl. Siyuan is an agent skill from Tommy-yw/RunbookHermes. SiYuan Note API for searching, reading, creating, and managing blocks and documents in a self-hosted knowledge base via curl.

When should I use Siyuan?

Siyuan fits situations like: tasks that involve Knowledge bases.

How do I install Siyuan in Claude Code?

Run `npx skills add Tommy-yw/RunbookHermes --skill siyuan -a claude-code`. Or copy the skill folder (optional-skills/productivity/siyuan in Tommy-yw/RunbookHermes) into .claude/skills/siyuan in your project. Claude Code loads it when a task matches its description.

How do I install Siyuan in Codex?

Run `npx skills add Tommy-yw/RunbookHermes --skill siyuan -a codex`. Or copy the skill folder (optional-skills/productivity/siyuan in Tommy-yw/RunbookHermes) into .agents/skills/siyuan in your project. Codex loads it when a task matches its description.

Can I use Siyuan in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add Tommy-yw/RunbookHermes --skill siyuan -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/siyuan, .gemini/skills/siyuan, .github/skills/siyuan and .opencode/skills/siyuan in your project.

What does Siyuan need to run?

Going by SKILL.md and its folder, Siyuan needs the command-line tools its instructions call (curl and jq) and credentials named SIYUAN_TOKEN. Our summary lists: Node.js; Docker; A credential in SIYUAN_TOKEN.

Does Siyuan access the network?

SKILL.md names 1 domain. As links in the text: github.com. This is read from the text; nothing was executed.

Is Siyuan safe to install?

Our automated static check of SKILL.md found notes only (mentions a .env file), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Siyuan use?

Siyuan is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Siyuan use?

About 2.3k tokens (SKILL.md is roughly 9.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Siyuan?

Skills that share tags, products or a category with Siyuan: CLI Anything Siyuan (HKUDS/CLI-Anything, 52k stars), Ima Knowledge Base (countbot-ai/CountBot, 784 stars), Hypatia (MarchLiu/hypatia, 239 stars) and Migrate (guhcostan/claude-mega-brain, 126 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Siyuan?

Tommy-yw (a GitHub user) maintains it in Tommy-yw/RunbookHermes, which has 546 GitHub stars. The repository holds 38 skills in this directory. The repository was last updated on May 18, 2026.

Source: Tommy-yw/RunbookHermes on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.