vault-skill-factory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vault Skill Factory

You turn a cluster of mature, curated wiki pages into a portable Agent Skill: a

SKILL.md

plus a

references/

folder, written to a review directory for the human to inspect and (only if they choose) install. This is the inverse of

wiki-capture

: capture turns a conversation into a page; the factory turns a body of pages into a reusable skill.

你可以将一组成熟、经过整理的wiki页面转化为可移植的Agent Skill：一个

SKILL.md

文件加上一个

references/

文件夹，会写入审查目录供人工检查，并且（仅当用户选择时）进行安装。这与

wiki-capture

功能相反：capture是将对话转化为页面；而本工厂则是将一组页面转化为可复用的技能。

Hard guardrails (read first)

严格约束（请先阅读）

Never write into
.skills/
and never run
setup.sh
or create symlinks into any global skill directory (
```
~/.claude/skills
```
,
```
~/.codex/skills
```
, …). Generated skills go to the review dir only. Installation is a separate, explicit human decision.
Never auto-install. End by telling the user where the skill is and how to install it project-locally if they want — do not do it for them.
Source pages are trusted vault content, but do not invent capabilities: the generated skill must reflect what the pages actually say.

绝不要写入
.skills/
目录，也**绝不要运行
```
setup.sh
```
**或创建指向任何全局技能目录（
```
~/.claude/skills
```
、
```
~/.codex/skills
```
……）的符号链接。生成的技能仅能存入审查目录。安装是一个独立、需明确人工确认的操作。
绝不要自动安装。结束时告知用户技能的存放位置，以及如果他们想要的话如何在项目本地安装——不要替他们执行安装操作。
源页面是受信任的知识库内容，但不要凭空创造功能：生成的技能必须如实反映页面中的实际内容。

Before You Start

开始之前

Resolve config (Config Resolution Protocol in
```
llm-wiki/SKILL.md
```
): get
```
OBSIDIAN_VAULT_PATH
```
,
```
OBSIDIAN_WIKI_REPO
```
,
```
OBSIDIAN_LINK_FORMAT
```
, the QMD vars, and:
- ```
SKILL_FACTORY_OUTPUT_DIR
```
  — where generated skills land. Default:
```
$OBSIDIAN_VAULT_PATH/_generated-skills
```
  (a vault-level, underscore-prefixed excluded dir — like
```
_raw
```
  /
```
_staging
```
  /
```
_sources
```
  , NOT the
```
skills/
```
  knowledge category). This co-locates generated skills with the vault they were distilled from. Create it if missing. Note:
```
_generated-skills/
```
  holds runtime Agent-Skill bundles (
```
name
```
  +
```
description
```
  frontmatter), not wiki pages — never write them into
```
skills/
```
  (that category is for knowledge pages and is graph-/lint-/index-tracked).
- ```
SKILL_FACTORY_MATURITY
```
  — comma list of
```
lifecycle:
```
  values that count as "mature". Default:
```
reviewed,verified
```
  . Pages with
```
tier: core
```
  also qualify.
Read
```
index.md
```
to understand what the vault holds.

解析配置（参考
```
llm-wiki/SKILL.md
```
中的配置解析协议）：获取
```
OBSIDIAN_VAULT_PATH
```
、
```
OBSIDIAN_WIKI_REPO
```
、
```
OBSIDIAN_LINK_FORMAT
```
、QMD变量，以及：
- ```
SKILL_FACTORY_OUTPUT_DIR
```
  ——生成的技能存放路径。默认值：
```
$OBSIDIAN_VAULT_PATH/_generated-skills
```
  （一个位于知识库根目录、以下划线开头的被排除目录——类似
```
_raw
```
  /
```
_staging
```
  /
```
_sources
```
  ，而非
```
skills/
```
  知识分类目录）。这样可以将生成的技能与提炼它们的知识库放在一起。如果目录不存在则创建。注意：
```
_generated-skills/
```
  目录存放运行时Agent-Skill包（包含
```
name
```
  和
```
description
```
  前置元数据），而非wiki页面——绝不要将它们写入
```
skills/
```
  目录（该分类目录用于存放知识页面，并且会被图谱/语法检查/索引跟踪）。
- ```
SKILL_FACTORY_MATURITY
```
  ——逗号分隔的
```
lifecycle:
```
  值列表，符合这些值的页面被视为“成熟”。默认值：
```
reviewed,verified
```
  。带有
```
tier: core
```
  标记的页面也符合条件。
阅读
```
index.md
```
以了解知识库包含的内容。

Step 1: Choose the cluster

步骤1：选择页面组

Decide which pages become the skill. The user may name a topic, tag, or project; otherwise propose candidates.

