WIHATN/vault-crystallize

Vault Crystallize

This skill is the behavior authority for crystallize and distill in a knowledge vault. Vault protocols are data contracts:

• AGENTS.md defines workspace boundaries, startup tiers, and write ownership.
• global/agent-rules/handoff-protocol.md defines the Handoff.md format.
• global/agent-rules/llm-wiki-protocol.md defines llm-wiki/ page schema, evidence, contradictions, integration, and health checks.
• global/agent-rules/llm-wiki-format.md defines page templates when present.

Do not look for a ## Crystallize section in the protocol. If one exists in an old vault, prefer this skill for behavior and use the protocol only for data contracts.

Boundary

Dedicated triggers:

• 结晶, 结晶一下, crystallize -> checkpoint recovery state and stable long-term knowledge only when they changed.
• 蒸馏, distill -> turn a concrete source into cited, confidence-rated evidence entries.

Do not use this skill for neat-freak, deep audits, broad doc cleanup, memory sync, or a polished "结晶版" summary unless the user explicitly asks for that separate task. Bare 收尾, "wrap up", "整理一下", and "sync my notes" are not crystallize triggers.

Agents that have not installed this skill are an installation/update concern, not a reason to duplicate crystallize behavior back into vault protocols. Do not create .claude/skills, .agents/skills, junctions, or per-agent install paths unless the user explicitly asks for installation work.

Native command wrappers live in commands/ and commands/<agent>/. Shared ordinary alias skills live under skills/; do not add duplicate alias SKILL.md files under platform-specific directories because Codex may recursively discover them twice. Treat all of them as explicit invocation adapters; keep SKILL.md as the behavior authority when updating them.

Language Defaults

Write Handoff.md and llm-wiki/ content in Chinese by default. Keep stable technical identifiers in English, including code, commands, variable names, paths, API names, package names, and source titles when preserving the original title matters.

Use another language only when the user explicitly asks for it, when quoting source material, or when an existing project rule is more specific for that unit.

Command: crystallize

1. Identify the current unit:
   • Work under projects/<name>/ -> that project.
   • Work under research/<name>/ -> that research domain, unless a submodule has its own Handoff.md.
   • Vault governance or cross-vault rules -> root Handoff.md and global/llm-wiki/.
2. Read the current unit Handoff.md before claiming current project state. If the unit is unclear, read root Handoff.md as the active-project index; if still unclear, ask one concise question.
3. Decide whether anything actually changed:
   • Recovery point changed -> update the current unit Handoff.md.
   • Stable conclusion another thread should know long-term -> update the matching existing llm-wiki/ page.
   • No recovery or long-term change -> write nothing and say why.
4. Route each stable conclusion by reuse scope before writing:
   • Ask: would this conclusion stay true and useful in a different project doing a similar task tomorrow? Yes -> write the general fact to the matching global/llm-wiki/<topic>.md page and keep only project-specific application details plus a wikilink pointer in the project wiki. Unsure -> keep it project-level (default down).
   • Rule of two: if this session used or rewrote a conclusion that lives in another project's wiki, promote it to a global topic page now.
   • Read before write: read the target topic page first and merge into an existing same-subject entry when one exists; never blind-append. Create a new topic page only when no existing topic fits, and update ## Triggers in global/llm-wiki/index.md in the same pass.
5. Write only the right layer:
   • Handoff.md gets current status, active files, open questions, next actions, and resume context.
   • llm-wiki/ gets stable decisions, methods, pitfalls, memory, entity/concept, or evidence entries.
   • log.md is only for genuinely major knowledge operations, not routine crystallize.
   • Tool-private memory, process replay, and agent caches never become vault authority.
6. If Handoff.md has ## Tracks, sweep all live tracks before finalizing. Preserve non-focus tracks unless the work explicitly closed them.
7. Run the review checklist below before reporting completion.

Command: distill

Use only when the user explicitly says distill, 蒸馏, or asks to turn a concrete source into traced evidence.

Inputs:

