obsidian-vault-kit

A Claude Code plugin for full-lifecycle Obsidian knowledge management — from article ingestion to spaced repetition review.

Ingest → Standardize → Query → Lint → Review → Sync

Skills

Skill	Command	What it does
vault-lint	/vault-lint	Health check: broken links, orphan pages, index consistency, frontmatter validation
vault-query	/vault-query	Karpathy-style "compile, don't retrieve": index lookup → full-text synthesis → optional write-back
review-scheduler	/review-scheduler start	(macOS only) Ebbinghaus spaced repetition via launchd + screen-unlock detection
chat-to-obsidian	/chat-to-obsidian	Convert the current conversation into a structured deep technical article
article-to-markdown	/article-to-markdown	Scrape an external URL, restructure as Markdown, save to vault
github-sync	/github-sync	Auto-update README.md and push vault changes to GitHub

Install

claude plugin install Howie126313/obsidian-vault-kit

Or clone manually:

git clone https://github.com/Howie126313/obsidian-vault-kit.git
cp -r obsidian-vault-kit /path/to/your/vault/.claude/plugins/obsidian-vault-kit

Highlights

Spaced Repetition (review-scheduler)

Based on the Ebbinghaus forgetting curve with intervals at [1, 2, 4, 7, 15, 30, 60, 90] days.

• Dual trigger: macOS launchd scheduled task + screen-unlock Swift watcher
• Idempotent: generates at most one review note per day, no matter how many triggers fire
• 3-level date extraction: YAML frontmatter → blockquote date → file birthtime
• 3-level summary extraction: frontmatter summary → intro section → H2 headings list

/review-scheduler start    # deploy & start (asks for preferred time)
/review-scheduler stop     # unload launchd tasks (keeps existing notes)
/review-scheduler status   # check running state

Vault Lint

Six checks in one pass:

1. Broken links — [[wikilinks]] pointing to nonexistent files
2. Orphan pages — files with zero inbound links
3. Index consistency — ghost entries, missing entries, count drift in index.md
4. Cross-reference suggestions — articles sharing keywords but not linked
5. Summary quality — empty or stale summaries in index.md
6. Frontmatter validation — required fields, enum values (type, confidence)

Auto-fixes low-risk issues (index gaps, counts). Reports everything else.

Vault Query (Karpathy-style)

Inspired by the "compile, don't retrieve" philosophy from Karpathy's LLM Wiki pattern:

1. Read index.md to locate candidate articles
2. Grep for supplementary matches
3. Read full text of relevant articles
4. Synthesize a comprehensive answer with [[wikilink]] citations
5. Optionally write the synthesis back as a new note (if it crosses 3+ source articles)

Frontmatter Schema

All articles follow a standardized schema:

title: string
date: YYYY-MM-DD
tags: [string]
type: concept | deep-dive | comparison | practice | guide | overview
confidence: high | medium | low
related: ["[[note-name]]"]
summary: string
source: string

Type and confidence are inferred automatically using deterministic rules (see skills/_shared/common-steps.md).

Customization

Directory Mapping

On first skill run, the plugin auto-detects your vault's directory structure and saves the config to $VAULT_ROOT/.vault-kit.json. You can edit this file to customize categories at any time.

{
  "version": 1,
  "directories": [
    {
      "dir": "frontend",
      "section": "Frontend",
      "match_rules": ["React, Vue, frontend frameworks, CSS, browser"]
    },
    {
      "dir": "ai-agents",
      "section": "AI Agents",
      "match_rules": ["Agent, LLM, AI models, Prompt"]
    }
  ],
  "default_directory": "",
  "uncategorized_section": "Uncategorized"
}

• dir — subdirectory name relative to vault root
• section — display name used as the index.md section header
• match_rules — topic descriptions for automatic article categorization
• default_directory — fallback directory when no rule matches (empty = vault root)

To reset and re-detect, delete .vault-kit.json and run any skill.

Review Intervals

Edit REVIEW_INTERVALS in skills/review-scheduler/references/review_reminder.py:

REVIEW_INTERVALS = [1, 2, 4, 7, 15, 30, 60, 90]  # days
TOLERANCE = 1  # ±1 day window

Requirements

• Claude Code CLI
• Obsidian
• Python 3 + PyYAML (for review-scheduler, macOS only)
• Xcode Command Line Tools (for review-scheduler, macOS only)
• Firecrawl MCP server (optional, for article-to-markdown URL scraping)

Project Structure

obsidian-vault-kit/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── _shared/common-steps.md          # shared workflow steps
│   ├── vault-lint/SKILL.md
│   ├── vault-query/SKILL.md
│   ├── review-scheduler/
│   │   ├── SKILL.md
│   │   ├── README.md
│   │   └── references/                  # Python, Swift, launchd templates
│   ├── github-sync/SKILL.md
│   ├── chat-to-obsidian/
│   │   ├── SKILL.md
│   │   └── references/article-template.md
│   └── article-to-markdown/
│       ├── SKILL.md
│       └── references/article-template.md
├── README.md
└── LICENSE

License

Apache-2.0