vault-completion
Fill missing Obsidian vault notes from overview/MOC files with wikilinks, Mermaid diagrams, ASCII removal, cross-vault linking, and content migration from old stubs to new vaults.
- License 许可
- Unlicense
- 最近更新
- 2026-11-03
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- vault-completion
- description
- Fill missing Obsidian vault notes from overview/MOC files with wikilinks, Mermaid diagrams, ASCII removal, cross-vault linking, and content migration from old stubs to new vaults.
02 资源文件 3
- 脚本references/mermaid-verify.py2.3 KB
- 脚本scripts/fix-wikilinks.py4.6 KB
- 脚本scripts/tag-vault.py6.2 KB
03 SKILL.md 正文
Vault Completion
Complete workflow for filling Panomete's Obsidian vaults from overview files. Covers gap analysis, note format preferences, Mermaid diagram insertion, cross-vault linking, and content migration.
When to Use
- User has an Overview/MOC file with
[[wikilinks]]pointing to non-existent notes - "Fill in the missing notes", "Complete the vault", "Summarize X based on the overview"
- User has an old stub note that needs expanding into a full topic vault
- User wants Mermaid diagrams added to existing pattern/architecture notes
Core Workflow
- Read source material — reference document (SWEBOK chapter, book TOC, website)
- Read the Overview/MOC — identify dead
[[wikilinks]]vs existing files - Present gap analysis — table: Topic | In Overview? | Has Note? | Status
- Fill missing notes — synthesize from source + your knowledge. Priority: user-specified URL → provided reference → own knowledge
- Update Overview — add
[[wikilinks]]to plain-text headings - Verify — run verification script: file count, size >1KB, Sources present, Mermaid valid
Note Format
# Topic N: Title+ brief intro- Tables over prose for rules, comparisons, patterns
## When to Usewith categorized examples## Comparisonfor similar/confusable concepts (use ❌/✅ pairs)## Practical Applications— "Why This Matters in SE" or equivalent⚠️ Target-Audience Traps— dedicated error-pattern section if teaching specific audience (Thai speakers, etc.)## Quick Test— 5 questions with answers## Sources— cite reference material
Style Rules
- Tables > prose, bold keywords, scannable, practical not academic
- ❌/✅ pairs for immediate contrast
- Images:
from authoritative sources only — never fabricate URLs
Directory Structure
- Category folders with numbered prefixes:
01 Foundation/,02 Tenses & Time/ - Flat files inside — NOT folder-per-topic.
Topic Name.mdgoes directly in its category folder - Files numbered for teaching order:
01 Parts of Speech.md,02 Articles.md - For sub-topics needing individual files: subfolder with Overview index:
05 12 English Tense/containing05 12 English Tense Overview.md+05.1 Present Simple.mdthrough05.12 Future Perfect Continuous.md - Sub-topic folder pattern: when a topic naturally splits into many sub-topics (e.g., 12 tenses, 22 design patterns, 15 UX laws), create a numbered subfolder containing an overview index and individual numbered files. The folder replaces the single
.mdfile:05 12 English Tense/instead of05 12 English Tense.md. Individual sub-topic files use decimal numbering:05.1,05.2,05.12. - Overview file lives at vault root OR inside the topic folder (when there are many files)
Mermaid Diagrams
Obsidian renders Mermaid natively. Prefer over ASCII art for design patterns, architecture, flows.
When to Add Mermaid
- classDiagram — design patterns, OOP, architecture components
- sequenceDiagram — API flows, auth, Saga orchestration, event chains
- graph TD/LR — deployment pipelines, decision trees, protocol flows
- stateDiagram-v2 — circuit breaker, order lifecycle, auth states
GoF Design Pattern Conventions
- Interfaces:
<<interface>>, Abstract classes:<<abstract>> - Relationships:
..>(Dependency),-->(Association),o--(Aggregation),*--(Composition),..|>(Implementation),<|--(Inheritance) - Keep diagrams focused — pattern participants, not every method
ASCII Removal Workflow
- Add Mermaid alongside existing ASCII — don't delete ASCII yet
- Once all files have Mermaid, ASK before stripping ASCII
- Batch-remove with Python script using
patch()or direct file writes - Verify: no
┌└├┐┘┤─│┬┴┼chars remain - Re-verify: all files still have ````mermaid` blocks, no broken mermaid (plain text inside mermaid fence)
Mermaid Verification
Check all files:
- ````mermaid` present
- First line after fence is a valid diagram type
- No plain text accidentally pulled into mermaid block during edits
Cross-Vault Linking
When a topic spans vaults (programming-note stubs ↔ software-engineering-note deep content):
- Identify overlap — compare both vaults
- Fill the stub vault with practical notes + Mermaid
- Cross-link from overview: "For philosophy see [[Boundaries]] in Clean Architecture"
- Update Content.md to route to new full notes
- Remove old stub after verification
Content Migration (Stub -> Full Vault)
- Create
Topic/folder with overview + category subfolders + numbered topic files - Move content from old stub into new overview (preserve: personal experiments, GitHub links, home server configs)
- Update root Content.md to reference
[[Topic Overview]] - Delete old stub file
- Verify: old file gone, folder has correct count, Content.md updated
Content Hub Pattern (programming-note)
When a vault root has a Content.md that links to both stubs and full vaults:
- Rewrite it as a routing table: Topic | Primary Content | Local Note
- When a stub becomes a full vault, update the routing table — both columns point to
[[New Overview]] - The Content.md becomes a compass: quick stubs for scanning, deep vaults for learning
- Keep unique local content (personal GitHub repos, home server configs) in the new overview
Stub Removal Workflow
- Create full vault folder with overview + category subfolders + numbered topic files
- Verify all content from old stub is covered in new vault
- Run verification script (file count, Sources sections, Mermaid validity)
- Update root Content.md routing table
rmthe old stub file- Re-verify old stub is gone + Content.md has correct link
Batch Construction
For large vaults (>10 files):
- Create ALL directories first — single
mkdir -pwith all paths - Write files in parallel batches (write_file is independent per file)
- After all writes, run verification script
- Update overview and Content.md last
Verification Script Pattern
Use execute_code with tempfile scripts that check:
- File count matches expected
- All files > 1KB (not stubs)
## Sourcessection present in every file- ````mermaid` blocks have valid diagram types (no plain text in mermaid fence)
- Overview has sufficient wikilinks (≥ half the file count)
- Content.md references correct overview name
# Skeleton verification script
import os, re, tempfile
verify = r"""...checks..."""
tmp = os.path.join(tempfile.gettempdir(), "hermes-verify-<vault>.py")
with open(tmp, "w") as f: f.write(verify)
rc = os.system(f'python "{tmp}"')
os.remove(tmp)
Anti-patterns
- Don't build academic syllabi for practical teaching — ask about the target student
- Don't over-engineer taxonomy — >8 categories is too many. User rejected 8-section English structure.
- Don't create
Topic/Topic.mdfolder-per-file wrappers — flat files in category folders - Don't write walls of prose — tables, bullets, headers
- Don't skip gap analysis — show what's being filled before writing
- Don't fabricate image URLs — use authoritative sources or skip
- Don't delete ASCII before Mermaid is confirmed working
- Don't leave broken Mermaid blocks — verify after edits
- Don't rename files on disk while also changing wikilinks — use
patch()on content,mvfor files, update references after - Don't remove the old stub until the new vault is verified complete
- Summary vs complete book: a PDF under 1MB with ~27 pages is a student summary. The user may later provide the 2-8MB, 200+ page complete book. Don't rewrite — add missing chapters and enrich existing files with the full book's depth (personal stories, examples, additional sections). Use
ls -lato check file size before extraction.
Bulk Tagging
Add Obsidian YAML frontmatter tags: [...] to all .md files based on vault path and folder structure.
Tag Hierarchy
- Vault-level tag based on root folder:
programming,software-engineering,fitness,english,math - Sub-tags from folder names:
database,api,networking,book-summary,design-patterns - Book summaries: add
book-summary+ author tag (uncle-bob,pragmatic-programmer) - Overview/MOC files: add
overviewtag - Respect existing frontmatter: merge new tags into existing YAML frontmatter. Don't overwrite user's existing tags.
Tag Cleanup
After initial tagging, scan for false matches:
grammar/foundationleaking into software-engineering files (folder name overlap)discrete-math/graphshitting GraphQL or database graph filesclean-codehittingclean-coderfiles Remove false matches with a second pass.
Script Reference
See scripts/tag-vault.py for the bulk tagging + cleanup script.
Wikilink Repair
Find and fix broken [[wikilinks]] across all vaults. Obsidian resolves wikilinks by filename (not path), so map broken names to correct filenames.
Common Breakage Patterns
- Wrong chapter numbers: SWEBOK files reference old numbering (
06_→08_) - Case mismatches:
[[SOLID Principles]]→[[solid-principles]] - Renamed files:
[[03 Migration & Versioning]]→[[03 Migration Backup & Scaling]] - Folder links:
[[01 Gestalt Laws/]]→[[01 Law of Proximity]](filename-only) - Cross-vault links: use Obsidian's
../vault-name/Note Nameformat
Approach
- Build a set of all existing filenames (case-insensitive)
- Scan all
.mdfiles for[[wikilinks]] - For each broken link, find the closest matching existing file
- Batch-replace with correct targets
- Re-scan to verify count goes to zero (except user's personal notes)
Script Reference
See scripts/fix-wikilinks.py for the bulk repair script.
Script Reference
See scripts/fix-wikilinks.py for the bulk repair script.
Checklist Simplification (Ponytail Mode)
When user invokes ponytail skill on checklists: turn overengineered reference manuals into actual tick-box checklists.
Pattern
- Reference manual (100-300 lines): code examples, version trivia, tutorials, migration notes → stays as reference
- Launch checklist (30-50 lines):
- [ ]tick boxes, one-liners,→ [[vault]]links for deep knowledge - Each checklist file lives in its domain folder next to the reference files
Two-Layer Checklist Architecture
The generic + framework companion pattern. One framework-agnostic launch checklist, then framework-specific companions that inherit from it:
backend-checklist/
├── API Launch.md ← Generic: tick first, 45 items
├── spring-boot-api.md ← Reference manual (263 lines)
├── fiber-v3-api.md ← Go/Fiber companion, ~80 items
├── nestjs-api.md ← NestJS companion, ~75 items
└── rust-axum-api.md ← Rust/Axum companion, ~80 items
frontend-checklist/
├── Frontend Launch.md ← Generic: tick first, 48 items
├── react-js.md ← Reference manual (134 lines)
├── react-js-v2.md ← React/Next.js launch companion, ~55 items
├── vue-js.md ← Vue 3 + Nuxt companion, ~70 items
└── angular.md ← Angular 17+ companion, ~80 items
Each framework companion: references the generic (Tick [[API Launch]] first), adds framework-specific items (middleware chain, DI, build tools), and follows the same section structure as the generic for consistency.
Rules
- No code examples in launch checklists (generic or companion)
- No version-specific trivia
- No tutorials
- Every item:
- [ ] Short action → [[vault note]]for how - Keep original deep-reference files — don't delete, just add the slim version
- Framework companions should have the same top-level sections as the generic for easy cross-referencing
- After building a companion, cross-check all companions in the same domain: if NestJS has a Swagger section but Fiber doesn't, add it to Fiber too
- When a user asks "what framework for X?", give a one-line recommendation with brief rationale before building the checklist
Pitfalls
- Missing form validation: checklists under "State & Data" or "Forms" should include both client-side validation (Zod, class-validator) AND server-side re-validation (client UX, server security). User caught this gap in Frontend Launch.
- Inconsistent companions: after creating a new framework companion, scan the others for sections the new one introduced that the old ones lack (e.g., Swagger/OpenAPI, Form validation, Observability)
04 同仓库更多 Skills
project-spec-docs
Fill/update project_spec docs (templates, MM handoffs).
penpot-mcp
Penpot MCP: connect, verify, and fix streaming via nginx.
nginx-streaming-proxy
Configure nginx for streaming endpoints (SSE, MCP, WS).
branding-ci
Use for brand/CI identity, style guides, and brand docs.
yuanbao
Yuanbao (元宝) groups: @mention users, query info/members.
slidev
Create and present web-based slidedecks for developers using Slidev with Markdown, Vue components, code highlighting, animations, and interactive features. Use when building technical presentations, conference talks, code walkthroughs, teaching materials, or developer decks.