Obsidian Doc Workflow
Overview
This skill is the Obsidian / local Markdown delivery adapter for research documents. Content contracts stay in task skills such as paper-card-delivery, paper-deep-dive, survey-builder, and llm-wiki. This skill owns vault path resolution, Markdown/callout/frontmatter/asset conventions, narrow file edits, and post-write verification.
Always use research-doc-workflow as the platform router. Use this skill when the durable target is Obsidian or a vault Markdown path.
Division Of Labor With llm-wiki
| Concern |
Owner |
Wiki layers (raw/ / wiki/), ingestion, provenance, indexes, graph hygiene |
llm-wiki |
| File write mechanics, callouts, frontmatter shape, relative assets, link hygiene, re-read verification |
this skill |
| Paper-card fields and validators |
paper-card-delivery |
When writing Research-Wiki or vault learning notes, load llm-wiki for knowledge rules and this skill for format/write verification. Format conflicts: this skill wins for representation; llm-wiki wins for what belongs in the wiki.
When To Use
- User supplies a vault-relative or absolute
.md path, folder under WorldModelVault, or says Obsidian / 写到 vault.
- An existing durable note already lives in the vault and must be updated in place.
Do not silently redirect an Obsidian target to Feishu or Notion. Preserve the note's folder, naming, and neighboring conventions unless the user asks to move it.
Shared Write Workflow
- Read the task-specific content skill and keep its semantic contract unchanged.
- Resolve the exact note path and folder conventions (frontmatter schema, asset dir, link style).
- Read the current file (and nearby notes if hierarchy/MOC matters) before editing.
- Prepare one canonical Markdown draft; keep Obsidian-native constructs listed below.
- Make the narrowest safe edit. Prefer surgical section updates over rewriting an entire rich note that already has images and user annotations.
- Re-read the written file and verify frontmatter, headings, links, image paths, formulas, and referenced assets. Run content-skill validators when present.
Obsidian Format Deltas
| Concern |
Obsidian rule |
| Hierarchy |
Folders + MOC/index notes + [[wikilinks]]; do not invent Feishu wiki nodes or Notion database properties as body text |
| Callouts |
Keep > [!type] (including > [!paper] when paper-card CSS/snippet applies) |
| Metadata |
YAML frontmatter for stable queryable fields; do not paste Notion property dumps into the body |
| Paper-card metadata |
Four physical Markdown lines after the title (not Notion <br>-joined single line) |
| Math |
Keep $...$ / $$...$$ |
| Images |
Relative paths under the vault asset convention; meaningful alt text or established caption convention; no absolute machine paths |
| Links |
[[wikilinks]] when the vault expects them; relative Markdown links for portable assets; external PDFs as normal [text](url) |
| References |
Plain [n] labels + original bibliography text + | [url](url) with display text equal to URL; never 1. ordered lists for bibliography |
| Body citations |
[[n](pdf-url)] with the same URL map as References |
| Editable trees |
Mermaid, Canvas, or linked outline per vault convention—not Feishu whiteboard tokens |
Forbidden Cross-Platform Residue
Reader-facing Obsidian notes must not contain:
- Notion paper-card
<br> metadata tricks left as literal HTML when four physical lines are required
- Feishu Docx/XML,
block_id, docs +media-insert instructions, or Lark whiteboard-only PlantUML as the primary tree
- Absolute paths like
/Users/..., .tools/tmp/..., or MinerU scratch directories in reader-facing embeds
- Visible
EW_IMG_… migration labels, 图像： assets/... residue, or Feishu-only layout notes
- Database property tables copied from Notion as a substitute for frontmatter without converting fields
Paper Cards in Obsidian
- Follow
paper-card-delivery.
- Keep four physical metadata lines; relative image + Chinese caption in alt/vault convention; seven bullet slots.
- Validate local drafts when practical:
python .tools/skills/paper-card-delivery/scripts/validate_paper_card.py path/to/cards.md --target obsidian
Deep Dives / Surveys / Meetings
- Completion standards come from
paper-deep-dive / survey-builder / meeting conventions in llm-wiki or the content skill.
- Obsidian mapping: one main note plus linked manuscript notes in a stable folder; relative assets; LaTeX math; Mermaid/Canvas or outline for
论文解析树.
- Do not require a Feishu mind map for vault deliveries.
Workspace Hygiene
- Store extraction intermediates under
.tools/tmp/<task-slug>/; delete after the durable note is re-read and verified.
- Durable figures belong under the note's
assets/ (or vault-established asset path) with semantic filenames—not the vault root.
- Do not leave opaque scratch files (
*_after.json, one-off scripts) in WorldModelVault root.
Acceptance Checklist
- Destination is Obsidian/vault Markdown from URL/path or explicit instruction.
- Content-skill contract passes.
- Frontmatter, headings, wikilinks/relative links, formulas, media paths, and captions verified by re-reading the file.
- No Feishu/Notion syntax residue in reader-facing content.
- Paper-card metadata (if any) uses four physical lines; validator run when a local draft exists.
- Response names Obsidian/path and the actual write/verify status.
1---2name: obsidian-doc-workflow3description: Obsidian/Markdown vault workflow for reading, editing, structuring, and verifying notes used by research skills (paper cards, deep dives, surveys, wiki pages, meeting notes). Use when the user gives a vault path or .md note, names Obsidian/WorldModelVault as the destination, or research-doc-workflow routes a durable write to local Markdown. Applies Obsidian-native format deltas so Feishu/Notion syntax does not leak into reader-facing notes.4---56# Obsidian Doc Workflow78## Overview910This skill is the Obsidian / local Markdown delivery adapter for research documents. Content contracts stay in task skills such as `paper-card-delivery`, `paper-deep-dive`, `survey-builder`, and `llm-wiki`. This skill owns vault path resolution, Markdown/callout/frontmatter/asset conventions, narrow file edits, and post-write verification.1112Always use [`research-doc-workflow`](../research-doc-workflow/SKILL.md) as the platform router. Use this skill when the durable target is Obsidian or a vault Markdown path.1314## Division Of Labor With `llm-wiki`1516| Concern | Owner |17|---|---|18| Wiki layers (`raw/` / `wiki/`), ingestion, provenance, indexes, graph hygiene | [`llm-wiki`](../llm-wiki-skill/SKILL.md) |19| File write mechanics, callouts, frontmatter shape, relative assets, link hygiene, re-read verification | **this skill** |20| Paper-card fields and validators | [`paper-card-delivery`](../paper-card-delivery/SKILL.md) |2122When writing Research-Wiki or vault learning notes, load `llm-wiki` for knowledge rules and this skill for format/write verification. Format conflicts: this skill wins for representation; `llm-wiki` wins for what belongs in the wiki.2324## When To Use2526- User supplies a vault-relative or absolute `.md` path, folder under WorldModelVault, or says Obsidian / 写到 vault.27- An existing durable note already lives in the vault and must be updated in place.2829Do not silently redirect an Obsidian target to Feishu or Notion. Preserve the note's folder, naming, and neighboring conventions unless the user asks to move it.3031## Shared Write Workflow32331. Read the task-specific content skill and keep its semantic contract unchanged.342. Resolve the exact note path and folder conventions (frontmatter schema, asset dir, link style).353. Read the current file (and nearby notes if hierarchy/MOC matters) before editing.364. Prepare one canonical Markdown draft; keep Obsidian-native constructs listed below.375. Make the narrowest safe edit. Prefer surgical section updates over rewriting an entire rich note that already has images and user annotations.386. Re-read the written file and verify frontmatter, headings, links, image paths, formulas, and referenced assets. Run content-skill validators when present.3940## Obsidian Format Deltas4142| Concern | Obsidian rule |43|---|---|44| Hierarchy | Folders + MOC/index notes + `[[wikilinks]]`; do not invent Feishu wiki nodes or Notion database properties as body text |45| Callouts | Keep `> [!type]` (including `> [!paper]` when paper-card CSS/snippet applies) |46| Metadata | YAML frontmatter for stable queryable fields; do not paste Notion property dumps into the body |47| Paper-card metadata | Four **physical** Markdown lines after the title (not Notion `<br>`-joined single line) |48| Math | Keep `$...$` / `$$...$$` |49| Images | Relative paths under the vault asset convention; meaningful alt text or established caption convention; no absolute machine paths |50| Links | `[[wikilinks]]` when the vault expects them; relative Markdown links for portable assets; external PDFs as normal `[text](url)` |51| References | Plain `[n]` labels + original bibliography text + ` \| [url](url)` with display text equal to URL; never `1.` ordered lists for bibliography |52| Body citations | `[[n](pdf-url)]` with the same URL map as References |53| Editable trees | Mermaid, Canvas, or linked outline per vault convention—not Feishu whiteboard tokens |5455## Forbidden Cross-Platform Residue5657Reader-facing Obsidian notes must not contain:5859- Notion paper-card `<br>` metadata tricks left as literal HTML when four physical lines are required60- Feishu Docx/XML, `block_id`, `docs +media-insert` instructions, or Lark whiteboard-only PlantUML as the primary tree61- Absolute paths like `/Users/...`, `.tools/tmp/...`, or MinerU scratch directories in reader-facing embeds62- Visible `EW_IMG_…` migration labels, `图像： assets/...` residue, or Feishu-only layout notes63- Database property tables copied from Notion as a substitute for frontmatter without converting fields6465## Paper Cards in Obsidian6667- Follow [`paper-card-delivery`](../paper-card-delivery/SKILL.md).68- Keep four physical metadata lines; relative image + Chinese caption in alt/vault convention; seven bullet slots.69- Validate local drafts when practical:7071```bash72python .tools/skills/paper-card-delivery/scripts/validate_paper_card.py path/to/cards.md --target obsidian73```7475## Deep Dives / Surveys / Meetings7677- Completion standards come from `paper-deep-dive` / `survey-builder` / meeting conventions in `llm-wiki` or the content skill.78- Obsidian mapping: one main note plus linked manuscript notes in a stable folder; relative assets; LaTeX math; Mermaid/Canvas or outline for `论文解析树`.79- Do not require a Feishu mind map for vault deliveries.8081## Workspace Hygiene8283- Store extraction intermediates under `.tools/tmp/<task-slug>/`; delete after the durable note is re-read and verified.84- Durable figures belong under the note's `assets/` (or vault-established asset path) with semantic filenames—not the vault root.85- Do not leave opaque scratch files (`*_after.json`, one-off scripts) in `WorldModelVault` root.8687## Acceptance Checklist8889- Destination is Obsidian/vault Markdown from URL/path or explicit instruction.90- Content-skill contract passes.91- Frontmatter, headings, wikilinks/relative links, formulas, media paths, and captions verified by re-reading the file.92- No Feishu/Notion syntax residue in reader-facing content.93- Paper-card metadata (if any) uses four physical lines; validator run when a local draft exists.94- Response names Obsidian/path and the actual write/verify status.
jasperpwang