Obsidian Kb Artifacts

Obsidian KB Artifacts

This skill handles format and artifact concerns only.

Responsibilities

• Obsidian Markdown formatting
• wikilinks and embeds
• registry table formatting
• canvas generation and validation
• optional Bases generation
• Obsidian CLI operations
• link repair in canonical notes
• lint-report formatting

Rules

• this skill does not decide where knowledge belongs
• .base is explicit-only
• Maps/ contains derived artifacts only
• link repair should strengthen existing canonical notes, not create note sprawl
• literature canvas edges must preserve evidence strength when the source notes provide it
• do not create stable-looking claim edges from abstract-only, webpage-placeholder, or unsupported notes

Read next

• references/OBSIDIAN-MARKDOWN.md
• references/CANVAS.md
• references/BASES.md
• references/REGISTRY-TABLES.md
• references/LINK-REPAIR.md
• references/CLI.md

BASES

Obsidian Bases are optional helper artifacts. They are explicit-only and should not be created by default.

Default policy

• Do not generate .base files unless the user explicitly asks for Bases or database-like views.
• Keep .base files under a project-local helper area only when they improve navigation.
• Do not make Bases the canonical registry or source of truth.

Basic structure

A .base file is YAML and typically contains:

filters:
  and:
    - 'status == "active"'

views:
  - type: table
    name: "Active Results"
    order:
      - file.name
      - status
      - updated

Good use cases

• table view for active experiments or results
• card view for paper notes
• filtered task-like view over canonical notes

Avoid by default

• auto-generating many .base files during bootstrap
• using Bases to replace _system/registry.md
• coupling critical project logic to plugin-specific Base behavior

CANVAS

Canvas files are optional derived artifacts stored under Maps/. They are not the source of truth.

Placement and scope

