obsidian-health — команда для Claude Code: проверка хранилища
Команда obsidian-health сканирует Obsidian-хранилище, ищет противоречия, пробелы в концепциях, устаревшие данные и проблемы структуры. Выводит результаты по уровню серьёзности.
MIT ★ 5 412 обновлён 2026-10-24
/plugin marketplace add eugeniughelbur/obsidian-second-brain
/plugin install obsidian-second-brain@obsidian-second-brainЧто делает obsidian-health
Команда читает конфиг _CLAUDE.md, запускает скрипт vault_health.py и анализирует результаты параллельно несколькими агентами. Каждый агент специализируется на одной категории проблем: ссылки на несуществующие заметки (по приоритету упоминаний), дубликаты концепций, проблемы фронтматтера, устаревшие задачи, сиротские заметки, противоречия в Key Decisions и ошибки типизированных связей.
Для больших хранилищ с шумными папками можно создать .vault-config.json с исключениями (по названиям директорий или пути от корня). Команда обнаруживает также проблемы с источниками: заметки, которые объявляют локальный захват, но не содержат текста; активные знания, опирающиеся только на URL-записи; источники без оценки качества. Если в хранилище есть _meta/taxonomy.md, команда проверит соответствие тегов канонической таксономии.
Это инструмент для вики-подхода: ссылки на несуществующие заметки — не ошибки, а ранжированный список того, что стоит написать. Команда предложит триажировать их через triage_links.py (нужен ANTHROPIC_API_KEY для автоматического ранжирования) или оставить как план.
Какие задачи решает
- найти противоречия в ключевых решениях и справочных заметках
- выявить пробелы в структуре хранилища по ссылкам на несуществующие заметки
- обнаружить источники с неполным локальным захватом
- проверить соответствие тегов таксономии
- отследить устаревшие задачи и пустые папки
Примеры запросов агенту
- Провести аудит хранилища: какие заметки стоит написать, где противоречия?
- Проверить здоровье знаний: есть ли источники без оценки качества?
- Найти дубликаты концепций и ошибки в типизированных связях
Как установить obsidian-health
1Через маркетплейс плагинов
/plugin marketplace add eugeniughelbur/obsidian-second-brain/plugin install obsidian-second-brain@obsidian-second-brain2Вручную: положить файлы
.claude/commands/obsidian-health.mdВызов — /obsidian-health. Для всех проектов — ~/.claude/commands/
Вручную: положить файлы
~/.codex/prompts/obsidian-health.mdВызов — /prompts:obsidian-health. В Codex этот формат помечен устаревшим, замена — скиллы
Вручную: положить файлы
.github/prompts/obsidian-health.prompt.mdВручную: положить файлы
.gemini/commands/obsidian-health.tomlGemini хранит команды в TOML: текст запроса — в поле prompt
Вопросы об obsidian-health
Как установить obsidian-health в Claude Code?
Выполни /plugin marketplace add eugeniughelbur/obsidian-second-brain, затем /plugin install obsidian-second-brain@obsidian-second-brain и убедись, что файл .claude/commands/obsidian-health.md доступен в проекте.
Что делает obsidian-health?
Сканирует Obsidian-хранилище на противоречия, пробелы в концепциях, устаревшие данные, проблемы структуры и источников. Результаты группирует по серьёзности и запускает специализированных агентов для каждой категории проблем.
Нужны ли зависимости для работы команды?
Команда требует uv для запуска Python-скриптов и переменную ANTHROPIC_API_KEY для автоматического ранжирования ссылок на несуществующие заметки через triage_links.py. Скрипт работает из директории скилла, путь к хранилищу берётся из _CLAUDE.md.
Исходный текст
obsidian-health.md · MIT
---
description: Run a vault health check - grouped by severity, detects contradictions, concept gaps, stale claims, and structural issues
category: meta
triggers_en: ["vault health", "check vault", "audit vault", "vault diagnostics"]
triggers_de: ["Vault-Gesundheit", "Vault prüfen", "Vault auditieren", "Vault-Diagnose"]
triggers_es: ["salud del vault", "revisa el vault", "audita el vault", "diagnóstico del vault"]
triggers_pt: ["saúde do vault", "verifique o vault", "audite o vault", "diagnóstico do vault"]
triggers_zh: ["检查知识库健康状况", "给我的知识库做体检", "审计我的笔记库", "诊断知识库问题"]
---
Use the obsidian-second-brain skill. Execute `/obsidian-health`:
1. Read `_CLAUDE.md` first to find the vault path
2. Run the health scan from the skill root (its absolute path was given at session start as **Skill root**; substitute it for `SKILL_ROOT`): `uv run --directory "SKILL_ROOT" scripts/vault_health.py --path ~/path/to/vault --json`
(replace vault path with the one from `_CLAUDE.md`)
- **Large or noisy vault?** If the scan surfaces thousands of findings from directories the user does not maintain by hand (atomic-card pools, backup snapshots, imported dumps), do NOT hardcode fixes. Offer to write a `<vault>/.vault-config.json` that extends the exclude list: `{"exclude-dirs": ["_card-pool"], "exclude-paths": ["Archive/Backup"]}`. `exclude-dirs` matches directory names anywhere in the tree; `exclude-paths` matches vault-relative path prefixes. Both are additive - the built-in excludes always apply - and a missing or malformed file is ignored silently. Re-run the scan afterward.
- **`source_payload` findings?** (#194) Three different problems under one type. An `error` naming one source means the note declares `capture_scope: full-local` or `bounded-local` and has essentially no body - it claims evidence it does not hold, so re-capture it or set `capture_scope: url-only` and say so plainly. A `warning` naming a source plus the notes that link it means active knowledge rests on a `url-only` record: the vault kept the locator, not the evidence. Offer to re-capture the source, or to mark the dependent claims as URL-backed; never resolve it by copying a complete copyrighted work. The single `info` line counting sources with no `capture_scope` is every source written before the field existed - fill them in as you touch them, do not sweep the vault. `"source_policy": "strict-local"` in `.vault-config.json` raises the last two by one severity.
- **`source_quality` findings?** (#258) A `warning` names a concept, synthesis or other note that cites only sources graded `speculation`: provenance unknown, derived or conflicting. It is not a claim that the note is wrong. Offer to corroborate its claims with a better source (the bounded lateral read in `references/source-quality-check.md`, only on an explicit yes), or to say in the note that they are unverified. A source with no `source_quality` is unjudged and never reported. `"source_quality_policy": "silent"` in `.vault-config.json` mutes the check.
- **`source_quality_unlabelled` findings?** (#258) A `warning` names a `type: source` note whose first lines say it is unverified, unconfirmed or speculative while its frontmatter has no `source_quality`. The prose is right, the field is missing. Offer to add `source_quality: speculation`, or a higher grade if the note shows the provenance capture saw. The same policy key mutes it.
- **`rewrite_policy: unattended` info line?** The vault has opted out of the confirm-before-rewrite gate in `/obsidian-ingest` (#250) and reviews rewrites through its own layer. Nothing to fix; the line is there so a reader of the report knows the vault runs without the gate. Remove the key from `.vault-config.json` to restore the default.
3. Parse the JSON output and split findings into categories
4. Spawn parallel subagents to handle each category simultaneously:
- **Wanted-notes agent**: the script reports `wanted_note` items - links to a note that does not exist yet. These are NOT errors: in a wiki-style vault you link a thing the moment you mention it, so wanted notes are a demand-ranked wishlist of pages worth writing, not breakage. Triage them with `uv run --directory "SKILL_ROOT" scripts/triage_links.py --path <vault> --limit N`, which sorts each into keep (a deliberate seed, leave it), create (referenced enough to deserve a real note now), or delete (junk or a typo - fix the link). Report-only by default; needs `ANTHROPIC_API_KEY`. Headless on purpose: it can run unattended or on a schedule. The goal is to triage the backlog, never to drive the count to zero.
- **Duplicates agent**: confirm duplicates are truly the same concept, not just similar names
- **Taxonomy agent**: only fires when `<vault>/_meta/taxonomy.md` exists (format in `references/taxonomy-format.md`) - the script's `tag_synonym` and `tag_not_in_taxonomy` findings are empty otherwise, so a vault without the file sees nothing. `tag_synonym` means a note's tag is a known synonym of a canonical tag: the fix is unambiguous, so offer to rewrite that note's `tags:` frontmatter to the canonical form, per note, with explicit confirmation before editing - never batch-rewrite across the vault unattended. `tag_not_in_taxonomy` means the tag matches neither a canonical tag nor a synonym: report it as informational only - it may be a legitimate new tag - and never auto-fix it; the taxonomy file is a human-curated vocabulary, not something this command edits on its own.
- **Frontmatter agent**: identify notes missing required fields by type. If the script reports a `code_fence_wrapped` note (frontmatter trapped inside a leading ```` ```markdown ```` fence), the fix is to **unwrap it** - strip the opening fence line and the matching closing ```` ``` ```` so the inner `---` frontmatter and body become real markdown. **Never add a new frontmatter block to a wrapped note** - that produces duplicate frontmatter and leaves the body trapped. If the note already has both a prepended frontmatter block and an inner wrapped one, merge them (keep the richer fields) and unwrap.
- **Staleness agent**: check overdue tasks and unfilled template syntax
- **Orphans agent**: check orphaned notes and empty folders
- **Contradictions agent**: scan Key Decisions sections and reference/concept notes (the concept or knowledge folder per `references/folder-map.md` - wiki-style `wiki/concepts/`, Obsidian-style `Knowledge/`) for claims that conflict with each other or have been superseded by newer sources
- **Typed-edge lint agent**: run `uv run --directory "SKILL_ROOT" scripts/link_graph.py --path <vault> --lint`, which validates the `relations:` typed-edge layer (see `references/ai-first-rules.md` Rule 6 § Typed edges). It returns `findings` (each with `severity`, `kind`, `note`, `target`, `type`, `detail`) and a `summary`. Map them into the severity groups below: `contradiction` (A and B claim the same asymmetric type about each other) is 🔴 Critical; `unknown_type`, `dangling_target`, and `self_edge` are 🟡 Warning (fix the type name, the target link, or drop the self-edge); `missing_inverse` is ⚪ Info (offer to add the reciprocal edge on the target note, never required). If the vault uses no `relations:` blocks yet, this returns zero findings - not an error.
- **Concept gaps agent**: find terms mentioned 3+ times across different notes that lack a dedicated page - these are missing concepts the vault should have
- **Stale claims agent**: compare reference/concept notes (the concept or knowledge folder per `references/folder-map.md` - wiki-style `wiki/concepts/`, Obsidian-style `Knowledge/`) against their source dates - flag any note older than 6 months that references fast-moving topics (tools, APIs, pricing, team structure)
- **Freshness agent**: run the freshness lint - `uv run --directory "SKILL_ROOT" scripts/freshness_lint.py --path <vault> --json` - which enforces `references/freshness-policy.md`: every stored fact must be timeless, dated, or a pointer. FRESH-1 errors are present-tense claims about fast facts (counts, statuses, balances) with no `as of` stamp - the sentences that silently become lies. Report the top offenders grouped by folder; offer to fix by adding a stamp, converting to a pointer (where truth lives + last observed value), or moving the claim into a dated note. For aged stamps (FRESH-2 warnings) run the refresh loop from the policy: re-observe (check the source, update value + stamp), convert (keep only the pointer), or retire (move into a dated note as history). Never delete - restamp, convert, or mark superseded
5. Merge results and group by severity:
- 🔴 Critical: unfilled template syntax, contradictions between notes, typed-edge contradiction cycles, code-fence-wrapped notes (frontmatter trapped in a fence)
- 🟡 Warning: duplicates, stale tasks, missing frontmatter, stale claims, concept gaps, freshness violations (undated fast facts, aged stamps), typed-edge problems (unknown type, dangling target, self-edge), tag-synonym findings (a tag that should fold to its canonical form per `_meta/taxonomy.md`), invalid tags (digits-only, dots, spaces - Obsidian renders these broken with no error; fix by prefixing a word or replacing the separator with `-`)
- ⚪ Info: wanted notes (linked but unwritten - a wishlist, not errors), orphaned notes, empty folders, missing inverse edges, tags not in the taxonomy (informational, not necessarily wrong)
6. For safe fixes (missing frontmatter, unwrapping code-fence-wrapped notes, obvious duplicates, creating pages for concept gaps), offer to fix automatically. For a `code_fence_wrapped` note, unwrap the fence rather than adding frontmatter (see the Frontmatter agent note above).
7. For destructive fixes (archiving, merging, resolving contradictions), list them and ask for explicit confirmation first
8. Append to the operation log: if `Logs/` exists write `**HH:MM** - health | X critical, Y warnings, Z info` to `Logs/YYYY-MM-DD.md`; otherwise append `## [YYYY-MM-DD] health | X critical, Y warnings, Z info` to `log.md`
---
**AI-first rule:** Every note created or updated by this command MUST follow `references/ai-first-rules.md` - `## For future agent` preamble, rich frontmatter (`type`, `date`, `tags`, `ai-first: true`, plus type-specific fields), recency markers per external claim, mandatory `[[wikilinks]]` for every person/project/concept referenced, sources preserved verbatim with URLs inline, and confidence levels where applicable. If that path does not resolve from your working directory, search upward for it; if you still cannot read it, say so before writing rather than producing a note that silently skips the rule. The vault is for future agent retrieval - not human reading.
**Anti-fabrication:** Search exhaustively before claiming any note, person, or file is absent - false absence is the most common failure mode - and never invent facts, entities, or dates (mark unknowns as `TBD`). See the anti-fabrication and search-completeness hard rules in `references/ai-first-rules.md`.
© Eugeniu Ghelbur · MIT · eugeniughelbur/obsidian-second-brain