yuque · chen201724 · Jul 15, 2026 · Jul 15, 2026 · Jul 15, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -1,8 +1,7 @@
 {
   "name": "yuque",
   "owner": {
-    "name": "yuque",
-    "email": "willchen.babydog@gmail.com"
+    "name": "yuque"
   },
   "metadata": {
     "description": "语雀 AI 生态 — MCP Tools and Skills for Yuque",

diff --git a/AGENT-INSTALL.md b/AGENT-INSTALL.md
@@ -1,111 +1,185 @@
-# Yuque AI Ecosystem — Agent Installation Guide
+# Yuque AI — Agent Installation Guide
 
-> This document is designed for AI agents (Claude Code, OpenCode, OpenClaw, etc.) to read and automatically install Yuque integration. Human-readable but optimized for machine execution.
+> One file for every client. Designed for AI agents to read and auto-install; human-readable too.
+>
+> **TL;DR for agents:** the canonical skills live in [`skills/`](./skills/) (standard SKILL.md format — frontmatter + markdown). Any client that supports skills can copy them directly. The MCP server is `npx -y yuque-mcp` with a Yuque token. Client-specific steps below.
 
-## Step 1: Identify Your Environment
-
-Determine which AI coding client you are running in and follow the corresponding guide:
-
-- **Claude Code** → See [plugins/claude-code/AGENT-INSTALL.md](./plugins/claude-code/AGENT-INSTALL.md)
-- **OpenCode** → See [plugins/opencode/AGENT-INSTALL.md](./plugins/opencode/AGENT-INSTALL.md)
-- **Cursor / GitHub Copilot (VS Code) / Windsurf / Other Editors** → See [shared/mcp-config/AGENT-INSTALL.md](./shared/mcp-config/AGENT-INSTALL.md)
-- **OpenClaw** → See [plugins/openclaw/README.md](./plugins/openclaw/README.md)
+---
 
-### How to Detect Your Client
+## Step 0: Prerequisites (all clients)
 
 ```bash
-# Check if Claude Code is available
-claude --version 2>/dev/null && echo "CLIENT=claude-code"
+# Node.js >= 20 (18 is EOL)
+node --version
 
-# Check if OpenCode is available
-opencode --version 2>/dev/null && echo "CLIENT=opencode"
+# npx available
+npx --version
 
-# Check if running inside Cursor
-[ -n "$CURSOR_SESSION" ] && echo "CLIENT=cursor"
+# Yuque token set (get one at https://www.yuque.com/settings/tokens)
+[ -n "$YUQUE_TOKEN" ] && echo "TOKEN=set" || echo "TOKEN=missing"
+```
 
-# Check if running inside VS Code
-[ -n "$VSCODE_PID" ] && echo "CLIENT=vscode"
+Verify the token independently of any client:
 
-# Check if GitHub Copilot extension is installed (required for MCP support in VS Code)
-code --list-extensions 2>/dev/null | grep -i "github.copilot" && echo "COPILOT=installed"
+```bash
+curl -s -H "X-Auth-Token: $YUQUE_TOKEN" https://www.yuque.com/api/v2/user
+# ✅ JSON with your user profile   ❌ 401 = invalid token, regenerate it
 ```
 
-## Step 2: Prerequisites
+> Note for MCP configs: the `yuque-mcp` server process reads the token from `--token=...` or the `YUQUE_PERSONAL_TOKEN` env var (not `YUQUE_TOKEN` — configs below handle the mapping).
+
+---
+
+## Claude Code (recommended path)
 
-Before proceeding with any installation method, ensure the following:
+The only formally packaged distribution — one command installs MCP server + all skills, with updates.
 
 ```bash
-# Check Node.js version (>= 20 required; Node 18 is EOL)
-node --version
-# Expected output: v20.x.x or higher
+# 1. Register the marketplace (this alone installs nothing)
+claude plugin marketplace add yuque/yuque-ecosystem
 
-# Check npm is available
-npm --version
+# 2. Install the plugin — required step
+claude plugin install yuque-personal@yuque
 
-# Check npx is available
-npx --version
+# 3. Token via env var
+export YUQUE_TOKEN="your_token_here"   # add to ~/.zshrc for persistence
 ```
 
-If Node.js is not installed or version is below 20:
+Verify:
 
 ```bash
-# Install via nvm (recommended)
-curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
-source ~/.bashrc  # or ~/.zshrc
-nvm install 20
-nvm use 20
+claude plugin list | grep yuque-personal
+# ✅ "yuque-personal" appears   ❌ re-run step 2 and check its error output
 ```
 
-## Step 3: Get a Yuque API Token
-
-1. Navigate to <https://www.yuque.com/settings/tokens>
-2. Click **"Create New Token"**
-3. Grant the following permissions:
-   - ✅ Read documents
-   - ✅ Write documents
-   - ✅ Read knowledge bases
-   - ✅ Manage knowledge bases (optional, for create/delete operations)
-4. Copy the generated token
-5. Store it securely:
+MCP-only alternative (no skills):
 
 ```bash
-# Option A: Set as environment variable (recommended)
-export YUQUE_TOKEN="your_token_here"
+claude mcp add yuque-mcp -- npx -y yuque-mcp --token=$YUQUE_TOKEN
+claude mcp list | grep -i yuque
+```
+
+Uninstall: `claude plugin uninstall yuque-personal`, `claude plugin marketplace remove yuque`, or `claude mcp remove yuque-mcp`.
+
+---
 
-# Option B: Add to your shell profile for persistence
-echo 'export YUQUE_TOKEN="your_token_here"' >> ~/.zshrc  # or ~/.bashrc
-source ~/.zshrc
+## OpenCode
+
+```bash
+# 1. MCP server — global config uses {env:YUQUE_TOKEN}, resolved at runtime,
+#    so no plaintext token lands in the file
+mkdir -p ~/.config/opencode
+cat > ~/.config/opencode/opencode.json << 'EOF'
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "yuque": {
+      "type": "local",
+      "command": ["npx", "-y", "yuque-mcp", "--token={env:YUQUE_TOKEN}"],
+      "enabled": true
+    }
+  }
+}
+EOF
+# (merge the mcp.yuque entry instead if the file already exists)
+
+# 2. Skills — copy the canonical directory
+REPO_DIR="/path/to/yuque-ecosystem"   # cloned checkout
+mkdir -p ~/.config/opencode/skills
+cp -r "$REPO_DIR/skills/"* ~/.config/opencode/skills/
 ```
 
-## Step 4: Verify Token
+Project-level variants: `opencode.json` in the project root, skills in `.opencode/skills/`. Never write a literal token into a project-level config — it is too easy to commit.
+
+Verify: `opencode mcp list` shows `yuque`; `opencode mcp debug yuque` shows tools.
+
+---
+
+## OpenClaw
 
 ```bash
-# Quick test — should return your user info as JSON (401 = invalid token)
-curl -s -H "X-Auth-Token: $YUQUE_TOKEN" https://www.yuque.com/api/v2/user
+# 1. Skills — copy the canonical directory into OpenClaw's skills dir
+REPO_DIR="/path/to/yuque-ecosystem"
+mkdir -p ~/.openclaw/skills
+cp -r "$REPO_DIR/skills/"* ~/.openclaw/skills/
+```
+
+2. MCP server — add to OpenClaw's `mcpServers` config:
+
+```json
+{
+  "mcpServers": {
+    "yuque-mcp": {
+      "command": "npx",
+      "args": ["-y", "yuque-mcp"],
+      "env": { "YUQUE_PERSONAL_TOKEN": "your-yuque-token" }
+    }
+  }
+}
 ```
 
-## Step 5: Follow Client-Specific Guide
+---
+
+## Cursor / VS Code (Copilot) / Windsurf / other MCP editors
+
+Copy the matching template from [`shared/mcp-config/`](./shared/mcp-config/) and replace `YOUR_YUQUE_TOKEN`:
+
+| Client | Template | Destination |
+|--------|----------|-------------|
+| Cursor | `cursor.json` | `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global) |
+| VS Code (requires GitHub Copilot extension) | `vscode.json` | `.vscode/mcp.json` |
+| Windsurf | `windsurf.json` | `.windsurf/mcp.json` |
+
+> **Security:** project-level configs contain a plaintext token after replacement — add them to `.gitignore`:
+>
+> ```bash
+> printf '%s\n' '.cursor/mcp.json' '.vscode/mcp.json' '.windsurf/mcp.json' >> .gitignore
+> ```
+
+These editors get MCP tools only. If the client supports skills (SKILL.md), also copy [`skills/`](./skills/) into its skills directory.
+
+---
+
+## Any other agent
 
-Now proceed to the guide for your specific client (see Step 1 links above).
+1. **MCP tools:** run `npx -y yuque-mcp --token=$YUQUE_TOKEN` as a stdio MCP server, or set `YUQUE_PERSONAL_TOKEN` in its env.
+2. **Skills:** copy [`skills/`](./skills/) into wherever your client discovers SKILL.md files. Each skill is self-contained (frontmatter `name`/`description` + workflow instructions) and only assumes the `yuque-mcp` tools are available.
 
 ---
 
-## Quick Reference: All Installation Methods
+## Available After Installation
+
+### MCP Tools (from `yuque-mcp`)
+
+| Category | Tools |
+|----------|-------|
+| User | `yuque_get_user` |
+| Search | `yuque_search` |
+| Books (知识库) | `yuque_list_books`, `yuque_get_book`, `yuque_create_book`, `yuque_update_book` |
+| Docs | `yuque_list_docs`, `yuque_get_doc`, `yuque_create_doc`, `yuque_update_doc` |
+| TOC | `yuque_get_toc`, `yuque_update_toc` |
+| Notes (小记) | `yuque_list_notes`, `yuque_get_note`, `yuque_create_note`, `yuque_update_note` |
+| Boards (画板) | `yuque_get_resource`, `yuque_create_resource`, `yuque_update_resource` |
+
+### Skills (8)
+
+smart-search, smart-summary, daily-capture, reading-digest, note-refine, knowledge-connect, style-extract, stale-detector
 
-| Client | Method | Command |
-|--------|--------|---------|
-| Claude Code | Marketplace | `claude plugin marketplace add yuque/yuque-ecosystem && claude plugin install yuque-personal@yuque` |
-| Claude Code | MCP Direct | `claude mcp add yuque-mcp -- npx -y yuque-mcp --token=$YUQUE_TOKEN` |
-| OpenCode | Config File | Add to `opencode.json` (see OpenCode guide) |
-| Cursor | Config File | Add to `.cursor/mcp.json` (see MCP config guide) |
-| VS Code | Config File | Add to `.vscode/mcp.json` (requires GitHub Copilot extension; see MCP config guide) |
-| Windsurf | Config File | Add to `.windsurf/mcp.json` (see MCP config guide) |
+Functional test inside any client session:
+
+```
+> Use the yuque_get_user tool to get my user info
+```
+
+---
 
 ## Troubleshooting
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
-| `node: command not found` | Node.js not installed | Install Node.js >= 18 via nvm or package manager |
-| `npx: command not found` | npm/npx not in PATH | Reinstall Node.js or add to PATH |
-| Token test fails with 401 | Invalid or expired token | Regenerate token at yuque.com/settings/tokens |
-| Token test fails with network error | Firewall or proxy issue | Check network connectivity to `www.yuque.com` |
+| `node: command not found` | Node.js not installed | Install Node.js >= 20 via nvm (`nvm install 20`) |
+| Token test returns 401 | Invalid or expired token | Regenerate at <https://www.yuque.com/settings/tokens> |
+| MCP server fails to start | Token not reaching the process | Pass `--token=...` or set `YUQUE_PERSONAL_TOKEN` in the server env |
+| Plugin not found in marketplace | Marketplace not registered | Re-run `claude plugin marketplace add yuque/yuque-ecosystem` |
+| Skills not discovered | Wrong skills directory | Check your client's skills path (see its section above) |
+| `ECONNREFUSED` / timeout | Network blocking yuque.com | `curl -I https://www.yuque.com` |
diff --git a/README.en.md b/README.en.md
@@ -2,101 +2,76 @@
 
 # Yuque AI Ecosystem
 
-> The unified home for everything in the Yuque AI ecosystem — website, plugins, skills, and shared resources.
+> The official distribution repository for Yuque AI integrations — one set of skills, ready to use in any AI client, plus the website that presents them.
 
 [![Website](https://img.shields.io/badge/Website-yuque.github.io-blue)](https://yuque.github.io/yuque-ecosystem/)
 [![npm](https://img.shields.io/npm/v/yuque-mcp)](https://www.npmjs.com/package/yuque-mcp)
 
 📖 **[Yuque + AI: From Documentation Tool to Your Second Brain](https://www.yuque.com/yuque/ai/yuque-ai-ecosystem-final)** — Explore the full vision of the Yuque AI Ecosystem
 
-## Architecture
+## Positioning
 
-This is a **Stripe-style monorepo**: one core SDK ([yuque-mcp-server](https://github.com/yuque/yuque-mcp-server)) + one ecosystem repository (this repo) containing all client integrations.
+**Skills are the asset, client integrations are distribution, the website is the storefront.** Capability and experience live in separate repositories: [yuque-mcp-server](https://github.com/yuque/yuque-mcp-server) defines what the AI *can do* (MCP tools); this repository defines how users *get it* (skill workflows, install docs, and the website).
 
-| Repository | Purpose | Stripe Analogy |
+| Layer | Content | Location |
 |---|---|---|
-| [yuque-mcp-server](https://github.com/yuque/yuque-mcp-server) | Core MCP Server (npm package) | stripe-node (SDK) |
-| **yuque-ecosystem** (this repo) | Website + All Client Plugins + Skills | stripe-examples + docs |
+| Capability | MCP Server (npm: `yuque-mcp`) | [yuque-mcp-server](https://github.com/yuque/yuque-mcp-server) |
+| Asset | Knowledge-management skills (single source, standard SKILL.md format) | [`skills/`](./skills/) |
+| Distribution | Claude Code Marketplace packaging + all-client install guide | [`plugins/yuque-personal/`](./plugins/yuque-personal/) · [`AGENT-INSTALL.md`](./AGENT-INSTALL.md) |
+| Storefront | Website (showcase + install guides) | [`website/`](./website/) |
+
+SKILL.md is a cross-client format — OpenCode, OpenClaw, and any other skills-capable client can copy [`skills/`](./skills/) into their own skills directory directly; no dedicated adapter layer needed. Claude Code is the one channel with formal packaging (one-command marketplace install with updates).
 
 ## Repository Structure
 
 ```
 yuque-ecosystem/
-├── website/                  # Official website (GitHub Pages)
+├── skills/                   # ★ The asset: 8 knowledge-management skills (single source)
+├── AGENT-INSTALL.md          # All-client install guide (directly executable by agents)
 ├── plugins/
-│   ├── yuque-personal/       # Claude Code plugin (personal edition) — canonical skills source
-│   │   ├── .claude-plugin/   #   plugin.json
-│   │   ├── .mcp.json         #   MCP server config
-│   │   └── skills/           #   8 skills (canonical — other clients are synced by script)
-│   ├── claude-code/          # Claude Code install docs
-│   ├── opencode/             # OpenCode integration (MCP config + skills copies)
-│   └── openclaw/             # OpenClaw plugin (skills copies)
+│   └── yuque-personal/       # Claude Code Marketplace packaging
+│       ├── .claude-plugin/   #   plugin.json
+│       ├── .mcp.json         #   MCP server config
+│       └── skills/           #   synced copy (do not edit; CI checks drift)
 ├── shared/
-│   └── mcp-config/           # MCP config templates for various editors
-├── scripts/                  # sync-skills.mjs — sync canonical skills to client copies
-├── .claude-plugin/           # Claude Code Marketplace entry
-└── package.json              # npm workspaces root
+│   └── mcp-config/           # MCP config templates for Cursor / VS Code / Windsurf, etc.
+├── scripts/                  # sync-skills.mjs — skills/ → plugin copy
+├── website/                  # Official website (GitHub Pages)
+└── .claude-plugin/           # Claude Code Marketplace entry
 ```
 
 > **The team edition (yuque-group) is temporarily withdrawn**: its skills depend on group-statistics MCP tools (`yuque_group_*`) that are not yet available in `yuque-mcp`. It will return once the underlying tools ship. See git history for the previous code.
 
 ## Quick Start
 
-### Claude Code
+### Claude Code (recommended — the formally packaged channel)
 
 ```bash
-# Option 1: Install via Marketplace (MCP tools + skills)
 claude plugin marketplace add yuque/yuque-ecosystem
 claude plugin install yuque-personal@yuque
 export YUQUE_TOKEN="your_token"   # the plugin reads the token from this env var
-
-# Option 2: Add MCP Server directly (MCP tools only, no skills)
-claude mcp add yuque-mcp -- npx -y yuque-mcp --token=YOUR_TOKEN
 ```
 
-### OpenCode
-
-Add to your `opencode.json`:
+MCP tools only, no skills:
 
-```jsonc
-{
-  "mcp": {
-    "yuque": {
-      "type": "local",
-      "command": ["npx", "-y", "yuque-mcp", "--token=YOUR_TOKEN"]
-    }
-  }
-}
+```bash
+claude mcp add yuque-mcp -- npx -y yuque-mcp --token=YOUR_TOKEN
 ```
 
-See [`plugins/opencode/`](./plugins/opencode/) for skills installation and the full setup guide.
-
-### Other Editors
+### Any other client (OpenCode / OpenClaw / Cursor / VS Code / Windsurf …)
 
-See [`shared/mcp-config/`](./shared/mcp-config/) for configuration templates for Cursor, Windsurf, GitHub Copilot (VS Code), and more.
+Two generic steps: ① configure `yuque-mcp` using a template from [`shared/mcp-config/`](./shared/mcp-config/); ② if the client supports skills, copy [`skills/`](./skills/) into its skills directory.
 
-## Modules
-
-| Module | Description | Link |
-|---|---|---|
-| 🌐 Website | Official ecosystem website | [`website/`](./website/) |
-| 🔌 Claude Code Plugin | Claude Code Marketplace plugin | [`plugins/claude-code/`](./plugins/claude-code/) |
-| 🟢 OpenCode Plugin | OpenCode MCP + Skills integration | [`plugins/opencode/`](./plugins/opencode/) |
-| 🤖 OpenClaw Plugin | OpenClaw Agent integration | [`plugins/openclaw/`](./plugins/openclaw/) |
-| 📋 MCP Config | Editor configuration templates | [`shared/mcp-config/`](./shared/mcp-config/) |
+Per-client commands live in [`AGENT-INSTALL.md`](./AGENT-INSTALL.md) — hand that file to your AI agent and it will install everything.
 
 ## Development
 
 ```bash
 # Website development
-cd website
-npm install
-npm run dev
-
-# OpenClaw Plugin development
-cd plugins/openclaw
-npm install
-npm run build
+cd website && npm install && npm run dev
+
+# After editing skills, sync the plugin copy (CI checks drift)
+npm run sync-skills
 ```
 
 ## Links