• Default path: Maps/*.canvas
• Default auto-maintained canvas: Maps/literature.canvas
• Other canvases are explicit-only unless a workflow clearly requires them
• Keep canvas references project-local unless the user explicitly asks for cross-project mapping

Core JSON structure

Use the standard JSON Canvas shape:

{
  "nodes": [],
  "edges": []
}

Each node needs a stable id, coordinates (x, y), and size (width, height). Each edge needs id, fromNode, and toNode.

Recommended node types

• file node: canonical note under Sources/*, Knowledge/*, Experiments/*, Results/*, Writing/*
• text node: short synthesis, legend, gap summary, or section heading
• link node: external URL when the relationship should stay outside the vault
• group node: visual cluster for a topic, method family, dataset family, or review bucket

Avoid treating free-form text nodes as a second knowledge store. Durable content belongs in markdown notes first.

File-node conventions

Use file nodes for canonical notes that already exist on disk.

• paper/source note -> point to Sources/Papers/* or other Sources/*
• synthesis note -> point to Knowledge/*
• experiment note -> point to Experiments/*
• stable result/report -> point to Results/* or Results/Reports/*

File nodes should reference existing files only. If the note does not exist yet, create the note first or use a temporary text node that clearly indicates draft intent.

Edge conventions

Use edges to express relationship semantics, not decoration.

• method extends method
• paper uses dataset
• result supports claim
• gap motivates experiment
• report summarizes experiment

When labels are supported in the producing workflow, keep them short and explicit:

• uses
• extends
• compares
• supports
• contradicts
• motivates
• summarizes

Do not draw unlabeled dense meshes when a few explicit edges communicate the structure better.

Group and color conventions

Use groups to organize major clusters such as:

• Methods
• Datasets
• Claims
• Gaps
• Experiments
• Results

Use color sparingly and consistently. Color is a navigation aid, not a semantic database.

Suggested pattern:

• one group color per cluster family
• neutral text nodes for summaries
• do not encode critical meaning only through color

Layout conventions

• Keep 50–100 px spacing between unrelated nodes
• Align related file nodes in rows or columns
• Put source papers on one side, synthesis notes in the middle, and gaps / experiments / results downstream
• Avoid overlapping groups
• Prefer a stable, readable layout over a compact but fragile layout

Recommended Maps/literature.canvas structure

For literature workflow, prefer this shape:

1. Sources/Papers/* file nodes for the key papers 2. Knowledge/* file nodes for:

• Literature Overview
• Method Taxonomy
• Research Gaps

3. text nodes for short bridge summaries where needed 4. groups for Methods, Datasets, Gaps, and Results 5. edges showing:

• paper -> method family
• paper -> dataset
• paper -> gap or limitation
• gap -> experiment direction

This keeps the canvas derived from canonical notes instead of replacing them.

Validation checklist

Before treating a canvas as valid, check:

• every file node target exists
• every edge endpoint points to an existing node id
• node ids are unique
• groups do not reference missing child nodes
• archived notes are either intentionally preserved or relinked; no silent dangling references
• the canvas adds navigation value instead of duplicating a markdown table

What not to put in Canvas

• raw source-of-truth metadata that belongs in _system/registry.md
• long-form synthesis that belongs in Knowledge/*
• unstable scratch thinking that should remain in Daily/*
• auto-generated project-wide mega-graphs by default

Generate or update a canvas only when the user explicitly asks for it, or when Maps/literature.canvas is part of the literature workflow.

CLI

Use the Obsidian CLI only as an optional helper for navigation, search, verification, or lightweight note actions. The filesystem remains the source of truth.

Common uses

obsidian help
obsidian search query="diffusion" limit=10
obsidian read file="My Note"
obsidian daily:append content="- [ ] Follow up"

Good uses in Claude Scholar

• open a note after updating it
• search a vault for a known keyword
• append a short daily action item
• verify that CLI targeting works for a specific vault

Do not rely on CLI for

• canonical registry truth
• project binding state
• lifecycle decisions
• sync logic that must work without Obsidian running

Fallback rule

If CLI is unavailable or the Obsidian app toggle is off, continue with filesystem-only KB maintenance.

LINK REPAIR

Repair links by strengthening existing canonical paths and avoiding duplicate concept notes.

OBSIDIAN MARKDOWN

Use valid Obsidian-flavored Markdown for canonical project notes. Prefer readable notes first, then Obsidian-native structure.

Core rules

• Keep a small frontmatter block at the top of canonical notes.
• Use [[wikilinks]] for vault-internal references and Markdown links only for external URLs.
• Use readable headings and short sections; avoid turning notes into raw dumps.
• Prefer Markdown tables only when the comparison is truly tabular.
• Keep system files and generated tables deterministic; keep human notes readable.

Frontmatter and properties

Use frontmatter for stable metadata such as:

---
type: knowledge
status: active
created: 2026-04-24
updated: 2026-04-24
tags:
  - research
  - active
aliases:
  - Alternative Note Name
---

Prefer simple scalar or list properties. Do not over-model note metadata unless the workflow needs it.

Wikilinks

Common forms:

[[Note Name]]
[[Folder/Note Name]]
[[Note Name|Display Text]]
[[Note Name#Heading]]
[[Note Name#^block-id]]

Use folder-qualified links when note names are ambiguous. Prefer links to canonical notes over duplicate notes.

Embeds

Use embeds when the reader benefits from inline context, not just because the syntax exists.

![[Note Name]]
![[Note Name#Heading]]
![[image.png|300]]
![[document.pdf#page=3]]

Avoid large embed chains that make notes hard to scan.

Callouts

Use callouts to highlight information that benefits from visual separation:

> [!note]
> Supporting detail.

> [!warning] Risk
> This assumption may break under domain shift.

Common types: note, info, tip, warning, question, success, failure, quote, example.

Tables

Use tables for:

• comparison matrices
• experiment summaries
• compact registries meant for humans

Avoid tables for long prose or nested content.

Tags and aliases

• Use tags sparingly and consistently.
• Use aliases when a note has a common alternate name or paper title variant.
• Do not rely on tags as the only navigation mechanism when wikilinks and index notes are clearer.

REGISTRY TABLES

Registry tables are the only visible project registry and should remain human-readable and machine-parseable.