diff --git a/README.md b/README.md
index 1a9384c..140696e 100644
--- a/README.md
+++ b/README.md
@@ -45,6 +45,9 @@ Code](https://code.claude.com/docs/en/skills) and
   with live links, quoted and dated.
 - [ibis-design](ibis-design/SKILL.md) — search a design space:
   issues, positions, and arguments.
+- [obsidian-markdown](obsidian-markdown/SKILL.md) — the workspace is
+  an Obsidian vault: one line per paragraph, relative links, no file
+  symlinks you expect Obsidian to show.
 
 ## at the terminal
 
diff --git a/obsidian-markdown/SKILL.md b/obsidian-markdown/SKILL.md
new file mode 100644
index 0000000..b1ce934
--- /dev/null
+++ b/obsidian-markdown/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: obsidian-markdown
+description: Markdown in an Obsidian vault that agents also write — use when an agent writes or edits any .md file in a workspace with a `.obsidian/` folder (notes, READMEs, CONTRIBUTING, AGENTS.md, skills, docs); when someone mentions Obsidian, hard wrap, ragged "poetry" margins, wikilinks, or the vault; when adding a symlink to markdown. Not for Discord or PR text (see grice-maxims).
+---
+
+# Markdown for an Obsidian vault agents write in
+
+The workspace is an [Obsidian](https://obsidian.md/) vault: a `.obsidian/` folder at its root. Dan reads and edits in Obsidian; agents write the same files from a terminal. Write markdown that reads well in Obsidian and on GitHub, and is easy for an agent to edit.
+
+## One line per paragraph
+
+Don't hard-wrap prose. A paragraph is one line; so is each list item. Break lines only between blocks: paragraphs, list items, headings, fences.
+
+Wrapped paragraphs render with a ragged "poetry" margin in Dan's Obsidian, and they make diffs of a one-word edit reflow a whole paragraph. Code blocks keep their line breaks, of course.
+
+When you rewrite a wrapped paragraph, unwrap it. Don't unwrap a whole file you aren't otherwise rewriting: that's a noisy diff in someone else's prose.
+
+## Links
+
+- Standard markdown links with relative paths: `[the webkeys pattern](docs/webkeys.md)`. Obsidian follows them, and GitHub renders them. `[[wikilinks]]` render only in Obsidian.
+- No spaces in file names, so links need no `%20`.
+- Link text says where the link goes (see hypertext-links).
+
+## File names and headings
+
+Obsidian shows file names in tabs, the file explorer, and search, so name files for what's in them.
+
+Headings show in Obsidian's outline pane: make them say something.
+
+## Frontmatter
+
+Obsidian shows YAML frontmatter as Properties. Keep it valid YAML: quote values that contain `: ` or start with a special character.
+
+## Symlinks
+
+From [Obsidian's symlinks page](https://obsidian.md/help/symlinks):
+
+> Obsidian ignores any symlink to a parent folder of the vault, or from one folder in the vault to another folder in the same vault.
+
+> File symlinks (as opposed to folder symlinks) may work, but aren't officially supported at this time.
+
+So a folder symlink inside the vault (`.claude/skills` → `.agents/skills`) is invisible to Obsidian, and that's fine: no duplicates. A file symlink like `AGENTS.md` → `CONTRIBUTING.md` may not show or update in Obsidian. Edit the target, never the link.