User-Defined Command Skill

This skill enables you to create and edit valid Steward user-defined commands — YAML-based command definitions stored as markdown files in the Steward/Commands folder.

File Format

Each command is a markdown file (.md) containing one or more YAML code blocks. The file can also contain plain text, headings, and other markdown content that can be referenced by system prompts.

YAML Schema

Command-Level Fields

Step-Level Fields

Trigger Fields

Command Syntax (Direct Tool Calls)

Steps can use command syntax in the query field to invoke tools directly without an AI round trip. This is the preferred approach for deterministic operations.

Syntax

c:<tool> [--arg=value]...

• c: prefix identifies a direct command call
• <tool> is a short alias (see reference below)
• --key=value pairs map to the tool's input schema
• Multiple commands can be chained with ; separator: c:read --blocks=1; c:conclude
• Quoted values for strings with spaces: --content="hello world"
• Comma-separated values for arrays: --files=Note1.md,Note2.md

Command Reference

c:read Flags

c:search Flags

c:delete Flags

One of --artifact or --files is required.

c:list Flags

c:move Flags

One of --artifact or --files is required, along with --destination.

c:rename Flags

c:grep Flags

Composing Steps

When composing UDC steps, prefer c: command syntax for deterministic operations to avoid unnecessary AI round trips. Reserve natural language queries for steps that require AI reasoning (e.g., content generation, summarization, complex editing decisions).

Use command syntax when the step:

• Reads content from a known location (c:read)
• Searches with specific criteria (c:search)
• Performs file operations: delete, move, rename, list, grep
• Generates speech or images from known text/prompts (c:speech, c:image)

Use natural language when the step:

• Needs AI to generate, summarize, or transform content
• Requires the AI to decide what to edit or how to structure output
• Involves complex reasoning about the content

When c: syntax is used, the step name is still recommended for tool activation but the query is parsed directly, bypassing the AI entirely.

System Prompt Values

The system_prompt field accepts an array of strings. Each string can be:

• Plain text: Direct instructions (e.g., 'Always use formal language')
• Wiki link to a note: '[[Note Name]]' — includes the full content of that note
• Wiki link to a heading: '[[Note Name#Heading]]' — includes content under that heading only
• Wiki link to local heading: '[[#Heading]]' — includes content under a heading in the current command file

Placeholders

These placeholders are replaced with actual values at execution time:

• $from_user — The user's input text
• $file_name — The file name that triggered the command (for triggered commands)
• $steward — The Steward folder path
• $active_file — The file path of the currently active file in the workspace

Examples

Simple multi-step command (with command syntax)

yaml
1command_name: clean-up
2query_required: false
3steps:
4  - name: search
5    query: 'c:search --keywords=Untitled --properties=tag:delete'
6    no_confirm: true
7  - name: vault
8    query: 'c:delete --artifact=latest; c:conclude'
9    no_confirm: true

Simple multi-step command (natural language)

yaml
1command_name: clean-up
2query_required: false
3model: gpt-4o
4steps:
5  - name: search
6    query: 'Notes name starts with Untitled or with tag #delete'
7  - name: vault
8    query: 'Delete them'
9    model: gpt-3.5-turbo

Mixed: command syntax for read, natural language for AI-driven edit

yaml
1command_name: format-lists
2query_required: false
3steps:
4  - name: read
5    query: 'c:read --blocks=-1 --element=list'
6    no_confirm: true
7  - name: edit
8    query: 'Format the list items from the previous step into a clean bulleted list'
9    system_prompt:
10      - 'Rewrite the list using consistent bullet formatting'

Chaining multiple commands in a single step

yaml
1command_name: quick-search-delete
2query_required: false
3steps:
4  - query: 'c:search --keywords=Untitled; c:delete --artifact=latest; c:conclude'
5    no_confirm: true

Question-answering command with system prompt

yaml
1command_name: ask
2query_required: true
3use_tool: false
4system_prompt:
5  - '[[#Instructions]]'
6steps:
7  - query: '$from_user'

Command with step-level system prompts

yaml
1command_name: summarize
2query_required: true
3steps:
4  - name: generate
5    system_prompt:
6      - '[[My Context Note]]'
7      - 'Focus on key takeaways'
8      - 'Use bullet points'
9    query: $from_user

Automated trigger command (with command syntax for read)

yaml
1command_name: generate_flashcards
2query_required: false
3
4triggers:
5  - events: [modify]
6    patterns:
7      tags: '#flashcard-gen'
8
9steps:
10  - name: read
11    query: 'c:read --type=entire --files=$file_name; c:conclude'
12    no_confirm: true
13  - name: edit
14    query: |
15      Generate flashcards from this note content.
16      Format each flashcard as:
17      Q: [question]
18      A: [answer]
19      ---
20      Append the flashcards at the end of the note under a "## Flashcards" heading.

Hidden command (not shown in autocomplete)

yaml
1command_name: internal-helper
2hidden: true
3query_required: true
4steps:
5  - name: generate
6    query: $from_user

Rules

• Note name should use sentence case: capitalize the first letter with spaces between words (e.g., Clean up vault.md).
• Do NOT add any heading at the beginning of the note. A short introduction should be the first content in the file.
• The YAML block MUST be inside a fenced code block with the yaml language tag.
• command_name and steps are always required.
• Step name determines which tools are available. Omitting name uses the default tool set.
• When query_required is true, at least one step must use $from_user in its query.
• When use_tool is false, the core system prompt with tool instructions is not sent — useful for pure conversational commands.
• System prompts and instructions referenced via [[#Heading]] should be placed BELOW the YAML code block, not above it.
• System prompts with wiki links are resolved at execution time. If a linked note or heading does not exist, an error occurs and the command will stop.
• For triggered commands, ensure the query in steps uses $file_name to reference the triggering file.
• Multiple triggers can be defined; any matching trigger will execute the command.
• A command file can contain multiple YAML code blocks, each defining a separate command.
• Markdown content outside YAML blocks (headings, text, lists) can be referenced by system prompts using [[#Heading]] syntax.
• When composing UDC steps, prefer c: command syntax for deterministic operations (read, search, delete, move, rename, list, grep, speech, image) to avoid unnecessary AI round trips. Reserve natural language queries for steps that require AI reasoning.