前言¶

日常写技术笔记时，很多人会在 Obsidian、Logseq 等工具里维护卡片库，但在 Cursor、Claude Code 等 Agent 对话里，模型往往不知道你的库路径、标签约定和 zk 命令习惯，只能泛泛建议「建个 Markdown 文件」。若你已经在用或打算用 zk 这套命令行 Zettelkasten 工具，把笔记留在本地纯文本里，就需要一份写进 Agent 的 Skill，让助手按同一套工作流创建、搜索和编辑笔记。

下面介绍 SkillHub 上的社区 Skill zk（坐标 @user_f2c57d7a/zk）：它把 zk CLI 的用法、环境变量和常用命令整理成 Agent 可遵循的说明，无需 API Key。

这是什么¶

zk 在 SkillHub 的分类为 knowledge-management，当前版本 v1.0.1，来源为 community，发布者为 user_f2c57d7a。Skill 简介与底层工具一致：纯文本 Zettelkasten 笔记助手，用于创建、搜索和管理 Markdown 笔记，支持高级筛选、标签和维基链接。

Skill 本身不替代 zk 可执行文件。元数据标明依赖本机已安装 zk 命令，并建议使用环境变量 VAULT_PATH 指向笔记库目录；底层项目主页为 https://github.com/zk-org/zk。

核心功能¶

依据 Skill 包内 SKILL.md，Agent 被引导掌握的能力包括：

1. 笔记库生命周期：zk init 初始化笔记本；在 VAULT_PATH 或当前目录下用 zk list、zk new、zk edit 等操作。
2. 搜索与筛选：关键词（--match）、标签（--tag）、链接关系（--link、--linked-by）、排序（--sort）及交互式列表（--interactive）。
3. Markdown 约定：普通链接、Wikilinks（[[笔记名称]]）、多种标签写法，以及 YAML frontmatter（title、tags 等）。
4. 日常命令表：zk preview、zk mv、zk rm 等与 zk --help 对照使用。
5. 配置：笔记库内 .zk/config.toml（如默认编辑器、笔记格式等，以本机 zk 版本为准）。

Skill 标签为 requires_api_key=false，不依赖外部付费接口。

安装与启用¶

安装 SkillHub CLI（若尚未安装）¶

先检查是否已有 skillhub：

command -v skillhub && skillhub --version

未安装时，可按 SkillHub 官方说明执行完整安装（CLI + 默认 Skill）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

仅安装 CLI 时：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

安装 zk Skill¶

安装技能时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认装到 ./skills/ 可能不会被识别。SkillHub 页面给出的安装方式为：参照 https://skillhub.cn/install/skillhub.md，安装 @user_f2c57d7a/zk。

搜索结果显示的可执行形式为：

skillhub install zk --namespace user_f2c57d7a --dir <你的 Agent skills 目录>

常见路径示例（以 SkillHub 文档为准）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或项目下的 .agents/skills/

安装后按你所用客户端要求重启或刷新 Agent，使 Skill 生效。

安装底层 zk 命令行（Skill 依赖）¶

Skill 元数据要求本机存在 zk 二进制。若尚未安装，Skill 内文档提供例如：

macOS（Homebrew）：

brew install zk

Linux（tarball，Skill 内示例版本 v0.15.2）：

curl -L https://gh-proxy.org/https://github.com/zk-org/zk/releases/download/v0.15.2/zk-v0.15.2-linux-amd64.tar.gz | tar xz
sudo mv zk /usr/local/bin/

验证：

zk --version

建议为笔记库设置环境变量并在该目录下操作：

export VAULT_PATH="/path/to/your/vault"
cd "$VAULT_PATH"

典型用法¶

以下示例均来自 Skill 官方 SKILL.md，可在配置好 VAULT_PATH 后本地复现。

初始化并创建笔记：

zk init my-notes
cd my-notes
zk new --title "笔记标题"

在已有库中列出与按标签搜索：

cd "$VAULT_PATH"
zk list
zk list --tag mytag
zk list --match "关键词"

组合筛选与编辑：

cd "$VAULT_PATH"
zk list --tag project --match "设计"
zk edit <note-id>

高级匹配（排除词、时间范围、交互式编辑）：

zk list --match "pizza -pineapple"
zk list --tag recipe --created "7 days ago"
zk edit -i -m "recipe"

在 Agent 对话中，你可以用自然语言描述意图（例如「在 VAULT_PATH 里新建一条带 meeting 标签的会议纪要」），由已加载本 Skill 的模型给出与上述命令一致的操作步骤或直接建议在终端执行的命令。

适用场景与注意¶

适合谁：

• 已采用或计划采用 Zettelkasten / 个人维基，且希望笔记以 Markdown 文件留在本地、用 zk 管理。
• 希望在 Cursor、Claude Code 等环境里，让 Agent 与同一套 CLI、标签和 Wikilink 约定对齐，而不是每次重新解释工具链。

需要注意：

• Skill 是操作指南与约定，真正读写文件仍依赖本机安装的 zk 和用户指定的 VAULT_PATH；路径错误或未 cd 到库目录会导致 zk 找不到笔记本。
• SkillHub 抓取信息显示该 Skill 下载 592 次、评分 100000（平台计分方式以 SkillHub 为准）；安装 Skill 与安装 zk CLI 是两步，缺一不可。
• Linux 安装示例固定为 amd64 tarball 与特定版本号，其他架构或版本请查阅 https://github.com/zk-org/zk/releases。
• 配置文件能力以你本机 zk 版本为准，Skill 中的 config.toml 片段标注为「根据实际版本调整」。

结尾¶

zk Skill 把社区维护的 zk 命令行工作流封装成 Agent 可读的技能说明：纯文本 Markdown、标签、维基链接与高级列表筛选，无需 API Key。若你正在 SkillHub 上挑选知识管理类 Skill，可按官方坐标安装并在本机准备好 zk 与 VAULT_PATH。

• SkillHub 页面：https://www.skillhub.cn/skills/user_f2c57d7a/zk
• API 条目：https://api.skillhub.cn/user_f2c57d7a/zk
• 底层工具：https://github.com/zk-org/zk