user-defined-command

name	user-defined-command
description	Create and edit Steward user-defined commands (UDCs). Use when the user wants to create, modify, or troubleshoot custom command workflows defined as YAML in the Steward/Commands folder.

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.

After creating or updating a UDC note, re-read the file and check the frontmatter status. If it is invalid, use the status error to fix the YAML and re-read again.

YAML Schema

Command-Level Fields

Field	Type	Required	Description
command_name	string	Yes	The name (In kebab-case) to invoke the command (e.g., clean-up invoked as /clean-up)
description	string	No	Short summary shown in / Help next to the command; omit if not needed
query_required	boolean	No	If true, the command requires user input after the prefix. Default: false
model	string	No	Default model for all steps (e.g., gpt-4o, gemini-2.5-flash)
system_prompt	array of strings	No	Additional system prompts applied to all steps
tools	array of strings	No	Super Agent tool names allowed for this command; omit for full set. Use [switch_agent_capacity] for chat-only until the user switches. If more than five tools, activate_tools is added when missing.
hidden	boolean	No	If true, the command does not appear in the autocomplete menu
triggers	array of trigger objects	No	Automatically execute when file events match criteria
cli	object	No	Shell session settings (v2): optional shell executable and whitelist patterns for auto-approved model shell lines (see CLI settings)
steps	array of step objects	Yes	The sequence of steps to execute

Step-Level Fields

Field	Type	Required	Description
name	string	No	Step name that activates corresponding tools: read, edit, search, vault, generate, image, speech. Use generate for direct AI response without tools
query	string	Conditional	The query to send. Required if query_required is true. Use $from_user as placeholder for user input
system_prompt	array of strings	No	Additional system prompts for this step only
model	string	No	Model override for this step
no_confirm	boolean	No	If true, skips confirmation prompts for this step

Trigger Fields

Field	Type	Required	Description
events	array of strings	Yes	Events to watch: create, modify, delete
folders	array of strings	No	Folder paths to watch (e.g., ["Inbox", "Daily Notes"])
patterns	object	No	Pattern matching criteria (all must match)
patterns.tags	string or array	No	Tags to match (e.g., "#todo" or ["#todo", "#review"])
patterns.content	string	No	Regex pattern to match file content
patterns.<property>	string or array	No	Any frontmatter property name and value to match

CLI settings (v2)

Use the root-level cli field when a command runs shell tools and you want to control how the local shell behaves.

cli:
  shell: /bin/zsh # optional: override the shell executable for new sessions
  whitelist:
    - 'yt-dlp*'
    - 'Get-Content*'
    - 'rm *_temp_transcript*'
    - 'cat _temp_transcript.en.srt'

cli.shell

Optional path to the shell executable when Steward spawns a new session for this command. Falls back to global Steward CLI settings when omitted.

cli.whitelist

Optional list of patterns (max 50 entries). When the Super Agent sends a model shell line in transcript mode (not interactive terminal mode), a matching pattern skips the confirmation prompt.

Matching rules (applied to the trimmed command line):

Pattern shape	Behavior
No *	Exact match only (e.g. pwd matches pwd, not pwd -L)
Contains *	Glob match: each * matches any run of characters

Examples:

• Get-Content* — commands starting with Get-Content
• rm *_temp_transcript.en.srt — rm followed by optional flags/whitespace, then that file path
• rm *_temp_transcript* — rm commands that mention _temp_transcript (quoted or unquoted)
• *_temp_transcript.en.srt — any command that ends with that filename

Notes:

• An entry cannot be only * wildcards; include at least one literal character.
• Empty shell lines never match (opening an interactive shell still requires confirmation).
• Interactive terminal commands always require confirmation, even when whitelisted.

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:edit --mode=replace_by_lines
• Quoted values for strings with spaces: --content="hello world"
• Comma-separated values for arrays: --files=Note1.md,Note2.md

Command Reference

Alias	Tool	Flags
c:read	Content Reading	--type, --files, --element, --blocks, --pattern
c:search	Search	--keywords, --filenames, --folders, --properties
c:delete	Delete	--artifact, --files
c:list	List	--folder, --pattern
c:move	Move	--artifact, --files, --destination
c:rename	Rename	--artifact, --pattern, --replace
c:grep	Grep	--pattern, --paths, --caseSensitive, --isRegex, --contextLines, --maxResults
c:speech	Speech	--text
c:image	Image	--prompt

c:read Flags

Flag	Type	Default	Description
--type	string	above	One of: above, below, pattern, entire, frontmatter
--files	string[]	[]	Comma-separated file names to read from
--artifact	string	—	Artifact ID (or latest) to resolve file names from.
--element	string	null	One of: paragraph, table, code, list, blockquote, image, heading
--blocks	number	1	Number of blocks to read. Use -1 for all content from current position
--pattern	string	—	RegExp pattern (required when --type=pattern)