Seed from the user's intent (a topic, tag, project, or a named page).
Expand the cluster:
- If QMD is configured (
```
QMD_WIKI_COLLECTION
```
  ), run
```
qmd query "<topic>" -c "$QMD_WIKI_COLLECTION" --files
```
  (or
```
vsearch
```
  ) to gather semantically related pages — this is the intended way to find the full cluster, not just exact-tag matches.
- Otherwise
```
Grep
```
  /
```
Glob
```
  by tag and wikilink-neighbourhood (pages linked from the seed pages).
Filter by maturity: keep pages whose
```
lifecycle:
```
is in
```
SKILL_FACTORY_MATURITY
```
or whose
```
tier:
```
is
```
core
```
. Drop
```
draft
```
pages unless the user explicitly includes them.
Confirm the cluster with the user (list page names + count) before generating. If fewer than ~3 mature pages match, say so — a skill from one thin page isn't worth it; offer to proceed anyway or widen the net.

确定哪些页面会被转化为技能。用户可能会指定主题、标签或项目；否则请推荐候选页面。

根据用户意图确定起点（主题、标签、项目或指定页面）。
扩展页面组：
- 如果配置了QMD（
```
QMD_WIKI_COLLECTION
```
  ），运行
```
qmd query "<topic>" -c "$QMD_WIKI_COLLECTION" --files
```
  （或
```
vsearch
```
  ）来收集语义相关的页面——这是找到完整页面组的预期方式，而非仅匹配精确标签。
- 否则使用
```
Grep
```
  /
```
Glob
```
  按标签和维基链接邻域（从起点页面链接的页面）筛选。
按成熟度筛选：保留
```
lifecycle:
```
值在
```
SKILL_FACTORY_MATURITY
```
列表中或带有
```
tier: core
```
标记的页面。除非用户明确要求，否则排除
```
draft
```
页面。
与用户确认页面组（列出页面名称及数量）后再生成技能。如果匹配的成熟页面少于约3个，请告知用户——仅从一个单薄的页面生成技能并无太大价值；提供继续操作或扩大筛选范围的选项。

Step 2: Design the skill

步骤2：设计技能

From the cluster, decide:

name
— kebab-case, derived from the cluster's subject (e.g.
```
french-theory-expert
```
,
```
peptide-protocols
```
). Must not collide with an existing skill in
```
.skills/
```
.
description
— the trigger. Write it "pushy" (per
```
skill-creator
```
): state when to use it (all the phrasings a user might say) and what it does. This field is what makes the skill fire.
Reasoning approach — how an agent should use this knowledge: the questions it answers, the method it applies, the caveats it respects. Distil this from the pages' synthesis, not a copy-paste.
Depth material — which page bodies become
```
references/
```
files.

从页面组中确定：

name
——短横线分隔格式（kebab-case），由页面组的主题衍生而来（例如
```
french-theory-expert
```
、
```
peptide-protocols
```
）。不得与
```
.skills/
```
目录中已有的技能重名。
description
——触发词。按照
```
skill-creator
```
的要求写得“明确”：说明何时使用（用户可能会说的所有表述）以及功能是什么。这个字段是触发技能运行的关键。
推理方法——Agent应如何使用这些知识：它能回答的问题、应用的方法、需要注意的警告。从页面的综合内容中提炼，而非直接复制粘贴。
深度素材——哪些页面内容会成为
```
references/
```
目录下的文件。

Step 3: Write the skill to the review dir

步骤3：将技能写入审查目录

Create

$SKILL_FACTORY_OUTPUT_DIR/<name>/

with:

<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 body should be lean (the trigger logic + a compact reasoning guide), pushing depth into

references/

. Follow the structure of existing skills in this repo. Preserve

^[inferred]

^[ambiguous]

markers when carrying over uncertain claims — a generated skill must not launder synthesis into fact.

references/sources.md
lists every vault page used (by

[[wikilink]]

) and their upstream

sources:

— so the skill stays auditable back to the vault and original sources.

SKILL_FACTORY.md
(factory metadata, kept out of the installable skill) records: generation date, the cluster pages + their lifecycle/tier, the maturity filter used, and the vault commit/hash if available. This lets a regenerate-on-update workflow diff later.

Optional, if the user asks: append/update a

marketplace.json

entry in the output dir (the OpenKB one-line-install convention) — still not an install, just a manifest.

创建

$SKILL_FACTORY_OUTPUT_DIR/<name>/

目录，包含以下内容：

<name>/
├── SKILL.md            # 前置元数据（name + 明确的description）+ 推理方法 + 核心知识
├── references/         # 从页面组提炼的深度素材
│   ├── <topic>.md      # 每个子主题对应一个文件；陈述性知识，非对话内容
│   └── sources.md      # 来源记录：技能构建所使用的知识库页面（及其上游来源）
└── SKILL_FACTORY.md    # 来源清单（见下文）——不属于可安装的技能部分

