Skills 安装使用

5 months ago
24b1019

Skills 安装使用

M-Doc 提供自定义技能（Skill），让各种 AI 工具能够通过自然语言直接查询、浏览、搜索和管理文档内容。Skills 是一种通用的 AI 工具扩展机制，支持所有兼容 Skill 协议的工具。

概述

mdoc-skills 为 AI 工具添加了 mdoc 技能。安装后，你可以直接将任意 mdoc.cc URL 或 orgSlug/docSlug 短路径粘贴到提示词中，AI 工具会自动向 M-Doc OpenAPI 发起认证请求，获取文档目录或文章内容并内联展示。

支持的工具

目前以下 AI 工具支持安装和使用 Skills：

工具 安装方式
Claude Code claude install-skill 命令
Gemini CLI 将 Skill 目录放入 ~/.gemini/skills/
其他兼容工具 参考各工具的 Skill 安装文档

支持的功能

功能 说明
获取文档目录 以树形结构展示文档的完整目录
读取文章内容 获取指定文章的 Markdown 原文
语义搜索 基于 AI 的语义搜索，返回相关文章列表
创建文章 通过自然语言创建新文章
更新文章 修改已有文章的标题和内容
删除文章 删除指定文章
发布文章 将文章草稿发布为正式版本
合并文章 将文章从一个版本合并到另一个版本

前置要求

  • 已安装支持 Skill 的 AI 工具（如 Claude Code、Gemini CLI 等）
  • 一个 M-Doc 个人访问令牌（PAT）

安装步骤

第一步：获取个人访问令牌

  1. 打开 https://mdoc.cc/settings，进入 个人令牌 页面。
  2. 点击生成新的 PAT，格式为 mdoc_pat_xxxxxxxxxxxxxxxx。
  3. 在终端中导出令牌（建议写入 ~/.zshrc 或 ~/.bashrc 以持久生效）：
export MDOC_TOKEN="mdoc_pat_你的令牌"

注意：如需使用文章写操作（创建、更新、删除、发布、合并），请确保令牌具有 write:articles 权限。

第二步：安装 Skill

根据你使用的 AI 工具，选择对应的安装方式：

Claude Code

claude install-skill https://cnb.cool/mliev/mdoc/mdoc-skills/-/tree/main/mdoc

Gemini CLI

# 克隆 Skill 仓库到 Gemini 的 skills 目录
git clone https://cnb.cool/mliev/mdoc/mdoc-skills.git ~/.gemini/skills/mdoc-skills

手动安装（通用方式）

对于其他支持 Skill 的工具，可以直接克隆仓库后按照工具的文档指引配置 Skill 路径：

git clone https://cnb.cool/mliev/mdoc/mdoc-skills.git

Skill 定义文件位于 mdoc/SKILL.md，将其所在目录指向你的工具即可。

第三步：验证安装

启动 AI 工具后，输入以下内容验证技能是否正常工作：

/mdoc mliev/mdoc

或直接粘贴 URL：

https://mdoc.cc/mliev/mdoc

如果安装成功，你将看到文档的目录树结构。

使用方式

输入格式

支持以下输入格式：

格式 示例
完整 URL https://mdoc.cc/mliev/mdoc
带版本的 URL https://mdoc.cc/mliev/mdoc/v1.0.0
带文章的 URL https://mdoc.cc/mliev/mdoc/v1.0.0/32
短路径 mliev/mdoc
带版本的短路径 mliev/mdoc/v1.0.0
带文章的短路径 mliev/mdoc/v1.0.0/32
搜索 搜索 mliev/mdoc 如何安装
英文搜索 search mliev/mdoc authentication

使用示例

获取文档目录

/mdoc mliev/mdoc

输出示例：

📄 mdoc  [版本: master]

  [32] 介绍
  [103] 快速开始
    [109] 注册与登录
    [110] 创建组织与文档
    [111] 编写与发布文章
  [104] 用户指南
    ...

读取指定文章

/mdoc https://mdoc.cc/mliev/mdoc/v1.0.0/32

输出：直接展示该文章的 Markdown 原文。

语义搜索

/mdoc 搜索 mliev/mdoc 版本控制

输出示例：

🔍 搜索结果（共 3 条，关键词："版本控制"）

  [113] 版本控制 (相似度: 0.95)
    M-Doc 采用类 Git 的版本控制模型...

  [134] 版本模型详解 (相似度: 0.82)
    版本是文档内容的独立快照...

创建文章

在对话中使用自然语言指令：

请在 mliev/mdoc 的 v1.0.0 版本下创建一篇标题为"部署最佳实践"的文章，内容为...

更新文章

请更新 mliev/mdoc 中文章 32 的内容，将标题改为"产品介绍"

发布文章

请发布 mliev/mdoc 中的文章 32，提交信息为"更新产品介绍"

自然语言触发

除了使用 /mdoc 命令外，以下自然语言也会自动触发技能：

  • 粘贴 https://mdoc.cc/… 格式的 URL
  • 说出"列出文档"、"读取文章"、"获取目录清单"
  • 说出"搜索文章"、"语义搜索"
  • 说出"创建文章"、"更新文章"、"删除文章"、"发布文章"、"合并文章"
  • 说出"调用 mdoc api"

与 MCP Server 的区别

M-Doc 同时提供 MCP Server 集成 和 Skills 两种 AI 接入方式：

特性 MCP Server Skills
适用工具 所有支持 MCP 协议的工具 所有支持 Skill 协议的工具
安装方式 编辑 JSON 配置文件 一行命令或 git clone
交互方式 通过 MCP 协议调用工具函数 自然语言触发，自动解析 URL
写操作支持 需手动调用 API 支持自然语言指令
搜索支持 支持 支持
运行依赖 需要 npx 运行 MCP Server 无额外依赖

建议：如果你的工具支持 Skill，推荐使用 Skills 方式，安装更便捷，交互更自然。如果你的工具仅支持 MCP 协议，请参考 MCP Server 集成 文档。两者也可以同时使用。

权限要求

操作 所需权限
获取目录 / 读取文章 / 搜索 read:articles
创建 / 更新 / 删除 / 发布 / 合并文章 write:articles

常见问题

安装后技能未生效

确认已正确导出 MDOC_TOKEN 环境变量，可以在终端中执行：

echo $MDOC_TOKEN

如果输出为空，请重新设置令牌并重启你的 AI 工具。

提示"TOKEN 未设置"

技能运行时会自动检查 MDOC_TOKEN。如果未设置，会显示配置引导。按照提示操作即可。

写操作返回 403

请确认你的 PAT 令牌具有 write:articles 权限。可以在 https://mdoc.cc/settings 的个人令牌页面检查和更新权限。

Skill 仓库地址

Skills 源码托管在：https://cnb.cool/mliev/mdoc/mdoc-skills