vault
Format conventions for markdown knowledge vaults. Use when writing notes or when format/syntax questions arise. Covers the dual-reader principle (human + AI), YAML frontmatter, wikilinks, and sources.
When & Why to Use This Skill
This Claude skill provides comprehensive format conventions for markdown knowledge vaults, specifically optimized for the 'dual-reader principle.' It ensures that digital notes are perfectly structured for both human readability in tools like Obsidian and seamless parsing by AI agents. By standardizing YAML frontmatter, wikilinks, and source attribution, it creates a high-quality, interoperable environment for long-term information management.
Use Cases
- Personal Knowledge Management (PKM): Organizing and standardizing notes within Obsidian or Logseq to ensure long-term clarity and searchability.
- AI-Enhanced Research: Structuring markdown files so that AI agents can accurately extract metadata and navigate internal links within a local knowledge base.
- Technical Documentation: Establishing a consistent style guide for markdown-based documentation that requires both human review and automated data processing.
- Digital Gardening: Implementing the dual-reader principle to make public or private knowledge bases accessible to both users and web crawlers/LLMs.
| name | vault |
|---|---|
| description | Format conventions for markdown knowledge vaults. Use when writing notes or when format/syntax questions arise. Covers the dual-reader principle (human + AI), YAML frontmatter, wikilinks, and sources. |
Vault Format
Dual-Reader Principle
Notes are read by both humans (via Obsidian/editors) and AI (raw markdown). Write so both have a good experience.
Avoid:
- Dataview blocks (AI sees dead code)
- Content that depends on embeds
![[]]resolving - Heavy callout syntax
Use freely:
- Wikilinks
[[Note Title]](both can follow) - YAML frontmatter (both can parse)
- Standard markdown
Note Structure
---
tags:
- tag1
- tag2
---
# Title
Content here.
## Sources
- (Author, Year) for claims
Conventions
Frontmatter: YAML with 3-7 specific tags
Links: Inline wikilinks [[Note Title]] or [[Note Title|display text]]
- No separate "Related Notes" section - links belong in context
Sources: Inline attribution (Author, Year), full references in ## Sources section