YAML blocks in markdown

Steward stores structured configuration inside markdown notes as fenced YAML code blocks (```yaml). You edit everything in Obsidian like any other note—headings, prose, links—while Steward reads the YAML blocks as machine-readable definitions.

Why YAML blocks instead of separate files?

Obsidian is built around notes. It does not treat standalone .yaml or .json files as first-class vault content the way it treats markdown. A separate config file would be harder to find, harder to annotate, and would not sit naturally beside the instructions you write for yourself or for the model.

YAML blocks inside a note give you both:

• Transparency — You see exactly what Steward uses. The structure is visible in Reading view and in the editor, with syntax highlighting when the fence is tagged yaml.
• Context in one place — Prose, headings, and Obsidian links can live in the same note as the definition. User-defined commands often keep system prompts under headings below the YAML block and reference them with [[#Heading]].
• Obsidian-native editing — No plugin-specific file type. Copy, search, link, and version-control notes the way you already work.

Steward uses this pattern for user-defined commands, Memory tool instructions, widget project definitions, guardrails rules, and other features that need more structure than a single property list.

Why not frontmatter only?

Note frontmatter (YAML between --- at the top of a file) works well for simple metadata: enabled, version, status, tags, and a few flat fields.

Many Steward features need more than that:

Need	Why frontmatter falls short
Nested structures	Commands have steps arrays, each step with its own fields; widgets split manifest, actions, actors, and agents across blocks.
Multiple definitions in one note	One command file can define several slash commands, each in its own YAML fence. Memory can hold many tool_instruction blocks—one per tool (or more).
Mixed machine and human content	Tool instructions use YAML for guidelines while headings and prose explain intent to you and the model. Frontmatter cannot hold that body content.
Large or repeated blocks	Long guideline lists or multi-step workflows are easier to read and edit in dedicated fences than crammed into a single frontmatter document.

Frontmatter is still used where it fits: status (validation result), enabled, version, and similar note-level flags. The heavy structure lives in YAML fences in the note body.

Block format

Use a standard markdown code fence with the yaml language tag:

```yaml
command_name: my-command
description: Short summary for Help.
steps:
  - query: Hello
```

Steward scans the note for ```yaml or ```yml fences (case-insensitive), parses each block, and validates it against the schema for that feature (command fields, name: tool_instruction, widget block types, and so on).

You can combine several blocks in one file—for example, multiple commands in Steward/Commands, or multiple tool instruction blocks in Steward/Memory/Tool instructions.md. Markdown outside the fences is ignored by the parser unless another feature explicitly references it (such as system prompts linked from a command).

Auto-validation and status

When a note that Steward manages is saved or edited, the plugin re-parses its YAML blocks, validates them, and updates the note’s frontmatter status field:

status value	Meaning
✅ Valid	All required blocks parsed and passed validation.
Invalid: …	One or more errors (syntax, unknown fields, wrong block type, schema mismatch). The message summarizes what to fix.

This applies when you save the file and when Steward (or the model via the edit tool) updates the YAML. After editing a definition, re-open or re-read the note and check status before relying on the change.

If validation fails, Steward does not load the invalid blocks for that feature until the errors are fixed.

Where YAML blocks are used

Feature	Wiki	Typical location
User-defined commands	User-defined commands	Steward/Commands/
Tool instructions (Memory)	Memory	Steward/Memory/Tool instructions.md
Widget project definitions	Widgets and visualizations	Widget project Widget.md

For field-level reference and examples, use the feature pages above. This page describes the shared YAML-in-markdown pattern they all use.

Tips

• Keep one concern per block type (e.g. one command per YAML fence in command files; name: tool_instruction per tool block in Memory).
• Put human-readable instructions below or beside YAML blocks when you link to them with [[#Heading]], so the command definition stays at the top and links resolve predictably.
• After Steward edits a YAML structure for you, confirm frontmatter status is ✅ Valid before testing the feature in chat.