vault-skill-factory

Vault Skill Factory

将一组成熟且经过策选的 Wiki 页面转化为可移植的 Agent Skill：一个 SKILL.md 和一个 references/ 文件夹，写入供人工检查的审核目录，只有在人工选择安装时才安装。它与 wiki-capture 的方向相反：capture 将对话转成页面；factory 则将一组页面转成可复用的技能。

严格防护措施（请先阅读）

• 绝不要写入 .skills/，也绝不要运行 setup.sh，或在任何全局技能目录（~/.claude/skills、~/.codex/skills……）中创建符号链接。生成的技能只能写入审核目录。是否安装应由人工另行明确决定。
• 绝不自动安装。 结束时告知用户技能所在位置，以及他们若愿意，如何在项目本地安装——不要代替他们安装。
• 源页面是可信的 Vault 内容，但不要凭空编造能力：生成的技能必须如实反映页面内容。

开始之前

1. 解析配置（参见 llm-wiki/SKILL.md 中的 Config Resolution Protocol）：获取 OBSIDIAN_VAULT_PATH、 OBSIDIAN_WIKI_REPO、OBSIDIAN_LINK_FORMAT、QMD 变量，以及：
   • SKILL_FACTORY_OUTPUT_DIR — 生成的技能存放位置。默认值： $OBSIDIAN_VAULT_PATH/_generated-skills（Vault 级别、以下划线开头的排除目录， 类似 _raw/_staging/_sources，而不是 skills/ 知识分类）。这会将生成的技能与提炼来源所在的 Vault 放在一起。若目录不存在，则创建。 注意：_generated-skills/ 存放运行时 Agent-Skill 包（带有 name 和 description frontmatter）， 不是 Wiki 页面——绝不要将它们写入 skills/（该分类用于知识页面，并受图谱、lint 和索引追踪）。
   • SKILL_FACTORY_MATURITY — 以逗号分隔的 lifecycle: 值列表，用于判定页面是否“成熟”。 默认值：reviewed,verified。tier: core 的页面也符合条件。
2. 阅读 index.md，了解 Vault 中包含的内容。

第 1 步：选择页面集群

确定哪些页面将构成技能。用户可能会指定主题、标签或项目；否则，先提出候选项。

1. 根据用户意图（主题、标签、项目或指定页面）选取种子页面。
2. 扩展页面集群：
   • 如果已配置 QMD（QMD_WIKI_COLLECTION），运行 qmd query "<topic>" -c "$QMD_WIKI_COLLECTION" --files （或 vsearch），收集语义相关的页面——这是查找完整集群的预期方式，而不只是匹配完全相同标签的页面。
   • 否则，按标签和 Wiki 链接邻域（从种子页面链接到的页面）使用 Grep/Glob 搜索。
3. 按成熟度筛选：保留 lifecycle: 属于 SKILL_FACTORY_MATURITY 或 tier: 为 core 的页面。除非用户明确要求纳入，否则剔除 draft 页面。
4. 向用户确认页面集群（列出页面名称和数量），然后再生成。如果符合条件的成熟页面少于约 3 篇，请说明情况——仅凭一篇内容单薄的页面不值得制作技能；可询问用户是否仍要继续或扩大搜索范围。

第 2 步：设计技能

根据页面集群确定：

• name — 由集群主题衍生的 kebab-case 名称（例如 french-theory-expert、 peptide-protocols）。不得与 .skills/ 中的现有技能冲突。
• description — 触发条件。按照 skill-creator 的要求，措辞要有推动性：说明何时使用（列出用户可能采用的各种表达方式），以及它的作用。该字段决定技能是否会被触发。
• 推理方法 — Agent 应如何运用这些知识：它要回答哪些问题、采用什么方法、遵守哪些注意事项。应从页面综合内容中提炼，而非直接复制粘贴。
• 深度材料 — 确定哪些页面正文将成为 references/ 文件。

第 3 步：将技能写入 review 目录

创建 $SKILL_FACTORY_OUTPUT_DIR/<name>/，并包含：

<name>/
├── SKILL.md            # frontmatter (name + pushy description) + reasoning approach + key knowledge
├── references/         # depth material distilled from the cluster
│   ├── <topic>.md      # one per sub-theme; declarative knowledge, not chat
│   └── sources.md      # provenance: which vault pages this was built from (+ their sources)
└── SKILL_FACTORY.md    # provenance manifest (see below) — NOT part of the installed skill

SKILL.md 正文应精简（包含触发逻辑和简洁的推理指南），将深入内容放入 references/。遵循此仓库中现有技能的结构。沿用不确定的说法时，保留 ^[inferred] / ^[ambiguous] 标记——生成的技能不得将综合推断伪装成事实。

references/sources.md 列出用到的每个知识库页面（使用 [[wikilink]]）及其上游 sources:，以便追溯技能与知识库及原始来源。

SKILL_FACTORY.md（工厂元数据，不包含在可安装技能中）记录：生成日期、集群页面及其生命周期／层级、使用的成熟度筛选条件，以及可用的知识库提交版本／哈希。这样，再生成更新的工作流日后就能进行差异比较。

可选，按用户要求：在输出目录中追加／更新 marketplace.json 条目（OpenKB 单行安装约定）——这仍然不是安装，只是清单。

第 4 步：可选地借助 skill-creator

skill-creator 提供可复用脚本。其路径在 pip／uv 安装和源码检出时有所不同，因此请在 $OBSIDIAN_WIKI_REPO 下检查这两种目录结构，并使用第一个存在的路径：

• $OBSIDIAN_WIKI_REPO/skills/skill-creator/scripts/ — 打包安装版（OBSIDIAN_WIKI_REPO 指向随附的 _data/ 目录，其中的 skills/ 下包含技能）。
• $OBSIDIAN_WIKI_REPO/.skills/skill-creator/scripts/ — 源码检出版。

无论解析到哪个路径，其中都包含：

• improve_description.py — 优化生成的 description，以改善触发效果。
• package_skill.py — 将技能目录打包为可分发的归档文件。
• quick_validate.py — 检查技能结构是否正常。

用户需要完善／验证后的成品时，请使用这些脚本；不要另行实现。

第 5 步：报告，然后停止

告知用户：

• 路径：$SKILL_FACTORY_OUTPUT_DIR/<name>/
• 构建所依据的集群（页面数量 + 名称）
• 触发用的 description
• 如需安装，如何安装（由用户决定，且仅限项目本地）：

  ln -s ../../.skills/<name> <repo>/.claude/skills/<name>   # after copying <name>/ into .skills/, sans SKILL_FACTORY.md
  

  明确说明：先审核；不要运行 setup.sh（它会将技能分发到全局目录）；未经明确同意，绝不可全局安装。

不要自行安装。不要写入 .skills/。完成。

质量检查清单

• 输出写入 $SKILL_FACTORY_OUTPUT_DIR，绝不写入 .skills/ 或全局目录
• 已与用户确认集群；仅使用成熟页面（依据 SKILL_FACTORY_MATURITY／tier: core）
• description 明确且准确（何时触发 + 做什么）
• SKILL.md 正文精简；深入内容放在 references/
• 保留 ^[inferred]／^[ambiguous] 标记；不将综合推断伪装成事实
• references/sources.md 可追溯至知识库页面及其来源
• 存在 SKILL_FACTORY.md 来源清单（不包含在可安装技能中）
• 报告中说明路径和仅限项目本地的手动安装步骤；未自动安装任何内容