yuque-knowledge-base（语雀知识库）

This skill enables AI agents to interact with Yuque (语雀) — a Chinese knowledge management platform — through its OpenAPI. It works across Claude Code, opencode, openclaw, and any agent with shell access.

Quick Start

Install this skill, then tell your AI agent:

帮我配置语雀 API，我的 token 是 xxxxxxxx

The agent will automatically create config.json and verify connectivity.

How to get your API Token

1. Login to Yuque
2. Click Avatar → Settings (设置) → Developer (开发者) → Personal Access Token (个人访问令牌)
3. Create a new token, copy it

Setup Details

Authentication requires a Yuque API token. The scripts look for it in this order:

1. config.json (preferred): Create config.json in this skill's root directory:

   {
     "api_token": "your-yuque-api-token",
     "base_url": "https://www.yuque.com"
   }

See config.example.json for the template.

1. Environment variable (fallback): export YUQUE_TOKEN="your-token"

When the user provides their API token, create config.json by copying config.example.json and filling in the token, then run python scripts/get_user.py to verify. If verification succeeds, show the user's name to confirm.

Verify setup: python scripts/get_user.py

Scripts

All scripts are in the scripts/ directory. They use only Python standard library (zero dependencies). Output is JSON to stdout, errors go to stderr.

Search & Read (RAG)

Create & Edit

Knowledge Base

Table of Contents

User

Workflows

Search & Read (RAG)

When the user asks to find or read content from Yuque:

1. Search: python scripts/search.py "keyword" — returns titles, IDs, and summaries
2. Present the search results to the user as a numbered list
3. Once the user selects a document, fetch the full content:

python scripts/get_doc.py --repo REPO_ID --doc DOC_ID

1. The response data.body field contains the markdown content. If body is empty, use body_html or body_lake as fallback.

Write & Upload

When the user asks to write content and upload it to Yuque (e.g., "write a dev doc and upload to Yuque"):

1. Write the content locally as a markdown file (e.g., /tmp/yuque_doc.md)
2. Find the target repo: python scripts/list_repos.py — ask the user which repo to use
3. Upload: python scripts/create_doc.py --repo REPO_ID --title "Title" --body-file /tmp/yuque_doc.md
4. The response includes the document URL in data.slug — combine with repo namespace to form the full URL

Edit Existing Document

When the user asks to update an existing Yuque document:

1. Find the doc: python scripts/search.py "doc title" or python scripts/list_docs.py --repo REPO_ID
2. Read current content: python scripts/get_doc.py --repo REPO_ID --doc DOC_ID
3. Modify the content locally
4. Update: python scripts/update_doc.py --repo REPO_ID --doc DOC_ID --body-file /tmp/updated.md

Organize Notes

When the user asks to organize or restructure their knowledge base:

1. View current structure: python scripts/get_toc.py --repo REPO_ID
2. Plan the reorganization based on user instructions
3. Apply changes: python scripts/update_toc.py --repo REPO_ID --action appendNode --action-mode child --doc-ids DOC_ID
4. Use --action removeNode to remove nodes, --action editNode to rename

Script Details

Body input for create/update

Documents support three ways to provide body content:

• --body "inline content" — for short content
• --body-file /path/to/file.md — for files (recommended for long content)
• Pipe via stdin: echo "content" | python scripts/create_doc.py ...

Pagination

List endpoints support --offset and --limit parameters. Default limit is 100.

Repository identifiers

The --repo parameter accepts either:

• Numeric ID: --repo 12345
• Namespace path: --repo group_login/book_slug (more readable)

Document format

Default format is markdown. All scripts default to creating/updating in markdown format. Use --format html or --format lake if needed.

User Intent Mapping