Repository navigation
AI Authoring Skill
Use this skill to turn a process description into a FlowMotion diagram or update an existing .flow file. The skill tells your AI assistant which schema to use and what to verify. It is not an Obsidian add-on.
- Create a folder named
flowmotion-authoringin the skill location your assistant supports. For a VS Code workspace, use.github/skills/flowmotion-authoring/. - Save the skill text below as
SKILL.mdin that folder. Copy the text inside the code block, including both---lines, but not the outer backticks. - Create a
referencesfolder next toSKILL.md. - Save the two raw JSON files below in
references. These links target FlowMotion 1.0.5. For a different plugin build, get both schemas from that build's tag or commit instead.
| Required file | Use it for |
|---|---|
diagram.schema.json |
Event diagrams with nodes, flows, and dependencies |
storyboard.schema.json |
Storyboards with scenes, beats, and captions |
flowmotion-authoring/
SKILL.md
references/
diagram.schema.json
storyboard.schema.json
For examples and playback rules, give your assistant the Authoring reference and Authoring cookbook. The wiki may describe newer features. Check examples against the schemas and runtime for your version before using them.
Ask your assistant:
Use the FlowMotion authoring skill for version 1.0.5. Create a two-scene storyboard called Project Kickoff. Show a decision going from the project lead to the sponsor, then show the sponsor's approval going back to the lead. Add a caption for each beat and tell me what you validated.
If your assistant does not load skills, paste the skill text into the conversation and attach both schema files. In either case, check which files the assistant read before relying on its output.
The skill does not grant access to Obsidian or your vault. Tell the assistant the target vault or workspace folder, the output path, and whether to create a file or return text for you to paste.
| What the assistant can access | Workflow |
|---|---|
| Obsidian CLI | With the official CLI enabled and FlowMotion active in the target vault, save the diagram to that vault and open it with obsidian vault="My Vault" open path="Diagrams/Project Kickoff.flow". Use a path relative to the vault root. The CLI controls Obsidian Desktop; opening a file does not verify playback. |
| Vault files, no Obsidian CLI | Save the .flow file in the specified vault folder. Open it yourself in Obsidian, or paste the generated flowmotion block into a note and switch to Reading view. To reuse a separate file, see Reusing diagrams. |
| Chat only or no vault access | Ask for the complete .flow contents or a paste-ready flowmotion block. Save or paste it yourself. |
Use the cookbook validation procedure in a matching FlowMotion source checkout with its dependencies installed. To also generate a static SVG preview, run this from the checkout root and replace both paths:
node --import tsx scripts/render-one.ts "/path/to/Project Kickoff.flow" "/path/to/Project Kickoff.svg"This is a repository script, not an Obsidian CLI command. It accepts a standalone diagram, not a whole note or a src: embed. To check motion, scene changes, or Next, play the diagram in Obsidian.
---
name: flowmotion-authoring
description: Create, edit, or review FlowMotion diagrams and storyboards in .flow files or Obsidian flowmotion blocks. Use the supplied FlowMotion schemas and report which validation checks ran.
---
# FlowMotion authoring
1. Identify the target FlowMotion version. Ask for clarification if the build and supplied schemas might not match. Do not mix schemas from different versions.
2. Choose a format. Read `references/storyboard.schema.json` for narrated scenes and beats. Read `references/diagram.schema.json` for nodes, flows, and dependency-driven execution. If the matching schema is missing, ask for it before drafting a YAML or JSON definition.
3. Use the schema to check required fields, allowed values, and nesting. Use the matching authoring reference to check behavior the schema cannot express. For Mermaid or PlantUML, consult FlowMotion's supported text syntax instead; the two JSON schemas do not describe that syntax. State any unsupported requests and offer a supported alternative.
4. Write a complete definition. Use stable IDs and reference those IDs rather than display labels. When editing, preserve existing IDs, references, and unrelated behavior. Do not mix grammars or invent keys.
5. Match the output to the destination. For a standalone `.flow` file, omit Markdown fences. For an inline Obsidian diagram, use a `flowmotion` fence. For a file embed, keep `src` and documented display options in the block. Resolve `src` relative to the note unless it starts with `/`, which means the vault root.
6. Use only the access available. Write to a vault only when the user has specified or approved the destination. If asked to open the result and the Obsidian CLI is available, use `obsidian vault="<vault name>" open path="<vault-relative path>"`. Otherwise give the user the path to open in Obsidian. If you cannot write files, return the complete file contents or a paste-ready block.
7. Validate the standalone definition. For YAML or JSON, check it against the matching JSON Schema if a validator is available. If you have terminal access and a matching FlowMotion source checkout with dependencies installed, run `lintSource` and `buildModel` as described in the [Authoring cookbook](https://github.com/vrsarin/obsidian-flowmotion/wiki/Authoring-Cookbook#validate-a-generated-file). Resolve errors and report warnings. For an embed, validate the referenced diagram separately.
8. Report the format, target version, assumptions, and checks actually performed. Reading a schema is not running a validator. Opening a file with the Obsidian CLI or generating a static SVG does not verify playback. Ask the user to check rendering or playback in Obsidian if you did not observe it.© 2026 @vrsarin. FlowMotion documentation.