c:search Flags

Flag	Type	Description
--keywords	string[]	Comma-separated search terms
--filenames	string[]	Comma-separated file names to search for
--folders	string[]	Comma-separated folder paths to search within
--properties	json	Property filters in name:value format, comma-separated (e.g. tag:todo,status:active)

c:delete Flags

Flag	Type	Description
--artifact	string	Artifact ID containing files to delete
--files	string[]	Comma-separated file paths to delete

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

c:list Flags

Flag	Type	Description
--folder	string	Folder path to list files from
--pattern	string	RegExp pattern to filter file names

c:move Flags

Flag	Type	Description
--artifact	string	Artifact ID containing files to move
--files	string[]	Comma-separated file paths to move
--destination	string	Destination folder path

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

c:rename Flags

Flag	Type	Description
--artifact	string	Artifact ID containing files to rename
--pattern	string	Pattern to match in file names
--replace	string	Replacement text for matched pattern

c:grep Flags

Flag	Type	Default	Description
--pattern	string	—	Text or RegExp pattern to search for in file content
--paths	string[]	all	Comma-separated files, folders, or glob patterns to search (e.g. src, docs/a.md, **/*.ts)
--caseSensitive	boolean	true	Whether matching is case-sensitive
--isRegex	boolean	false	Treat --pattern as a regular expression instead of literal text
--contextLines	number	0	Number of lines before and after each match to include (0-10)
--maxResults	number	50	Maximum returned matches (1-500). totalMatches may be higher when results are truncated

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)

command_name: clean-up
description: Remove Untitled or tagged notes via search then delete.
query_required: false
steps:
  - name: search
    query: 'c:search --keywords=Untitled --properties=tag:delete'
    no_confirm: true
  - name: vault
    query: 'c:delete --artifact=latest'
    no_confirm: true

Simple multi-step command (natural language)

command_name: clean-up
query_required: false
model: gpt-4o
steps:
  - name: search
    query: 'Notes name starts with Untitled or with tag #delete'
  - name: vault
    query: 'Delete them'
    model: gpt-3.5-turbo

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

command_name: format-lists
query_required: false
steps:
  - name: read
    query: 'c:read --blocks=-1 --element=list'
    no_confirm: true
  - name: edit
    query: 'Format the list items from the previous step into a clean bulleted list'
    system_prompt:
      - 'Rewrite the list using consistent bullet formatting'

Chaining multiple commands in a single step

command_name: quick-search-delete
query_required: false
steps:
  - query: 'c:search --keywords=Untitled; c:delete --artifact=latest'
    no_confirm: true

Conditional steps

Run a step only when its when condition(s) match user input. Multiple conditions use OR semantics — the step runs if any condition is true. Omit when to always run the step.

Supported conditions:

• empty_from_user — user input is empty (after trim)
• matches: '<regex>' — input matches the pattern
• not_matches: '<regex>' — input does not match the pattern

command_name: explain-video
query_required: false
steps:
  - name: check-yt-dlp
    query: 'c:shell --argsLine="yt-dlp --version"'
    when:
      - empty_from_user
      - not_matches: '(youtube\.com|youtu\.be)'
    no_confirm: true
  - query: '$from_user'

not_matches alone is often enough — empty input will not match a URL pattern.

Question-answering command with system prompt

command_name: ask
description: Chat with instructions from this note until full tools are enabled.
query_required: true
tools:
  - switch_agent_capacity
system_prompt:
  - '[[#Instructions]]'
steps:
  - query: '$from_user'

Command with step-level system prompts

command_name: summarize
query_required: true
steps:
  - name: generate
    system_prompt:
      - '[[My Context Note]]'
      - 'Focus on key takeaways'
      - 'Use bullet points'
    query: $from_user

Automated trigger command (with command syntax for read)

command_name: generate_flashcards
query_required: false

triggers:
  - events: [modify]
    patterns:
      tags: '#flashcard-gen'

steps:
  - name: read
    query: 'c:read --type=entire --files=$file_name'
    no_confirm: true
  - name: edit
    query: |
      Generate flashcards from this note content.
      Format each flashcard as:
      Q: [question]
      A: [answer]
      ---
      Append the flashcards at the end of the note under a "## Flashcards" heading.

Hidden command (not shown in autocomplete)

command_name: internal-helper
hidden: true
query_required: true
steps:
  - name: generate
    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.
• After creating or editing a UDC file, re-read it and verify the frontmatter status is valid.
• 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 tools is [switch_agent_capacity], only that tool is available until the user confirms switching to full agent mode — 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, exists, speech, image, shell) to avoid unnecessary AI round trips. Reserve natural language queries for steps that require AI reasoning.