Zettel Builder — AI skill for Claude Code

zettel-builder

一个自底向上生长的 Zettelkasten 卡片笔记系统：素材进来就长卡，价值观重述、自动连边、周期性巡检文章就绪簇，缺口处可触发深度调研补卡。

**状态**：面向 AI agent harness（Claude Code / OpenClaw / Codex / Hermes）的 Skill。已脱敏发布——原版围绕个人写作风格构建，这里把写作风格那部分替换成了可填写的模板。

---

它解决什么问题

写作素材越积越多，但真要写时却找不到该用哪些。常见做法是攒一堆"碎念笔记"，可是这些笔记彼此孤立，不会自己长成文章。

zettel-builder 把"素材消化"这一步流程化：

• 每段素材切成多张原子卡（一卡一判断，半年后脱离上下文也能读懂）
• 每张卡末段必须做价值观重述（我同意/不同意/部分同意 + 边界），不是改写文风，是产生新判断
• 嵌入只做语义召回，agent 必须读全文判定是否真连/真同（不基于相似度阈值自动跳过）
• 周期巡检卡池，发现"文章就绪簇"（密度够 + 视角配齐 + 没被过去文章覆盖）就发 Telegram 提醒
• 簇拼成大纲后移交给你自己的写作 Skill 出稿

文章不会"自己长出来"——它是从已有方向上的稠密簇中浮现的。这个 skill 帮你更高效地组织既定方向的材料，但不替你决定写什么。

四种调用模式

模式	触发	做什么
ingest	/zettel ingest <来源>	把素材切原子卡 → 价值观重述 → 候选链接
scan	/zettel scan	消化 _queue/ 里积累的待办素材
inspect	/zettel inspect	巡检卡池找就绪簇 / 孤儿卡 / 缺口
write	/zettel write	把指定簇拼成大纲移交写作 Skill 出稿

安装

方式 A — 把仓库交给你自己的 AI agent

请安装这个 Skill。先判断我当前使用的是 OpenClaw、Claude Code、Codex 还是 Hermes（优先按这个匹配顺序）。根据本机已有 Skill 目录、同步链或 agent 配置完成安装，并在安装后验证 `zettel-builder` 能被当前环境发现和调用。不要改写 Skill 内容；只有在适配本机外部服务路径或账号能力时，才做必要的本机配置说明。

方式 B — 手动安装（Claude Code 示例）

git clone https://github.com/wshuyi/zettel-builder.git ~/.claude/skills/zettel-builder

OpenClaw / Hermes / Codex 则放到对应 harness 的 skill 搜索根目录下后 reload。

使用前准备

zettel-builder 是"调度型"Skill，本身不写文章，依赖几个外部能力。请按需准备：

1. **你的写作风格快照**（必填） 首次启用前，请打开 `references/voice-snapshot.md`（包内有模板），填入你自己的核心价值观（3-7 条）和文风硬规则。Mode 1 价值观重述会读它，没填则重述会滑回 "客观介绍"。

2. **你的写作 Skill**（可选） Mode 4 / Mode 5 把就绪簇或命题草稿移交给你自己的写作 Skill 出稿。没有的话也能用——卡片照样长，只是出稿那步要手动接管。

3. **素材源**（可选） 默认在 `~/wiki/published-articles/raw/{articles,getnote}/` 找上游素材。可以是已发表文章、笔记导出、Readwise 高亮、知识库快照等任何 Markdown。没有上游也能用 Mode 1 单次喂料。

4. **深度调研 Skill**（可选） Mode 4 检测到簇有 evidence_gap 时可调 `/deep-research`。没有就跳过 gap 提示。

5. **OpenClaw 调度**（可选） 包内 `references/openclaw-cron.md` 说明了 daily-scan + weekly-inspect 的 cron 配置。也可以纯手动 `/zettel scan`、`/zettel inspect`。

6. **嵌入模型**（自动） 默认走 `fastemb