前言¶
团队文档落在语雀、日常编辑却在本地 Markdown 或仓库里时，常见做法是手动复制粘贴，或在 CI 里单独维护一套脚本。创建、更新、删除单篇文档、查看知识库目录（TOC）、对比本地与云端是否一致，这些操作分散在语雀控制台和本地文件之间，Agent 很难按你的意图一次性做完。
下面介绍 SkillHub 上的社区 Skill「语雀文档 skill」（坐标 @user_924c5114/yuque-docs-skill，当前版本 1.0.2）。它把语雀知识库文档的读写与同步能力封装成 Agent 可遵循的 SKILL 说明，适合在 Cursor、Claude Code、Codex 等支持 Skills 的环境里，用自然语言驱动文档推送、拉取与增量同步。
这是什么¶
「语雀文档 skill」是面向语雀（Yuque）知识库文档操作的 Agent Skill，采用通用 SKILL.md 格式，由社区发布者 user_924c5114（SkillHub 页面标注作者 Sean Liu）维护，在 SkillHub 分类为 knowledge-management，来源为 community。
当用户需要创建、更新、删除或列举语雀知识库中的文档、管理知识库目录结构，或把本地内容推到语雀、同步变更、查看仓库里已有内容时，应使用本 Skill。它不覆盖语雀团队成员、权限、知识库设置等管理面，也不适用于飞书、钉钉、Notion 等其他知识库，或跨知识库的批量迁移。
SkillHub 标签标明 requires_api_key=true，使用前需要准备语雀 API 访问凭证；具体变量名与配置步骤以安装后 Skill 包内 SKILL.md 为准。
核心功能¶
以下能力均来自 SkillHub 官方简介，彼此一致：
- 推送本地 Markdown 到语雀知识库：把仓库或目录中的 Markdown 上传到指定知识库。
- 拉取云端文档到本地：从语雀把文档内容同步到本地文件。
- 文档 CRUD：创建、更新、删除语雀中的文档。
- 查看目录结构（TOC）：浏览知识库的目录层级，便于对齐本地结构与云端标题。
- 智能增量同步（sync）：在本地与语雀之间做增量同步，减少全量覆盖。
- 状态对比（status）：对比本地与云端差异，便于决定先推还是先拉。
安装与启用¶
SkillHub 提供两种常见安装方式：用 CLI 装到当前 Agent 的 skills 目录，或把安装提示词发给 AI 让其按 SkillHub 安装文档操作。
通过 SkillHub CLI¶
先确认本机是否已有 skillhub：
command -v skillhub && skillhub --version
未安装时，可按 SkillHub 安装文档 执行完整安装（示例为官方给出的推荐命令）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
安装 Skill 时必须用 --dir 指向当前 Agent 实际使用的 skills 目录，否则默认会装到 ./skills/，Agent 可能识别不到。官方文档给出的常用路径包括：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
在对应目录下安装本 Skill 的示例：
skillhub install user_924c5114/yuque-docs-skill --dir ~/.cursor/skills/
将 ~/.cursor/skills/ 换成你当前环境的路径即可。安装后若 Agent 未立刻加载新 Skill，按你所用客户端的说明重启或重新打开会话。
通过 AI 安装提示词¶
SkillHub 技能页提供的提示词为：
请根据 https://skillhub.cn/install/skillhub.md，安装 `@user_924c5114/yuque-docs-skill`。
把上述内容发给支持 SkillHub 安装流程的 Agent，由其按安装文档完成拉取与落盘。
API 密钥¶
本 Skill 在 SkillHub 上标记为需要 API Key。安装完成后，在 Skill 包内的 SKILL.md 中查看语雀 Token 或相关凭证的配置方式，再让 Agent 执行文档操作。
典型用法¶
本 Skill 通过 Agent 理解 SKILL.md 中的流程来调用语雀能力，而不是替代你本机的 skillhub CLI。在已安装并配置 API 凭证的前提下，可以用自然语言描述目标，例如：
- 推送本地稿：说明本地 Markdown 路径与目标语雀知识库，要求将内容创建或更新到语雀。
- 拉取备份：指定知识库与文档，要求拉取到本地目录，便于版本管理或离线编辑。
- 看目录：要求列出某知识库的 TOC，再决定本地文件与云端标题如何对应。
- 增量同步：在本地与语雀已有关联关系时，要求执行 sync，只处理有变更的文档。
- 先对比再操作：要求执行 status，根据差异再选择推送或拉取。
具体子命令、参数与错误处理以安装后的 SKILL.md 为准；上文仅为与官方功能列表对应的使用意图示例。
适用场景与注意¶
适合谁
- 已在语雀托管团队或项目知识库，同时用 Git 或本地 Markdown 写作的团队。
- 希望在 Cursor、Claude Code、Codex 等环境里用对话完成「推一篇文档」「拉最新版」「对一下两边差什么」，而不是每次打开语雀网页手工操作。
边界与限制
- 仅针对语雀文档与知识库目录相关操作；成员、权限、知识库设置等管理需求不要用本 Skill。
- 不负责飞书、钉钉、Notion 等平台，也不做跨知识库批量迁移。
- 依赖语雀 API 与有效 API Key；网络与配额限制以语雀官方为准。
- SkillHub 页面显示版本为 v1.0.2，社区来源；升级与变更以 SkillHub 上该坐标发布的版本为准。
结尾¶
「语雀文档 skill」把推送与拉取 Markdown、文档增删改查、TOC 查看、sync 与 status 等能力收敛到一个 Agent Skill 里，适合把语雀当作正式知识库、又把本地或仓库当作编辑源的场景。安装时记住坐标 @user_924c5114/yuque-docs-skill，并用 --dir 对准当前客户端的 skills 目录。
- Skill API 地址：https://api.skillhub.cn/user_924c5114/yuque-docs-skill
- SkillHub 技能页：https://www.skillhub.cn/skills/user_924c5114/yuque-docs-skill
- SkillHub 安装说明：https://skillhub.cn/install/skillhub.md