• Source: a file path, pasted text, fetched URL content, note, PDF, or conversation excerpt.
• Target unit: infer from source path or current task; if ambiguous, ask one concise question.
• Destination: target unit llm-wiki/evidence-log.md.

Workflow:

1. Read the target unit Handoff.md.
2. Read global/agent-rules/llm-wiki-protocol.md sections ## Evidence Log and ## Pending Contradictions.
3. Split the source into numbered blocks B1, B2, B3, ... in source order. Keep raw long sources in sources/ or notes/; put only pointers and concise evidence in llm-wiki/.
4. Separate evidence from inference. Evidence claims cite (src: Bn). Inferences name the source blocks they depend on.
5. Assign confidence per conclusion: high, medium, low, or unverified.
6. If new evidence contradicts existing llm-wiki/, follow ## Pending Contradictions; do not silently overwrite.

Evidence entry shape:

### YYYY-MM-DD · <source title>
- **来源：** [[relative/source-or-note]]
- **原文块：**
  - B1: <short source locator or excerpt summary>
  - B2: <short source locator or excerpt summary>
- **证据结论：**
  - <claim> (src: B1) - confidence: <high|medium|low|unverified>
- **推断：**
  - <inference> (from: B1+B2) - confidence: <high|medium|low|unverified>
- **待验证：** <specific verification need, or `无`>

Review Checklist

Handoff review:

• Exactly the required sections from handoff-protocol.md; ## Tracks is optional only for parallel live tracks.
• If ## Tracks exists, exactly one track has [focus].
• ## Last Done has at most 4 entries, reverse chronological, each ending with a date.
• ## Next Actions has at most 3 concrete checkbox items.
• ## Active Files explains why each file is active now, not what the file is.
• ## Decisions contains a wikilink to [[llm-wiki/decisions]] or a decision block ID, or says None.
• ## Resume tells the next agent what to read and what mental model to keep.

LLM wiki review:

• New or significantly changed pages have frontmatter required by llm-wiki-protocol.md.
• The page type matches the content: decision, method, pitfall, memory, evidence, entity, concept, glossary, or operation log.
• New pages are linked from the local llm-wiki/index.md.
• Claims have confidence; evidence claims point to sources.
• Unresolved contradictions are recorded in the designated place instead of hidden.
• Cross-project reusable conclusions are routed to global/llm-wiki/ topic pages; no fact is duplicated across layers (project keeps application details plus a pointer).
• Entry headings and field sets match the llm-wiki-format.md template for the page type: claim pages (method / pitfall / topic) key by stable subject name, event pages (decisions / evidence / log) key by date.
• No aliased wikilinks appear inside Markdown tables.

Behavior review:

• Do not run or invoke neat-freak unless explicitly requested.
• Do not broaden into doc cleanup, memory sync, or formatting churn.
• Do not manage agent-local skill installation unless explicitly requested.
• Do not write if nothing changed; reporting "nothing changed" is a valid outcome.

Validation

When files were created, moved, renamed, or the user is switching threads/agents, run the read-only health suite from the vault root:

pwsh -NoProfile -File global/tools/vault-health.ps1
pwsh -NoProfile -File global/tools/vault-meta.ps1 -Audit
pwsh -NoProfile -File global/tools/vault-links.ps1

For content-only edits, run the smallest relevant check and report what was skipped.

Common Failure Modes

Failure	Correction
"Other agents without the skill will not crystallize."	Install/update distribution solves that. Do not duplicate behavior into protocols.
Reads llm-wiki-protocol.md ## Crystallize.	Stop; this skill owns crystallize behavior. Protocols define formats and health checks only.
Treats 收尾 or "cleanup docs" as crystallize.	Do not trigger unless dedicated words or explicit evidence intent appear.
Writes process logs to llm-wiki/.	Only stable conclusions belong there.
Appends to stale Handoff lists.	Rewrite sliding windows within the documented caps.
Appends a new dated entry to a claim page (methods / pitfalls / topic) instead of merging.	Claim pages key by subject: locate the existing entry, rewrite it in place, bump updated / 验证于.