diff --git a/skills/note-taking/obsidian/SKILL.md b/skills/note-taking/obsidian/SKILL.md index 0c557dd9ff..37bceb9f4b 100644 --- a/skills/note-taking/obsidian/SKILL.md +++ b/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 -VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}" -cat "$VAULT/Note Name.md" -``` +Use `read_file` with the resolved absolute path to the note. Prefer this over `cat` because it provides line numbers and pagination. ## List notes -```bash -VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}" +Use `search_files` with `target: "files"` and the resolved vault path. Prefer this over `find` or `ls`. -# All notes -find "$VAULT" -name "*.md" -type f - -# In a specific folder -ls "$VAULT/Subfolder/" -``` +- To list all markdown notes, use `pattern: "*.md"` under the vault path. +- To list a subfolder, search under that subfolder's absolute path. ## Search -```bash -VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}" +Use `search_files` for both filename and content searches. Prefer this over `grep`, `find`, or `ls`. -# By filename -find "$VAULT" -name "*.md" -iname "*keyword*" - -# By content -grep -rli "keyword" "$VAULT" --include="*.md" -``` +- For filenames, use `search_files` with `target: "files"` and a filename `pattern`. +- 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. ## Create a note -```bash -VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}" -cat > "$VAULT/New Note.md" << 'ENDNOTE' -# Title - -Content here. -ENDNOTE -``` +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. ## Append to a note -```bash -VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}" -echo " -New content here." >> "$VAULT/Existing Note.md" -``` +Prefer a native file-tool workflow when it is not awkward: + +- Read the target note with `read_file`. +- 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 diff --git a/website/docs/reference/skills-catalog.md b/website/docs/reference/skills-catalog.md index 221b07fdc0..2bc686e38d 100644 --- a/website/docs/reference/skills-catalog.md +++ b/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 diff --git a/website/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian.md b/website/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian.md index 38ff151902..56e6292b22 100644 --- a/website/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian.md +++ b/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 -VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}" -cat "$VAULT/Note Name.md" -``` +Use `read_file` with the resolved absolute path to the note. Prefer this over `cat` because it provides line numbers and pagination. ## List notes -```bash -VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}" +Use `search_files` with `target: "files"` and the resolved vault path. Prefer this over `find` or `ls`. -# All notes -find "$VAULT" -name "*.md" -type f - -# In a specific folder -ls "$VAULT/Subfolder/" -``` +- To list all markdown notes, use `pattern: "*.md"` under the vault path. +- To list a subfolder, search under that subfolder's absolute path. ## Search -```bash -VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}" +Use `search_files` for both filename and content searches. Prefer this over `grep`, `find`, or `ls`. -# By filename -find "$VAULT" -name "*.md" -iname "*keyword*" - -# By content -grep -rli "keyword" "$VAULT" --include="*.md" -``` +- For filenames, use `search_files` with `target: "files"` and a filename `pattern`. +- 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. ## Create a note -```bash -VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}" -cat > "$VAULT/New Note.md" << 'ENDNOTE' -# Title - -Content here. -ENDNOTE -``` +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. ## Append to a note -```bash -VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}" -echo " -New content here." >> "$VAULT/Existing Note.md" -``` +Prefer a native file-tool workflow when it is not awkward: + +- Read the target note with `read_file`. +- 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