Docs/Concepts/Agents and skills

Agents and skills

Agents are markdown files

An agent is a note in the Agents/ folder at the vault root — nothing more exotic than that. Its frontmatter configures how it runs; the body of the file is its system prompt.

Frontmatter fields that matter:

backend — which model/service dispatches the agent: anthropic (the default), anthropic-managed, anthropic-api, or anthropic-oauth (a Claude subscription token) for Anthropic backends; or hermes, openclaw, or pi (local agent-backend endpoints). Defaults to anthropic if omitted.
skills — a list of skill ids attached to this agent (see below).
scope_allow / scope_deny — glob and #tag rules that decide which notes this agent is allowed to touch for in-app dispatch (_private/** is always quarantined, regardless of scope). These are enforced for in-app triggers; they're advisory for an external MCP caller, which isn't bound by a specific agent's scope.
status — pause, resume, or revoke an agent; a paused agent stops firing on save, mention, schedule, re-run, or bulk dispatch.

Triggers fire on a note's save or an @mention (live), on a cron schedule while the app is open, or on a branch you author explicitly.

Skills are reusable instruction packets

A skill lives at Skills/<id>/SKILL.md — frontmatter (name, description) plus a markdown body that is the instructions. Skills are just vault files: portable, synced like any note, editable in place.

Attach a skill to an agent through the agent's skills: frontmatter list (by id), or from the agent's Skills tab in the app. At every dispatch, Solomon composes the agent's effective system prompt: its authored system_prompt, followed by each attached skill's body, in a fixed order — alphabetical by skill id, regardless of the order they're listed in skills:. Editing a skill updates every agent that has it attached, on their very next run — there's no copy/paste and nothing to manually resync. A skills: id that no longer resolves to a real skill is silently skipped at dispatch rather than erroring.

Skills and agents are discoverable over MCP too: skills_list / skill_read for skills, and any MCP client with write access can author a new skill with a plain note_create at Skills/<name>/SKILL.md, or compose a one-shot agent from a skill's body via skill_to_agent.

What agents can actually do: MCP tools

An agent's real capability is the set of MCP tools it can call — the same seventeen read/write tools that back the desktop app's local MCP server and the solomon CLI: search, read, list, run a base query, and (on the write side) create/write/append/edit-section/set-properties/move/delete a note, plus tools to author widgets and turn a skill into an agent. Every one of them refuses _private/, any dot-directory, and Widgets/ in the same way, regardless of which surface is calling.

Propose vs. apply: how agent writes land

By default, every write an agent (or the CLI, or an MCP caller) makes resolves to propose mode: instead of mutating the note directly, it stages a pending change that shows up in Solomon's review panel — and in the iOS Inbox — for you to Accept or Reject. This is the "visibly, never silently" guarantee: agents draft changes, you approve them. This applies uniformly to body edits, frontmatter changes, and structural operations like creating, moving, or deleting a note.

A force-scoped credential (a specific MCP key mode, or the CLI's --token flag) applies writes immediately instead, skipping the review step — useful for a trusted one-shot script, but it's an opt-in escape hatch, not how agent writes behave by default.

Where this shows up

Agents surface (desktop) — the roster + identity sheet where you seed starter agents, tune an agent's backend/tools/skills/scope, and work the review queue.
Operations surface (desktop) — one live view across agents, MCP access, and the CLI: a stream of activity, a dashboard with the approval inbox, and a map of what's been touched recently.
Directory-scoped (non-reusable) guidance is a separate mechanism: an AGENT.md dropped in a folder rides along whenever an agent reads a note there, without being a shareable skill.