如何在 Claude Code 与其他 AI Agent 中启用 Quarkdown 内置的 agent skill-育师

如何在 Claude Code 与其他 AI Agent 中启用 Quarkdown 内置的 agent skill

【免费下载链接】quarkdown🪐 Markdown with superpowers: from ideas to papers, presentations, websites, books, and knowledge bases.项目地址: https://gitcode.com/GitHub_Trending/qu/quarkdown

Quarkdown 随安装包附带了一个 agent skill，以及一份完整的离线 wiki 和 stdlib API 参考副本，目的是让 AI Agent 在生成.qd文档前先查阅官方文档，而不是凭空猜测语法。这篇文章的任务就是把这个 skill 接入你的 AI 编码工具：Claude Code 用一条软链接命令即可启用，ChatGPT 等其他 Agent 则通过上传或指向SKILL.md文件接入。前提是你已经安装了 Quarkdown CLI（即quarkdown命令可用），因为 skill 的位置需要通过 CLI 的doctor get命令解析。

先确认 skill 的安装位置

skill 随 Quarkdown 一起分发，quarkdown doctor get agent-skill会打印它的绝对路径。这个get子命令的输出是一行一个值，专门用于 shell 替换（见 CLI - Doctor）。运行：

quarkdown doctor get agent-skill

命令输出了形如绝对路径的一行内容，说明 CLI 正常工作，后续步骤都可以依赖它。该目录下包含一个SKILL.md入口文件，AI Agent 工具可以读取或软链接它。在仓库中可以直接对照 skills/quarkdown/SKILL.md 查看这个入口文件的实际内容。

在 Claude Code 中启用

把打包好的 skill 目录软链接到 Claude 的 skills 目录：

ln -s "$(quarkdown doctor get agent-skill)" ~/.claude/skills/quarkdown

这条命令用ln -s在~/.claude/skills/下创建一个名为quarkdown的符号链接，指向quarkdown doctor get agent-skill解析出的目录；它只在你的用户目录新增一个链接，不修改 Quarkdown 安装内容。

链接创建后，重启 Claude 会话让 skill 被加载。

验证 skill 是否生效

skill 的激活条件是：你让 Claude 去写或编辑一个.qd文件。给 Claude 一个明确的任务（例如"把这个 Markdown 改写成.qd文档"），skill 应自动接管。如果 skill 没有自动触发，可以手动调用/quarkdown来触发它。

在 ChatGPT 与其他 Agent 中启用

对 Claude Code 之外的 Agent，接入方式是上传SKILL.md文件，或让 Agent 直接指向该文件。先用下面的命令拿到它的完整路径：

echo "$(quarkdown doctor get agent-skill)/SKILL.md"

然后把输出的这个文件上传给你的 Agent（或让它读取该路径）。SKILL.md带有 frontmatter，name: quarkdown，描述中写明了适用场景：编写或编辑.qd文件、生成 HTML/PDF/纯文本等排版输出。文件中还包含使用边界：当最终目标就是纯 Markdown（聊天、README、GitHub issue）时，不应使用这个 skill。

skill 驱动 Agent 的实际工作流程

启用后，Agent 并不是自由发挥，而是按 SKILL.md 中定义的流程工作。理解这个流程有助于你核对 Agent 的行为是否符合预期：

定位安装目录。Agent 应运行一次：
```
QUARKDOWN_INSTALL="$(quarkdown doctor get install-dir)"
```
quarkdown doctor get install-dir打印包含bin/、lib/、docs/的发行版根目录（见 CLI - Doctor）。
阅读内置文档。安装目录下的docs/wiki/_nav.qd是 wiki 索引，docs/wiki/quickstart.qd是新用户的入口；需要精确的函数签名时查docs/quarkdown-stdlib/下的 stdlib API 参考（HTML 格式）。skill 要求 Agent 在写非平凡内容前先读相关 wiki 页。
新建项目。如果用户想从零开始一个 Quarkdown 项目，skill 要求 Agent 让用户自己运行quarkdown create [dir]（交互式向导），而不是手工搭建项目文件。
写文件并编译验证。Agent 写完.qd文件后要执行：
```
quarkdown c <main>.qd --strict --out /tmp/quarkdown-verify
```
其中<main>通常是main.qd，但 Agent 应结合你的项目确认。--strict让编译器在出错时退出（非严格模式下错误只是以框的形式显示在文档里）；--out /tmp/quarkdown-verify把产物写到临时目录，避免污染你的项目（默认输出目录是 CWD 下的./quarkdown-output）。这些参数均可在 CLI - Options 中查到。
报告编译错误。skill 的最后一步是把编译报错原样反馈给你。

两条 skill 明确禁止的行为值得留意：--pdf会启动无头浏览器、速度较慢，只在用户明确要 PDF 时使用；live preview（-p、-w）是长驻 web server，Agent 只应把命令建议给你，而不是自己运行（选项含义见 CLI - Options）。

常见问题与限制

skill 没有自动激活：用/quarkdown手动触发；确认软链接存在且目标目录非空（quarkdown doctor get agent-skill应能输出路径）。
quarkdown doctor get agent-skill无输出或命令不存在：说明 Quarkdown CLI 本身不可用，需要先完成 CLI 安装；本 skill 的所有步骤都依赖quarkdown命令在 PATH 中。
适用边界：该 skill 面向.qd文档的编写与编辑。若你的产出物只是纯 Markdown，skill 自身声明此时不应使用。

skill 的完整说明见 Use with AI agents。启用完成后，日常用法就是直接向 Agent 提"写/改一个.qd文件"类的需求，并核对它是否走了"读内置文档 → 写文件 →--strict编译验证 → 报错反馈"这条链路。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考