pi-config/skills/obsidian-sorter/SKILL.md

name, description

name	description
obsidian-sorter	File notes into Sam's Obsidian vault. Use when adding, capturing, or organizing notes in Obsidian; when asked "sort my inbox", "add this to my notes", "where does this go", or when a thought/idea/plan should be recorded. Handles the proposal-and-approve workflow where the vault owner ticks a checkbox before anything moves.

Obsidian Sorter

Files notes into Sam's Obsidian vault at ~/obsidian on host .27.

Nothing is ever filed without the owner's approval. You write a note into the inbox; a watcher writes a proposal into the note's frontmatter; Sam ticks approved: true in Obsidian; the watcher files it.

Where things live

Thing	Location
Vault	.27 → ~/obsidian (synced to Gitea sam/obsidian-vault)
Sorter code	.27 → ~/obsidian-sorter/
Watcher service	.27 → systemctl --user obsidian-sorter (always running, 10s poll)
Command	.27 → ~/bin/obsidian-sort
Sort log	.27 → ~/obsidian/010 inbox/_sort log.md

The sorter runs on .27 because that is where the vault lives. From another machine, reach it over SSH:

ssh sam@192.168.20.27 'obsidian-sort scan'

The taxonomy — type mirrors folder

Refer to the existing folder listing to see subfolders — this table is the reference for the pattern.

Folder	Type	Meaning
200 projects/	project	Work in progress — something being built
300 areas/	area	Ongoing interest with documentation and notes
400 Personal Family/	family	Family / strictly non-work
100 Table of Contents/	index	Navigation notes only
000 daily/	daily	Chronological daily notes
500 archive/	archive	Inactive material
Clippings/	clipping	Browser-extension captures
010 inbox/	note	Unsorted placeholder

A note's type always equals its folder. Never invent a type. These are retired and must not be used: subject, tool, container, machine, backup-system, website, service, storage, network-component, person.

The lifecycle

IDEA (not started)   -> 200 projects/260 Ideas to Build Create Make
BEING BUILT          -> 200 projects/250 Electronics
FINISHED             -> 300 areas/...

Adding a note

Write it into 010 inbox/ on .27 using the generic template. Do not choose a folder or a type — the sorter decides.

---
created: YYYY-MM-DD HH:MM
type: note
tags: []
aliases: []
---
# [[Note Title]]

A paragraph or two describing what this actually is. The more clearly you
describe it, the better it files.

Write it via SSH, e.g.:

ssh sam@192.168.20.27 'cat > "$HOME/obsidian/010 inbox/My Note.md"' << 'MD'
---
created: 2026-01-01 12:00
type: note
tags: []
aliases: []
---
# [[My Note]]

The content.
MD

Within ~10 seconds the watcher adds a proposal:

proposed_folder: 200 projects/250 Electronics
proposed_toc: 100 Table of Contents/Projects.md → Ideas
proposed_tags: [electronics, bluetooth]
confidence: 0.87
approved: false

Triggering a check

The watcher polls every 10 seconds, so normally you do nothing. To force it:

ssh sam@192.168.20.27 'obsidian-sort watch --once'   # one pass
ssh sam@192.168.20.27 'obsidian-sort'                # dry run: show plans
ssh sam@192.168.20.27 'obsidian-sort apply'          # file (prompts)
ssh sam@192.168.20.27 'obsidian-sort apply --yes'    # file, no prompt
ssh sam@192.168.20.27 'obsidian-sort scan'           # vault summary

Steering the sorter

Sam's own tags always win. Tag a note and the sorter obeys:

Tag on the note	Effect
project	constrained to the 200 projects/ bucket
family / personal	constrained to 400 Personal Family/
business-idea	pinned to 400 Personal Family/410 Business Ideas
recipe	pinned to 400 Personal Family/450 Recipes

Tag pinning costs $0 — no model call is made.

Rules

• Never set type to anything other than note when adding to the inbox.
• Never move notes into folders yourself — that is the sorter's job.
• Never modify proposed_* or approved fields. That is Sam's decision.
• Never touch .trash/.
• Files starting with _ in the inbox are internal (the sort log) — ignore them.
• If asked where something belongs, use propose rather than guessing:

ssh sam@192.168.20.27 'obsidian-sort propose "010 inbox/My Note.md" --jev'

Troubleshooting

ssh sam@192.168.20.27 'systemctl --user status obsidian-sorter'
ssh sam@192.168.20.27 'journalctl --user -u obsidian-sorter -n 50'
ssh sam@192.168.20.27 'cat "$HOME/obsidian/010 inbox/_sort log.md" | tail -30'

If the service is stopped: systemctl --user start obsidian-sorter.