Use when writing to the vault — creating new notes (vault_write), editing existing notes (vault_edit, vault_append, vault_update_frontmatter). Handles duplicate checking, link discovery, annotations, and index updates for new notes. Provides guidelines for modifications.
From obsidian-pkmnpx claudepluginhub adrianv101/obsidian-pkm-plugin --plugin obsidian-pkmThis skill uses the workspace's default tool permissions.
Designs and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
Enables AI agents to execute x402 payments with per-task budgets, spending controls, and non-custodial wallets via MCP tools. Use when agents pay for APIs, services, or other agents.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
Follow these steps when creating new notes. When running as a subagent, the delegation prompt provides the note topic and project context.
Before creating, search for existing notes on the same topic:
vault_semantic_search({ query: "<topic/title of intended note>", limit: 5 })
If vault_semantic_search is unavailable (no OBSIDIAN_PKM_OPENAI_KEY), use vault_search with the note's title and key terms, and vault_query with matching tags to check for duplicates.
Route based on results:
vault_read, then use vault_append to add new content or vault_edit to refine existing content. Use vault_update_frontmatter if metadata changed. Skip to Step 4 (Discover Connections) after updating.Use vault_write with the appropriate template. Select the template and path based on content type:
| Content Type | Template | Default Path |
|---|---|---|
| Architecture decision | adr | <project>/development/decisions/ADR-NNN-{title}.md |
| Research finding | research-note | <project>/research/{title}.md |
| Bug investigation | troubleshooting-log | <project>/development/debug/{title}.md |
| Reusable knowledge | permanent-note | 03-Resources/Development/{title}.md |
| Task | task | <project>/tasks/{title}.md |
| Meeting record | meeting-notes | <project>/planning/{title}.md |
| Literature/article notes | literature-note | 03-Resources/{title}.md |
Where <project> is the vault project path (e.g., 01-Projects/MyApp). Determine from the delegation prompt, CLAUDE.md # PKM: annotation, or SessionStart hook context.
Notes in 03-Resources/ should be written as project-agnostic knowledge — useful regardless of where the insight originated. Use frontmatter tags or ## Related links to trace the origin project, but write the content for a general audience.
If CLAUDE.md specifies a different location for a content type, use that instead.
vault_write({
template: "<template>",
path: "<path-from-table>",
frontmatter: { tags: [...], ... }
})
Ensure:
{title} uses kebab-case (e.g., cache-eviction-strategies)vault_list on the decisions directory to determine the next NNN numbervault_write creates a skeleton from the template — headings with HTML comment placeholders and empty bullets. You must fill in the actual content.
vault_read to see the exact template outputvault_edit, using the exact text from the read output as old_stringWork section by section. Each vault_edit call must match text exactly as it appears in the file — do NOT guess what the template produced.
For templates with many sections, you can batch multiple sections into fewer edits by using a larger old_string that spans consecutive sections.
Run vault_suggest_links on the new note to find related content:
vault_suggest_links({ path: "<path-to-new-note>", limit: 8 })
Select the top 3–5 most relevant suggestions.
If vault_suggest_links is unavailable (no OPENAI_API_KEY), use vault_search with key terms from the note's title/topic and vault_query with matching tags to manually identify good link targets.
If no suggestions are returned (new vault or isolated topic), skip Steps 5–7 — the note's ## Related section will be filled as the graph grows.
For each selected link, write a one-line annotation explaining the relationship.
Good annotations use specific relationship language:
Bad: - [[note]] — related to this topic
Good: - [[architecture-patterns]] — foundational patterns this decision builds on
Use the note's content, shared tags, and conversation context to produce meaningful explanations.
Add annotated links to the note using vault_add_links:
vault_add_links({
path: "<path-to-new-note>",
links: [
{ target: "<vault-relative-path>", annotation: "relationship explanation" },
{ target: "<vault-relative-path>", annotation: "relationship explanation" }
]
})
The tool handles deduplication (skips already-linked targets), creates ## Related if missing, and validates targets exist. Format annotations as specific relationship language (see Step 5).
If the note uses a non-standard section (e.g., ## References), pass section: "## References".
If the template does not include a ## Related section, vault_add_links will create it automatically (default create_section: true). Templates with ## Related built in: adr, permanent-note, research-note, troubleshooting-log, literature-note, moc, meeting-notes.
Note: MOC notes created before this version may use ## Related Topics instead of ## Related. If vault_add_links fails with "Section not found", try section: "## Related Topics".
For significant note types (ADR, permanent-note, research-note, troubleshooting-log, literature-note, moc, meeting-notes):
## Related section using vault_add_linksSkip for ephemeral types (fleeting-note, daily-note) — Obsidian's native backlinks panel is sufficient.
_index.md_index.md references it where appropriateGuidelines for edits, appends, and frontmatter updates. These don't require the full creation workflow above.
[[note#heading]] wikilinks pointing to itvault_suggest_links to discover new connections worth addingvault_append({ heading: "## Sessions", position: "after_heading" }) for reverse-chronological orderingheading param to insert in the right location rather than appending at EOFvault_update_frontmatter over vault_edit for YAML fields — it parses and re-serializes safelytype, created, tags) can be updated but not removedstatus must be pending/active/done/cancelled, priority must be low/normal/high/urgent