docs(skills): modernize Obsidian file workflows

skills/note-taking/obsidian/SKILL.md

@@ -1,65 +1,59 @@
 ---
 name: obsidian
-description: Read, search, and create notes in the Obsidian vault.
+description: Read, search, create, and edit notes in the Obsidian vault.
 ---
 
 # Obsidian Vault
 
-**Location:** Set via `OBSIDIAN_VAULT_PATH` environment variable (e.g. in `~/.hermes/.env`).
+Use this skill for filesystem-first Obsidian vault work: reading notes, listing notes, searching note files, creating notes, appending content, and adding wikilinks.
 
-If unset, defaults to `~/Documents/Obsidian Vault`.
+## Vault path
 
-Note: Vault paths may contain spaces - always quote them.
+Use a known or resolved vault path before calling file tools.
+
+The documented vault-path convention is the `OBSIDIAN_VAULT_PATH` environment variable, for example from `~/.hermes/.env`. If it is unset, use `~/Documents/Obsidian Vault`.
+
+File tools do not expand shell variables. Do not pass paths containing `$OBSIDIAN_VAULT_PATH` to `read_file`, `write_file`, `patch`, or `search_files`; resolve the vault path first and pass a concrete absolute path. Vault paths may contain spaces, which is another reason to prefer file tools over shell commands.
+
+If the vault path is unknown, `terminal` is acceptable for resolving `OBSIDIAN_VAULT_PATH` or checking whether the fallback path exists. Once the path is known, switch back to file tools.
 
 ## Read a note
 
-```bash
+Use `read_file` with the resolved absolute path to the note. Prefer this over `cat` because it provides line numbers and pagination.
-VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}"
-cat "$VAULT/Note Name.md"
-```
 
 ## List notes
 
-```bash
+Use `search_files` with `target: "files"` and the resolved vault path. Prefer this over `find` or `ls`.
-VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}"
 
-# All notes
+- To list all markdown notes, use `pattern: "*.md"` under the vault path.
-find "$VAULT" -name "*.md" -type f
+- To list a subfolder, search under that subfolder's absolute path.
-
-# In a specific folder
-ls "$VAULT/Subfolder/"
-```
 
 ## Search
 
-```bash
+Use `search_files` for both filename and content searches. Prefer this over `grep`, `find`, or `ls`.
-VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}"
 
-# By filename
+- For filenames, use `search_files` with `target: "files"` and a filename `pattern`.
-find "$VAULT" -name "*.md" -iname "*keyword*"
+- For note contents, use `search_files` with `target: "content"`, the content regex as `pattern`, and `file_glob: "*.md"` when you want to restrict matches to markdown notes.
-
-# By content
-grep -rli "keyword" "$VAULT" --include="*.md"
-```
 
 ## Create a note
 
-```bash
+Use `write_file` with the resolved absolute path and the full markdown content. Prefer this over shell heredocs or `echo` because it avoids shell quoting issues and returns structured results.
-VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}"
-cat > "$VAULT/New Note.md" << 'ENDNOTE'
-# Title
-
-Content here.
-ENDNOTE
-```
 
 ## Append to a note
 
-```bash
+Prefer a native file-tool workflow when it is not awkward:
-VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}"
+
-echo "
+- Read the target note with `read_file`.
-New content here." >> "$VAULT/Existing Note.md"
+- Use `patch` for an anchored append when there is stable context, such as adding a section after an existing heading or appending before a known trailing block.
-```
+- Use `write_file` when rewriting the whole note is clearer than constructing a fragile patch.
+
+For an anchored append with `patch`, replace the anchor with the anchor plus the new content.
+
+For a simple append with no stable context, `terminal` is acceptable if it is the clearest safe option.
+
+## Targeted edits
+
+Use `patch` for focused note changes when the current content gives you stable context. Prefer this over shell text rewriting.
 
 ## Wikilinks
 

website/docs/reference/skills-catalog.md

@@ -136,7 +136,7 @@ If a skill is missing from this list but present in the repo, the catalog is reg
 
 | Skill | Description | Path |
 |-------|-------------|------|
-| [`obsidian`](/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian) | Read, search, and create notes in the Obsidian vault. | `note-taking/obsidian` |
+| [`obsidian`](/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian) | Read, search, create, and edit notes in the Obsidian vault. | `note-taking/obsidian` |
 
 ## productivity
 