SKILL.md主体内容应精简（包含触发逻辑 + 紧凑的推理指南），将深度内容放入

references/

目录。遵循本仓库中现有技能的结构。当引用不确定的内容时，保留

^[inferred]

^[ambiguous]

标记——生成的技能绝不能将综合内容伪装成事实。

references/sources.md

**列出所有使用的知识库页面（通过

[[wikilink]]

）及其上游

sources:

——这样技能可以追溯回知识库及原始来源，保持可审计性。

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

可选操作：如果用户要求，在输出目录中追加/更新

marketplace.json

条目（遵循OpenKB的一键安装约定）——这仍然不是安装操作，只是一个清单文件。

Step 4: Optionally lean on skill-creator

步骤4：可选借助skill-creator工具

skill-creator

ships reusable scripts (

$OBSIDIAN_WIKI_REPO/.skills/skill-creator/scripts/

```
improve_description.py
```
— tighten the generated
```
description
```
for better triggering.
```
package_skill.py
```
— bundle the skill dir into a distributable archive.
```
quick_validate.py
```
— sanity-check the skill's structure.

Use them when the user wants a polished/validated artifact; don't reinvent them.

skill-creator

提供了可复用的脚本（位于

$OBSIDIAN_WIKI_REPO/.skills/skill-creator/scripts/

）：

```
improve_description.py
```
——优化生成的
```
description
```
以提升触发效果。
```
package_skill.py
```
——将技能目录打包为可分发的归档文件。
```
quick_validate.py
```
——对技能结构进行合理性检查。

当用户需要一个经过打磨/验证的产物时使用这些脚本；不要重复造轮子。

Step 5: Report — and stop

步骤5：报告结果——并停止操作

Tell the user:

the path:
```
$SKILL_FACTORY_OUTPUT_DIR/<name>/
```
the cluster it was built from (page count + names)
the trigger
```
description
```
How to install if they want it (their decision, project-local only):
```
ln -s ../../.skills/<name> <repo>/.claude/skills/<name>   # after copying <name>/ into .skills/, sans SKILL_FACTORY.md
```
Note explicitly: review first; do not run
```
setup.sh
```
(it fans skills into global dirs); never global-install without explicit agreement.

Do not install it yourself. Do not write to

.skills/

. Done.

告知用户：

路径：
```
$SKILL_FACTORY_OUTPUT_DIR/<name>/
```
技能构建所基于的页面组（页面数量 + 名称）
触发用的
```
description
```
如果想要安装该技能的方法（由用户决定，仅在项目本地安装）：
```
ln -s ../../.skills/<name> <repo>/.claude/skills/<name>   # 将<name>/目录复制到.skills/目录后执行，需排除SKILL_FACTORY.md
```
明确注意：请先审查技能内容；不要运行
```
setup.sh
```
（它会将技能扩散到全局目录）；未经明确同意绝不要进行全局安装。

不要自行安装技能。不要写入

.skills/

目录。操作完成。

Quality checklist

质量检查清单

Output went to
```
$SKILL_FACTORY_OUTPUT_DIR
```
, never
```
.skills/
```
or a global dir
Cluster confirmed with the user; only mature pages (per
```
SKILL_FACTORY_MATURITY
```
/
```
tier: core
```
)
```
description
```
is pushy and accurate (when + what)
SKILL.md body is lean; depth lives in
```
references/
```
```
^[inferred]
```
/
```
^[ambiguous]
```
markers preserved; no synthesis laundered into fact
```
references/sources.md
```
traces back to vault pages + their sources
```
SKILL_FACTORY.md
```
provenance manifest present (excluded from the installable skill)
Report names the path and the manual, project-local-only install step; nothing auto-installed

输出内容存入
```
$SKILL_FACTORY_OUTPUT_DIR
```
，绝未存入
```
.skills/
```
或全局目录
页面组已与用户确认；仅包含成熟页面（符合
```
SKILL_FACTORY_MATURITY
```
/
```
tier: core
```
）
```
description
```
明确且准确（包含使用场景 + 功能）
SKILL.md主体内容精简；深度内容存于
```
references/
```
目录
保留了
```
^[inferred]
```
/
```
^[ambiguous]
```
标记；未将综合内容伪装成事实
```
references/sources.md
```
可追溯回知识库页面及其来源
存在
```
SKILL_FACTORY.md
```
来源清单（不包含在可安装技能中）
报告中说明了路径及手动、仅项目本地的安装步骤；未进行任何自动安装