zhitongblog / solomd

SoloMD — Markdown vault skill

When to use this skill

Trigger this skill when the user wants to:

• Browse / read / search a folder of Markdown notes (their personal
  knowledge base, journal, project docs, etc.).

• Maintain the vault — generate weekly summaries, extract TODOs across
  notes, suggest wikilinks, find orphan notes, etc.

• Edit notes with version control — every write lands as an AutoGit
  commit (no network); past revisions are queryable via autogit_log /
  autogit_diff.

• Share a note publicly via a solomd.app/share/?repo=…&path=… link
  that renders the file from a public GitHub repo (no SoloMD account
  required for the viewer).

If the user just wants generic file I/O on a directory, the built-in
filesystem tools are simpler. This skill is specifically for
Markdown-as-a-vault workflows.

Setup (one-time)

The skill assumes solomd-mcp is installed and registered as a user-scope
MCP server (~/.claude.json). If /mcp doesn't list solomd, run:

bash ~/.claude/skills/solomd/install.sh

This installs the binary (via cargo install solomd-mcp on macOS or
downloading the prebuilt binary from
https://github.com/zhitongblog/solomd/releases/latest on Linux / Windows)
and registers a solomd server pointing at your notes folder via
claude mcp add --scope user (falling back to patching ~/.claude.json
directly when the claude CLI isn't on PATH).

Default mode is read-only. To enable the 3 write tools, re-register with
--allow-write:

claude mcp remove solomd -s user
claude mcp add --scope user solomd -- \
  ~/.claude/bin/solomd-mcp --workspace ~/your-notes --allow-write

Tools available

All exposed via the solomd: prefix.

Read tools (always available)

• solomd:list_notes(workspace?, subdir?, limit=100) — list .md files.
• solomd:read_note(workspace?, path) — full contents.

• solomd:search(workspace?, query, mode="literal"|"regex", limit=200) —
  substring or regex search; returns matches with line numbers.

• solomd:get_backlinks(workspace?, note_name) — every note that
  references [[<name>]].

• solomd:list_tags(workspace?) — #tag aggregation with counts.
• solomd:get_outline(workspace?, path) — H1/H2/H3 structure.

• solomd:autogit_log(workspace?, path, limit=20) — per-note commit
  history. Each save in SoloMD is a commit.

• solomd:autogit_diff(workspace?, path, from_revision, to_revision="HEAD") —
  diff between revisions of one note.

• solomd:sync_status(workspace?) — git remote ahead/behind, dirty files,
  conflict state.

• solomd:share_url(workspace?, path) — generate a public read-only
  solomd.app/share/… link (requires the workspace to be pushed to a
  public GitHub repo).

• solomd:read_agent_trace(workspace?, run_id) — replay a past agent
  recipe run from its .solomd/agent-runs/<run-id>/trace.jsonl.

Write tools (need --allow-write on the server)

• solomd:write_note(workspace?, path, content) — create or overwrite.
  Returns the diff against any prior version.

• solomd:append_to_note(workspace?, path, content) — append; idempotent
  (won't duplicate a block already present at the bottom).

• solomd:autogit_rollback(workspace?, path, revision) — restore a note
  to a past commit.

Multi-vault

If the server was started with multiple --workspace alias=/path flags,
pass the workspace argument (e.g. workspace: "work" or
workspace: "home") to disambiguate. Without one, the first registered
workspace is the default.

Patterns

Browse before acting

When the user asks "do X across my notes", first call list_notes or
search to confirm the scope. The vault might be 30 notes or 3,000 — your
plan should match the size.

Always cite

When responding with information from notes, link them back as
[[note-name]] (the wikilink format SoloMD uses). The user can click
straight back to the source. Example:

Your three open architecture decisions are tracked in [[adr-001-storage]],
[[adr-003-rate-limits]], and [[adr-007-streaming-api]].

Writes go through accept/reject — surface this

If the user is also running the SoloMD desktop app on the same vault,
every write tool call lands on an agent/<recipe>/<run-id> AutoGit branch
the user must accept in Settings → Recipes → Pending before it touches
main. Tell the user this is happening so they know to check the app:

I've written the summary to weekly/2026-W22.md — it's pending on an
AutoGit branch (agent/claude-code/abc123). Open SoloMD →
Settings → Recipes → Pending to accept or reject before it lands on main.

If they're not running the app, the write lands on a branch they can
inspect manually with git branch | grep agent/ and git merge /
git branch -D as needed.

Watch the write cap

The server enforces a per-run write cap (default 5, hard ceiling 50). If
you hit it, the call returns an error and no further writes succeed in
that session. Plan multi-write actions in a single dispatch rather than
fanning out one-at-a-time.

Starter recipes

This skill ships 11 reference YAML recipes at
[`recipes/`](recipes/). They're the same files as the SoloMD Skill Pack
zip — copy any of them into <workspace>/.solomd/agents/ to enable inside
SoloMD (the app's recipe runner watches that directory).

For use from Claude Code directly, treat the YAML as documentation: adapt
the prompt: block into the user's request and call the appropriate MCP
tools yourself. Example — 01-weekly-review.yml becomes:

Use list_notes to find every daily/*.md from the past 7 days, read
each, and write weekly/{ISO-week}.md with Themes / Decisions / Open
threads sections, citing each daily as [[YYYY-MM-DD]].

Recipe catalog

When NOT to use this skill

• The user wants generic shell or filesystem ops on non-Markdown content —
  use the built-in Bash / Read / Edit tools.

• The user is editing a single file they've already opened — direct
  Edit is more efficient than going through read_note / write_note.

• The vault isn't actually a SoloMD vault and the user doesn't care about
  wikilinks / tags / AutoGit — the 5 SoloMD-only tools become no-ops
  (still useful for the other 8).

About SoloMD

SoloMD is a free, MIT-licensed Markdown editor.
The MCP server you just installed is bundled with the desktop app —
get the app for the visual Agent panel, the accept/reject UI, and
AutoGit history navigation.

• macOS: https://github.com/zhitongblog/solomd/releases/latest/download/SoloMD4.5.6universal.dmg
• Windows: https://github.com/zhitongblog/solomd/releases/latest/download/SoloMD4.5.6x64_en-US.msi
• Windows ARM64: https://github.com/zhitongblog/solomd/releases/latest/download/SoloMD4.5.6arm64_en-US.msi
• Linux: see https://github.com/zhitongblog/solomd/releases/latest