---
name: obsidian-compatible-writing
description: Write memory notes that are pleasant in Obsidian without requiring Obsidian. Optional enhancement skill. Use when the user has Obsidian open alongside their agent workflow and wants better vault navigation.
---

# Obsidian-Compatible Writing

**Optional enhancement skill.** The core agent-knowledge system works fully without Obsidian.
This skill improves note quality for users who also browse the vault in Obsidian.

Nothing here changes the canonical data model. Memory/ is still the source of truth.
Evidence/ is still non-canonical. The branch-note convention is unchanged.

---

## What this skill adds

- Better YAML frontmatter for Obsidian's properties panel
- Optional tags for Obsidian graph filtering
- Better internal link quality
- Guidance for the optional canvas export
- Guidance for optional dashboard notes

What this skill does NOT do:
- Make wiki-links mandatory (they break portability)
- Require Obsidian to open or read notes
- Change the canonical data model
- Make canvas or dashboard files required

---

## Richer frontmatter

Obsidian's Properties panel and graph use frontmatter. Adding a few extra fields
makes the vault easier to navigate visually:

```markdown
---
note_type: branch-entry
area: auth
updated: 2025-01-15
tags:
  - memory
  - auth
  - project/<project-slug>
aliases:
  - Authentication
---
```

Tags:
- `memory` on all Memory/ notes (makes graph filtering easy)
- `evidence` on all Evidence/ notes
- Domain tag matching the branch name
- Project tag for multi-project vaults

Aliases: add the human-readable name of the branch if it differs from the file name.
(e.g., `jwt.md` could alias to `JWT Handling`)

These fields are optional. The agent-knowledge system ignores them. Obsidian uses them.

---

## Link quality

Standard portable links work in Obsidian:
```markdown
See [auth/auth.md](auth/auth.md) for token handling.
```

Obsidian also resolves wiki-links, but only use them inside Obsidian-specific notes:
```markdown
See [[auth/auth]] for token handling.    <- wiki-link, Obsidian only
See [auth/auth.md](auth/auth.md) ...    <- portable, works everywhere
```

For Memory/ notes (which must be portable), always use standard markdown links.
Wiki-links are acceptable in optional Outputs/ or Dashboards/ notes.

---

## Graph navigation

The knowledge graph looks best when:
- Every branch note links to its subtopic notes (already required by convention)
- Every branch note links back to `Memory/MEMORY.md` (add `[Index](../MEMORY.md)` at top)
- Decisions link back to the branch note that records them
- Evidence/imports notes reference their source branch in frontmatter

Adding a backlink line at the top of each branch note improves Obsidian graph density:
```markdown
[Index](../MEMORY.md) | [Decisions](../decisions/decisions.md)
```

---

## Optional: dashboard notes

Dashboards/ contains generated rollup views. These can be enhanced for Obsidian
with dataview-style frontmatter -- but only if the user has the Dataview plugin.

Since Dataview is optional, keep dashboards compatible without it:
- Use plain markdown tables and lists as the primary content
- Add a dataview query as a comment block or secondary section for users who have it

```markdown
## Recent Sessions

(plain markdown table of recent sessions)

<!-- Dataview users can replace the above with:
```dataview
TABLE date, title FROM "Sessions" SORT date DESC LIMIT 5
``` -->
```

---

## Optional: canvas export

The `agent-knowledge export-canvas` command generates `Outputs/knowledge-export.canvas`
for viewing the vault as an Obsidian Canvas.

The canvas shows:
- Memory branch nodes (colored green)
- Evidence summary nodes (colored purple)
- Edges between linked notes

Open it in Obsidian with Canvas enabled (Settings > Core plugins > Canvas).

This is a generated Output: non-canonical, regeneratable. Do not manually edit it.
To refresh: `agent-knowledge export-canvas --project .`

---

## What stays optional

| Feature | Required | Optional |
|---------|----------|----------|
| YAML frontmatter (basic) | Yes | -- |
| Tags, aliases | No | Yes, improves Obsidian UX |
| Standard markdown links | Yes | -- |
| Wiki-links | No | Yes, only in non-portable notes |
| Dataview queries | No | Yes, add as comments |
| Canvas export | No | Yes, use `export-canvas` |
| Dashboard notes | No | Yes, generated by sync |
| Obsidian installed | No | Yes, optional viewer |

The system works fully without any of the optional features.

---

## Obsidian settings for best experience

If using Obsidian:
1. **Files and links > Use `[[Wikilinks]]`**: OFF (keeps links portable)
2. **Core plugins > Graph view**: ON
3. **Core plugins > Canvas**: ON (for canvas export)
4. **Community plugins > Dataview**: Optional
5. Open the vault at: `~/agent-os/projects/<slug>/`
