The plugin holds only WHEN, the vault holds HOW — designing a format-agnostic Claude Code plugin

Posted on Oct 30 • Originally published at wada-dev.com

My Claude Code plugin knowledge-gardener holds none of the Obsidian vault's formatting conventions (filename / frontmatter / link syntax / folder layout). Instead, it reads the vault's own README.md every time. This post is about why I did that, how it differs from existing plugins, and what properties fall out of it.

There are already several plugins that CRUD an Obsidian vault for Claude Code. Representative examples:

These hardcode the format on the plugin side. So if your vault has its own conventions — "standard markdown links (no wikilinks)," "numeric-prefix folders ( 01_FleetingNotes/ etc.)" — it conflicts outright. You could fork and fix it, but at that point the plugin's generality is gone.

knowledge-gardener holds only when to CRUD the vault, and follows the vault's own README for how to write.

[conventional plugin] [knowledge-gardener] plugin holds the format too plugin: when to write / what to write → doesn't fit another vault vault README: how to write → conventions concentrate in the vault Enter fullscreen mode Exit fullscreen mode With this separation of concerns:

I put a "Pre-flight Setup" at the top of every skill. The shared steps, abridged:

1. Resolve the vault path from the KG_VAULT environment variable 2. Read $KG_VAULT/README.md (the vault-root convention document) 3. Also read $KG_VAULT/../README.md (in case the vault is a repo subdir) 4. If a folder-scoped README exists, consult it too 5. If conventions are unclear, stop and ask — don't silently invent a default Enter fullscreen mode Exit fullscreen mode In implementation terms, each operational skill (plant / water / connect / prune / survey / recap) handles its own CRUD action, and they share the common "Pre-flight Setup" to eliminate duplication.

This post was written with AI assistance and reviewed by the author.