vault-skill-factory

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

.agents/skills/claude-history-ingest

.agents/skills/code-understand

.agents/skills/codex-history-ingest

.agents/skills/copilot-history-ingest

.agents/skills/cross-linker

Audit 0.4.1 · source sha 8bcf57f68146 · 31 Oct 2026Report an issue or request a re-scan

• Publisherar9av GitHub userOwner of the repository this skill is read from
• Source folderar9av/obsidian-wiki/.skills/vault-skill-factoryThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict8bcf57f68146A new audit runs when the source changes
• Repository statusNot archivedLast push 4 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Create a reviewable Agent Skill package from mature curated wiki pages. Use when turning verified vault knowledge into a reusable skill. Reads the vault and writes only to a review directory; it does not install skills.

---
name: vault-skill-factory
description: >
  Create a reviewable Agent Skill package from mature curated wiki pages. Use when turning verified vault knowledge into a reusable skill. Reads the vault and writes only to a review directory; it does not install skills.
---

# 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.

## 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.

## Before You Start

1. **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.
2. Read `index.md` to understand what the vault holds.

## Step 1: Choose the cluster

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

1. **Seed** from the user's intent (a topic, tag, project, or a named page).
2. **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).
3. **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.
4. **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.

## Step 2: Design the skill

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.

## Step 3: Write the skill to the review dir

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.

## Step 4: Optionally lean on skill-creator

`skill-creator` ships reusable scripts. Their path differs between a pip/uv install and a source
checkout, so check both layouts under `$OBSIDIAN_WIKI_REPO` and use the first that exists:

- `$OBSIDIAN_WIKI_REPO/skills/skill-creator/scripts/` — packaged install (`OBSIDIAN_WIKI_REPO` points
  at the bundled `_data/` dir, which ships the skills under `skills/`).
- `$OBSIDIAN_WIKI_REPO/.skills/skill-creator/scripts/` — source checkout.

Whichever resolves, it holds:

- `improve_description.py` — tighten the generated `description`

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-31
   !CAUTION B 89 / 100

   first audit · source 8bcf57f68146

Questions about vault-skill-factory

• github.com/ar9av/obsidian-wiki/tree/main/.skills/vault-skill-fac — the audited source at commit 8bcf57f68146 and every finding aboveObserved · 31 Oct 2026

Spotted something wrong? Report a correction · Methodology