website/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian.md

@@ -1,14 +1,14 @@
 ---
-title: "Obsidian — Read, search, and create notes in the Obsidian vault"
+title: "Obsidian — Read, search, create, and edit notes in the Obsidian vault"
 sidebar_label: "Obsidian"
-description: "Read, search, and create notes in the Obsidian vault"
+description: "Read, search, create, and edit notes in the Obsidian vault"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
 # Obsidian
 
-Read, search, and create notes in the Obsidian vault.
+Read, search, create, and edit notes in the Obsidian vault.
 
 ## Skill metadata
 
@@ -25,61 +25,55 @@ The following is the complete skill definition that Hermes loads when this skill
 
 # Obsidian Vault
 
-**Location:** Set via `OBSIDIAN_VAULT_PATH` environment variable (e.g. in `~/.hermes/.env`).
+Use this skill for filesystem-first Obsidian vault work: reading notes, listing notes, searching note files, creating notes, appending content, and adding wikilinks.
 
-If unset, defaults to `~/Documents/Obsidian Vault`.
+## Vault path
 
-Note: Vault paths may contain spaces - always quote them.
+Use a known or resolved vault path before calling file tools.
+
+The documented vault-path convention is the `OBSIDIAN_VAULT_PATH` environment variable, for example from `~/.hermes/.env`. If it is unset, use `~/Documents/Obsidian Vault`.
+
+File tools do not expand shell variables. Do not pass paths containing `$OBSIDIAN_VAULT_PATH` to `read_file`, `write_file`, `patch`, or `search_files`; resolve the vault path first and pass a concrete absolute path. Vault paths may contain spaces, which is another reason to prefer file tools over shell commands.
+
+If the vault path is unknown, `terminal` is acceptable for resolving `OBSIDIAN_VAULT_PATH` or checking whether the fallback path exists. Once the path is known, switch back to file tools.
 
 ## Read a note
 
-```bash
+Use `read_file` with the resolved absolute path to the note. Prefer this over `cat` because it provides line numbers and pagination.
-VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}"
-cat "$VAULT/Note Name.md"
-```
 
 ## List notes
 
-```bash
+Use `search_files` with `target: "files"` and the resolved vault path. Prefer this over `find` or `ls`.
-VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}"
 
-# All notes
+- To list all markdown notes, use `pattern: "*.md"` under the vault path.
-find "$VAULT" -name "*.md" -type f
+- To list a subfolder, search under that subfolder's absolute path.
-
-# In a specific folder
-ls "$VAULT/Subfolder/"
-```
 
 ## Search
 
-```bash
+Use `search_files` for both filename and content searches. Prefer this over `grep`, `find`, or `ls`.
-VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}"
 
-# By filename
+- For filenames, use `search_files` with `target: "files"` and a filename `pattern`.
-find "$VAULT" -name "*.md" -iname "*keyword*"
+- For note contents, use `search_files` with `target: "content"`, the content regex as `pattern`, and `file_glob: "*.md"` when you want to restrict matches to markdown notes.
-
-# By content
-grep -rli "keyword" "$VAULT" --include="*.md"
-```
 
 ## Create a note
 
-```bash
+Use `write_file` with the resolved absolute path and the full markdown content. Prefer this over shell heredocs or `echo` because it avoids shell quoting issues and returns structured results.
-VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}"
-cat > "$VAULT/New Note.md" << 'ENDNOTE'
-# Title
-
-Content here.
-ENDNOTE
-```
 
 ## Append to a note
 
-```bash
+Prefer a native file-tool workflow when it is not awkward:
-VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}"
+
-echo "
+- Read the target note with `read_file`.
-New content here." >> "$VAULT/Existing Note.md"
+- Use `patch` for an anchored append when there is stable context, such as adding a section after an existing heading or appending before a known trailing block.
-```
+- Use `write_file` when rewriting the whole note is clearer than constructing a fragile patch.
+
+For an anchored append with `patch`, replace the anchor with the anchor plus the new content.
+
+For a simple append with no stable context, `terminal` is acceptable if it is the clearest safe option.
+
+## Targeted edits
+
+Use `patch` for focused note changes when the current content gives you stable context. Prefer this over shell text rewriting.
 
 ## Wikilinks