diff --git a/apps/x/packages/core/src/application/assistant/skills/builtin-tools/skill.ts b/apps/x/packages/core/src/application/assistant/skills/builtin-tools/skill.ts
index 7a777ee9..ceb2f940 100644
--- a/apps/x/packages/core/src/application/assistant/skills/builtin-tools/skill.ts
+++ b/apps/x/packages/core/src/application/assistant/skills/builtin-tools/skill.ts
@@ -5,21 +5,19 @@ Load this skill when creating or modifying agents that need access to Rowboat's
 
 ## Available Builtin Tools
 
-Agents can use builtin tools by declaring them in the \`"tools"\` object with \`"type": "builtin"\` and the appropriate \`"name"\`.
+Agents can use builtin tools by declaring them in the YAML frontmatter \`tools\` section with \`type: builtin\` and the appropriate \`name\`.
 
 ### executeCommand
 **The most powerful and versatile builtin tool** - Execute any bash/shell command and get the output.
 
 **Security note:** Commands are filtered through \`.rowboat/config/security.json\`. Populate this file with allowed command names (array or dictionary entries). Any command not present is blocked and returns exit code 126 so the agent knows it violated the policy.
 
-**Agent tool declaration:**
-\`\`\`json
-"tools": {
-  "bash": {
-    "type": "builtin",
-    "name": "executeCommand"
-  }
-}
+**Agent tool declaration (YAML frontmatter):**
+\`\`\`yaml
+tools:
+  bash:
+    type: builtin
+    name: executeCommand
 \`\`\`
 
 **What it can do:**
@@ -51,66 +49,78 @@ Agents can use builtin tools by declaring them in the \`"tools"\` object with \`
 - Full bash shell features are available (variables, loops, conditionals, etc.)
 - Tools like jq, yq, awk, sed can parse and transform data
 
-**Example agent with executeCommand:**
-\`\`\`json
-{
-  "name": "arxiv-feed-reader",
-  "description": "A feed reader for the arXiv",
-  "model": "gpt-5.1",
-  "instructions": "Extract latest papers from the arXiv feed and summarize them. Use curl to fetch the RSS feed, then parse it with yq and jq:\n\ncurl -s https://rss.arxiv.org/rss/cs.AI | yq -p=xml -o=json | jq -r '.rss.channel.item[] | select(.title | test(\"agent\"; \"i\")) | \"\\(.title)\\n\\(.link)\\n\\(.description)\\n\"'\n\nThis will give you papers containing 'agent' in the title.",
-  "tools": {
-    "bash": {
-      "type": "builtin",
-      "name": "executeCommand"
-    }
-  }
-}
+**Example agent with executeCommand** (\`agents/arxiv-feed-reader.md\`):
+\`\`\`markdown
+---
+model: gpt-5.1
+tools:
+  bash:
+    type: builtin
+    name: executeCommand
+---
+# arXiv Feed Reader
+
+Extract latest papers from the arXiv feed and summarize them.
+
+Use curl to fetch the RSS feed, then parse it with yq and jq:
+
+\\\`\\\`\\\`bash
+curl -s https://rss.arxiv.org/rss/cs.AI | yq -p=xml -o=json | jq -r '.rss.channel.item[] | select(.title | test("agent"; "i")) | "\\(.title)\\n\\(.link)\\n\\(.description)\\n"'
+\\\`\\\`\\\`
+
+This will give you papers containing 'agent' in the title.
 \`\`\`
 
-**Another example - System monitoring agent:**
-\`\`\`json
-{
-  "name": "system-monitor",
-  "description": "Monitor system resources and processes",
-  "model": "gpt-5.1",
-  "instructions": "Monitor system resources using bash commands. Use 'df -h' for disk usage, 'free -h' for memory, 'top -bn1' for processes, 'ps aux' for process list. Parse the output and report any issues.",
-  "tools": {
-    "bash": {
-      "type": "builtin",
-      "name": "executeCommand"
-    }
-  }
-}
+**Another example - System monitoring agent** (\`agents/system-monitor.md\`):
+\`\`\`markdown
+---
+model: gpt-5.1
+tools:
+  bash:
+    type: builtin
+    name: executeCommand
+---
+# System Monitor
+
+Monitor system resources using bash commands:
+- Use 'df -h' for disk usage
+- Use 'free -h' for memory
+- Use 'top -bn1' for processes
+- Use 'ps aux' for process list
+
+Parse the output and report any issues.
 \`\`\`
 
-**Another example - Git automation agent:**
-\`\`\`json
-{
-  "name": "git-helper",
-  "description": "Automate git operations",
-  "model": "gpt-5.1",
-  "instructions": "Help with git operations. Use commands like 'git status', 'git log --oneline -10', 'git diff', 'git branch -a' to inspect the repository. Can also run 'git add', 'git commit', 'git push' when instructed.",
-  "tools": {
-    "bash": {
-      "type": "builtin",
-      "name": "executeCommand"
-    }
-  }
-}
+**Another example - Git automation agent** (\`agents/git-helper.md\`):
+\`\`\`markdown
+---
+model: gpt-5.1
+tools:
+  bash:
+    type: builtin
+    name: executeCommand
+---
+# Git Helper
+
+Help with git operations. Use commands like:
+- 'git status' - Check working tree status
+- 'git log --oneline -10' - View recent commits
+- 'git diff' - See changes
+- 'git branch -a' - List branches
+
+Can also run 'git add', 'git commit', 'git push' when instructed.
 \`\`\`
 
 ## Agent-to-Agent Calling
 
 Agents can call other agents as tools to create complex multi-step workflows. This is the core mechanism for building multi-agent systems in the CLI.
 
-**Tool declaration:**
-\`\`\`json
-"tools": {
-  "summariser": {
-    "type": "agent",
-    "name": "summariser_agent"
-  }
-}
+**Tool declaration (YAML frontmatter):**
+\`\`\`yaml
+tools:
+  summariser:
+    type: agent
+    name: summariser_agent
 \`\`\`
 
 **When to use:**
@@ -125,19 +135,19 @@ Agents can call other agents as tools to create complex multi-step workflows. Th
 - Results are returned as tool output
 - The calling agent can then continue processing or delegate further
 
-**Example - Agent that delegates to a summarizer:**
-\`\`\`json
-{
-  "name": "paper_analyzer",
-  "model": "gpt-5.1",
-  "instructions": "Pick 2 interesting papers and summarise each using the summariser tool. Pass the paper URL to the summariser. Don't ask for human input.",
-  "tools": {
-    "summariser": {
-      "type": "agent",
-      "name": "summariser_agent"
-    }
-  }
-}
+**Example - Agent that delegates to a summarizer** (\`agents/paper_analyzer.md\`):
+\`\`\`markdown
+---
+model: gpt-5.1
+tools:
+  summariser:
+    type: agent
+    name: summariser_agent
+---
+# Paper Analyzer
+
+Pick 2 interesting papers and summarise each using the summariser tool.
+Pass the paper URL to the summariser. Don't ask for human input.
 \`\`\`
 
 **Tips for agent chaining:**
@@ -198,18 +208,18 @@ The \`executeMcpTool\` builtin allows the copilot to directly execute MCP tools
 
 - **Use builtin executeCommand** when you need: CLI tools, system operations, data processing, git operations, any shell command
 - **Use MCP tools** when you need: Web scraping (firecrawl), text-to-speech (elevenlabs), specialized APIs, external service integrations
-- **Use agent tools (\`"type": "agent"\`)** when you need: Complex multi-step logic, task delegation, specialized processing that benefits from LLM reasoning
+- **Use agent tools (\`type: agent\`)** when you need: Complex multi-step logic, task delegation, specialized processing that benefits from LLM reasoning
 
 Many tasks can be accomplished with just \`executeCommand\` and common Unix tools - it's incredibly powerful!
 
 ## Key Insight: Multi-Agent Workflows
 
 In the CLI, multi-agent workflows are built by:
-1. Creating specialized agents for specific tasks (in \`agents/\` directory)
-2. Creating an orchestrator agent that has other agents in its \`tools\`
+1. Creating specialized agents as Markdown files in the \`agents/\` directory
+2. Creating an orchestrator agent that has other agents in its \`tools\` (YAML frontmatter)
 3. Running the orchestrator with \`rowboatx --agent orchestrator_name\`
 
-There are no separate "workflow" files - everything is an agent!
+There are no separate "workflow" files - everything is an agent defined in Markdown!
 `;
 
 export default skill;
diff --git a/apps/x/packages/core/src/application/assistant/skills/mcp-integration/skill.ts b/apps/x/packages/core/src/application/assistant/skills/mcp-integration/skill.ts
index 6478f1bd..eed51898 100644
--- a/apps/x/packages/core/src/application/assistant/skills/mcp-integration/skill.ts
+++ b/apps/x/packages/core/src/application/assistant/skills/mcp-integration/skill.ts
@@ -359,70 +359,67 @@ Always use \`listMcpServers\` and \`listMcpTools\` to discover what's actually a
 
 ## Adding MCP Tools to Agents
 
-Once an MCP server is configured, add its tools to agent definitions:
+Once an MCP server is configured, add its tools to agent definitions (Markdown files with YAML frontmatter):
 
-### MCP Tool Format in Agent
-\`\`\`json
-"tools": {
-  "descriptive_key": {
-    "type": "mcp",
-    "name": "actual_tool_name_from_server",
-    "description": "What the tool does",
-    "mcpServerName": "server_name_from_config",
-    "inputSchema": {
-      "type": "object",
-      "properties": {
-        "param1": {"type": "string", "description": "What param1 means"}
-      },
-      "required": ["param1"]
-    }
-  }
-}
+### MCP Tool Format in Agent (YAML frontmatter)
+\`\`\`yaml
+tools:
+  descriptive_key:
+    type: mcp
+    name: actual_tool_name_from_server
+    description: What the tool does
+    mcpServerName: server_name_from_config
+    inputSchema:
+      type: object
+      properties:
+        param1:
+          type: string
+          description: What param1 means
+      required:
+        - param1
 \`\`\`
 
 ### Tool Schema Rules
 - Use \`listMcpTools\` to get the exact \`inputSchema\` from the server
 - Copy the schema exactly as provided by the MCP server
-- Only include \`"required"\` array if parameters are truly mandatory
+- Only include \`required\` array if parameters are truly mandatory
 - Add descriptions to help the agent understand parameter usage
 
 ### Example snippets to reference
 - Firecrawl search (required param):
-\`\`\`json
-"tools": {
-  "search": {
-    "type": "mcp",
-    "name": "firecrawl_search",
-    "description": "Search the web",
-    "mcpServerName": "firecrawl",
-    "inputSchema": {
-      "type": "object",
-      "properties": {
-        "query": {"type": "string", "description": "Search query"},
-        "limit": {"type": "number", "description": "Number of results"}
-      },
-      "required": ["query"]
-    }
-  }
-}
+\`\`\`yaml
+tools:
+  search:
+    type: mcp
+    name: firecrawl_search
+    description: Search the web
+    mcpServerName: firecrawl
+    inputSchema:
+      type: object
+      properties:
+        query:
+          type: string
+          description: Search query
+        limit:
+          type: number
+          description: Number of results
+      required:
+        - query
 \`\`\`
 
 - ElevenLabs text-to-speech (no required array):
-\`\`\`json
-"tools": {
-  "text_to_speech": {
-    "type": "mcp",
-    "name": "text_to_speech",
-    "description": "Generate audio from text",
-    "mcpServerName": "elevenLabs",
-    "inputSchema": {
-      "type": "object",
-      "properties": {
-        "text": {"type": "string"}
-      }
-    }
-  }
-}
+\`\`\`yaml
+tools:
+  text_to_speech:
+    type: mcp
+    name: text_to_speech
+    description: Generate audio from text
+    mcpServerName: elevenLabs
+    inputSchema:
+      type: object
+      properties:
+        text:
+          type: string
 \`\`\`
 
 
diff --git a/apps/x/packages/core/src/application/assistant/skills/workflow-authoring/skill.ts b/apps/x/packages/core/src/application/assistant/skills/workflow-authoring/skill.ts
index 85bb113e..bcd50258 100644
--- a/apps/x/packages/core/src/application/assistant/skills/workflow-authoring/skill.ts
+++ b/apps/x/packages/core/src/application/assistant/skills/workflow-authoring/skill.ts
@@ -7,8 +7,8 @@ Load this skill whenever a user wants to inspect, create, or update agents insid
 
 **IMPORTANT**: In the CLI, there are NO separate "workflow" files. Everything is an agent.
 
-- **All definitions live in \`agents/*.json\`** - there is no separate workflows folder
-- Agents configure a model, instructions, and the tools they can use
+- **All definitions live in \`agents/*.md\`** - Markdown files with YAML frontmatter
+- Agents configure a model, tools (in frontmatter), and instructions (in the body)
 - Tools can be: builtin (like \`executeCommand\`), MCP integrations, or **other agents**
 - **"Workflows" are just agents that orchestrate other agents** by having them as tools
 
@@ -19,66 +19,66 @@ Load this skill whenever a user wants to inspect, create, or update agents insid
 3. The orchestrator calls other agents as tools when needed
 4. Data flows through tool call parameters and responses
 
-## Agent File Schema
+## Agent File Format
 
-Agent files MUST conform to this exact schema. Invalid agents will fail to load.
+Agent files are **Markdown files with YAML frontmatter**. The frontmatter contains configuration (model, tools), and the body contains the instructions.
 
-### Complete Agent Schema
-\`\`\`json
-{
-  "name": "string (REQUIRED, must match filename without .json)",
-  "description": "string (REQUIRED, what this agent does)",
-  "instructions": "string (REQUIRED, detailed instructions for the agent)",
-  "model": "string (OPTIONAL, e.g., 'gpt-5.1', 'claude-sonnet-4-5')",
-  "provider": "string (OPTIONAL, provider alias from models.json)",
-  "tools": {
-    "descriptive_key": {
-      "type": "builtin | mcp | agent (REQUIRED)",
-      "name": "string (REQUIRED)",
-      // Additional fields depend on type - see below
-    }
-  }
-}
+### Basic Structure
+\`\`\`markdown
+---
+model: gpt-5.1
+tools:
+  tool_key:
+    type: builtin
+    name: tool_name
+---
+# Instructions
+
+Your detailed instructions go here in Markdown format.
 \`\`\`
 
-### Required Fields
-- \`name\`: Agent identifier (must exactly match the filename without .json)
-- \`description\`: Brief description of agent's purpose
-- \`instructions\`: Detailed instructions for how the agent should behave
+### Frontmatter Fields
+- \`model\`: (OPTIONAL) Model to use (e.g., 'gpt-5.1', 'claude-sonnet-4-5')
+- \`provider\`: (OPTIONAL) Provider alias from models.json
+- \`tools\`: (OPTIONAL) Object containing tool definitions
 
-### Optional Fields
-- \`model\`: Model to use (defaults to model config if not specified)
-- \`provider\`: Provider alias from models.json (optional)
-- \`tools\`: Object containing tool definitions (can be empty or omitted)
+### Instructions (Body)
+The Markdown body after the frontmatter contains the agent's instructions. Use standard Markdown formatting.
 
 ### Naming Rules
-- Agent filename MUST match the \`name\` field exactly
-- Example: If \`name\` is "summariser_agent", file must be "summariser_agent.json"
+- Agent filename determines the agent name (without .md extension)
+- Example: \`summariser_agent.md\` creates an agent named "summariser_agent"
 - Use lowercase with underscores for multi-word names
 - No spaces or special characters in names
 
 ### Agent Format Example
-\`\`\`json
-{
-  "name": "agent_name",
-  "description": "Description of the agent",
-  "model": "gpt-5.1",
-  "instructions": "Instructions for the agent",
-  "tools": {
-    "descriptive_tool_key": {
-      "type": "mcp",
-      "name": "actual_mcp_tool_name",
-      "description": "What the tool does",
-      "mcpServerName": "server_name_from_config",
-      "inputSchema": {
-        "type": "object",
-        "properties": {
-          "param1": {"type": "string", "description": "What the parameter means"}
-        }
-      }
-    }
-  }
-}
+\`\`\`markdown
+---
+model: gpt-5.1
+tools:
+  search:
+    type: mcp
+    name: firecrawl_search
+    description: Search the web
+    mcpServerName: firecrawl
+    inputSchema:
+      type: object
+      properties:
+        query:
+          type: string
+          description: Search query
+      required:
+        - query
+---
+# Web Search Agent
+
+You are a web search agent. When asked a question:
+
+1. Use the search tool to find relevant information
+2. Summarize the results clearly
+3. Cite your sources
+
+Be concise and accurate.
 \`\`\`
 
 ## Tool Types & Schemas
@@ -88,24 +88,22 @@ Tools in agents must follow one of three types. Each has specific required field
 ### 1. Builtin Tools
 Internal Rowboat tools (executeCommand, file operations, MCP queries, etc.)
 
-**Schema:**
-\`\`\`json
-{
-  "type": "builtin",
-  "name": "tool_name"
-}
+**YAML Schema:**
+\`\`\`yaml
+tool_key:
+  type: builtin
+  name: tool_name
 \`\`\`
 
 **Required fields:**
 - \`type\`: Must be "builtin"
-- \`name\`: Builtin tool name (e.g., "executeCommand", "readFile")
+- \`name\`: Builtin tool name (e.g., "executeCommand", "workspace-readFile")
 
 **Example:**
-\`\`\`json
-"bash": {
-  "type": "builtin",
-  "name": "executeCommand"
-}
+\`\`\`yaml
+bash:
+  type: builtin
+  name: executeCommand
 \`\`\`
 
 **Available builtin tools:**
@@ -120,21 +118,21 @@ Internal Rowboat tools (executeCommand, file operations, MCP queries, etc.)
 ### 2. MCP Tools
 Tools from external MCP servers (APIs, databases, web scraping, etc.)
 
-**Schema:**
-\`\`\`json
-{
-  "type": "mcp",
-  "name": "tool_name_from_server",
-  "description": "What the tool does",
-  "mcpServerName": "server_name_from_config",
-  "inputSchema": {
-    "type": "object",
-    "properties": {
-      "param": {"type": "string", "description": "Parameter description"}
-    },
-    "required": ["param"]
-  }
-}
+**YAML Schema:**
+\`\`\`yaml
+tool_key:
+  type: mcp
+  name: tool_name_from_server
+  description: What the tool does
+  mcpServerName: server_name_from_config
+  inputSchema:
+    type: object
+    properties:
+      param:
+        type: string
+        description: Parameter description
+    required:
+      - param
 \`\`\`
 
 **Required fields:**
@@ -145,36 +143,35 @@ Tools from external MCP servers (APIs, databases, web scraping, etc.)
 - \`inputSchema\`: Full JSON Schema object for tool parameters
 
 **Example:**
-\`\`\`json
-"search": {
-  "type": "mcp",
-  "name": "firecrawl_search",
-  "description": "Search the web",
-  "mcpServerName": "firecrawl",
-  "inputSchema": {
-    "type": "object",
-    "properties": {
-      "query": {"type": "string", "description": "Search query"}
-    },
-    "required": ["query"]
-  }
-}
+\`\`\`yaml
+search:
+  type: mcp
+  name: firecrawl_search
+  description: Search the web
+  mcpServerName: firecrawl
+  inputSchema:
+    type: object
+    properties:
+      query:
+        type: string
+        description: Search query
+    required:
+      - query
 \`\`\`
 
 **Important:**
 - Use \`listMcpTools\` to get the exact inputSchema from the server
 - Copy the schema exactly—don't modify property types or structure
-- Only include \`"required"\` array if parameters are mandatory
+- Only include \`required\` array if parameters are mandatory
 
 ### 3. Agent Tools (for chaining agents)
 Reference other agents as tools to build multi-agent workflows
 
-**Schema:**
-\`\`\`json
-{
-  "type": "agent",
-  "name": "target_agent_name"
-}
+**YAML Schema:**
+\`\`\`yaml
+tool_key:
+  type: agent
+  name: target_agent_name
 \`\`\`
 
 **Required fields:**
@@ -182,84 +179,94 @@ Reference other agents as tools to build multi-agent workflows
 - \`name\`: Name of the target agent (must exist in agents/ directory)
 
 **Example:**
-\`\`\`json
-"summariser": {
-  "type": "agent",
-  "name": "summariser_agent"
-}
+\`\`\`yaml
+summariser:
+  type: agent
+  name: summariser_agent
 \`\`\`
 
 **How it works:**
-- Use \`"type": "agent"\` to call other agents as tools
+- Use \`type: agent\` to call other agents as tools
 - The target agent will be invoked with the parameters you pass
 - Results are returned as tool output
 - This is how you build multi-agent workflows
-- The referenced agent file must exist (e.g., agents/summariser_agent.json)
+- The referenced agent file must exist (e.g., \`agents/summariser_agent.md\`)
 
 ## Complete Multi-Agent Workflow Example
 
 **Podcast creation workflow** - This is all done through agents calling other agents:
 
-**1. Task-specific agent** (does one thing):
-\`\`\`json
-{
-  "name": "summariser_agent",
-  "description": "Summarises an arxiv paper",
-  "model": "gpt-5.1",
-  "instructions": "Download and summarise an arxiv paper. Use curl to fetch the PDF. Output just the GIST in two lines. Don't ask for human input.",
-  "tools": {
-    "bash": {"type": "builtin", "name": "executeCommand"}
-  }
-}
+**1. Task-specific agent** (\`agents/summariser_agent.md\`):
+\`\`\`markdown
+---
+model: gpt-5.1
+tools:
+  bash:
+    type: builtin
+    name: executeCommand
+---
+# Summariser Agent
+
+Download and summarise an arxiv paper. Use curl to fetch the PDF.
+Output just the GIST in two lines. Don't ask for human input.
 \`\`\`
 
-**2. Agent that delegates to other agents**:
-\`\`\`json
-{
-  "name": "summarise-a-few",
-  "description": "Summarises multiple arxiv papers",
-  "model": "gpt-5.1",
-  "instructions": "Pick 2 interesting papers and summarise each using the summariser tool. Pass the paper URL to the tool. Don't ask for human input.",
-  "tools": {
-    "summariser": {
-      "type": "agent",
-      "name": "summariser_agent"
-    }
-  }
-}
+**2. Agent that delegates to other agents** (\`agents/summarise-a-few.md\`):
+\`\`\`markdown
+---
+model: gpt-5.1
+tools:
+  summariser:
+    type: agent
+    name: summariser_agent
+---
+# Summarise Multiple Papers
+
+Pick 2 interesting papers and summarise each using the summariser tool.
+Pass the paper URL to the tool. Don't ask for human input.
 \`\`\`
 
-**3. Orchestrator agent** (coordinates the whole workflow):
-\`\`\`json
-{
-  "name": "podcast_workflow",
-  "description": "Create a podcast from arXiv papers",
-  "model": "gpt-5.1",
-  "instructions": "1. Fetch arXiv papers about agents using bash\n2. Pick papers and summarise them using summarise_papers\n3. Create a podcast transcript\n4. Generate audio using text_to_speech\n\nExecute these steps in sequence.",
-  "tools": {
-    "bash": {"type": "builtin", "name": "executeCommand"},
-    "summarise_papers": {
-      "type": "agent",
-      "name": "summarise-a-few"
-    },
-    "text_to_speech": {
-      "type": "mcp",
-      "name": "text_to_speech",
-      "mcpServerName": "elevenLabs",
-      "description": "Generate audio",
-      "inputSchema": { "type": "object", "properties": {...}}
-    }
-  }
-}
+**3. Orchestrator agent** (\`agents/podcast_workflow.md\`):
+\`\`\`markdown
+---
+model: gpt-5.1
+tools:
+  bash:
+    type: builtin
+    name: executeCommand
+  summarise_papers:
+    type: agent
+    name: summarise-a-few
+  text_to_speech:
+    type: mcp
+    name: text_to_speech
+    mcpServerName: elevenLabs
+    description: Generate audio from text
+    inputSchema:
+      type: object
+      properties:
+        text:
+          type: string
+          description: Text to convert to speech
+---
+# Podcast Workflow
+
+Create a podcast from arXiv papers:
+
+1. Fetch arXiv papers about agents using bash
+2. Pick papers and summarise them using summarise_papers
+3. Create a podcast transcript
+4. Generate audio using text_to_speech
+
+Execute these steps in sequence.
 \`\`\`
 
 **To run this workflow**: \`rowboatx --agent podcast_workflow\`
 
 ## Naming and organization rules
-- **All agents live in \`agents/*.json\`** - no other location
-- Agent filenames must match the \`"name"\` field exactly
-- When referencing an agent as a tool, use its \`"name"\` value
-- Always keep filenames and \`"name"\` fields perfectly aligned
+- **All agents live in \`agents/*.md\`** - Markdown files with YAML frontmatter
+- Agent filename (without .md) becomes the agent name
+- When referencing an agent as a tool, use its filename without extension
 - Use relative paths (no \${BASE_DIR} prefixes) when giving examples to users
 
 ## Best practices for multi-agent design
@@ -273,85 +280,105 @@ Reference other agents as tools to build multi-agent workflows
 ## Validation & Best Practices
 
 ### CRITICAL: Schema Compliance
-- Agent files MUST have \`name\`, \`description\`, and \`instructions\` fields
-- Agent filename MUST exactly match the \`name\` field
-- Tools MUST have valid \`type\` ("builtin", "mcp", or "agent")
+- Agent files MUST be valid Markdown with YAML frontmatter
+- Agent filename (without .md) becomes the agent name
+- Tools in frontmatter MUST have valid \`type\` ("builtin", "mcp", or "agent")
 - MCP tools MUST have all required fields: name, description, mcpServerName, inputSchema
 - Agent tools MUST reference existing agent files
 - Invalid agents will fail to load and prevent workflow execution
 
 ### File Creation/Update Process
-1. When creating an agent, use \`workspace-writeFile\` with complete, valid JSON
+1. When creating an agent, use \`workspace-writeFile\` with valid Markdown + YAML frontmatter
 2. When updating an agent, read it first with \`workspace-readFile\`, modify, then use \`workspace-writeFile\`
-3. Validate JSON syntax before writing—malformed JSON breaks the agent
-4. Test agent loading after creation/update by using \`analyzeAgent\`
+3. Validate YAML syntax in frontmatter before writing—malformed YAML breaks the agent
+4. **Quote strings containing colons** (e.g., \`description: "Default: 8"\` not \`description: Default: 8\`)
+5. Test agent loading after creation/update by using \`analyzeAgent\`
 
 ### Common Validation Errors to Avoid
 
-❌ **WRONG - Missing required fields:**
-\`\`\`json
-{
-  "name": "my_agent"
-  // Missing description and instructions
-}
+❌ **WRONG - Missing frontmatter delimiters:**
+\`\`\`markdown
+model: gpt-5.1
+# My Agent
+Instructions here
 \`\`\`
 
-❌ **WRONG - Filename mismatch:**
-- File: agents/my_agent.json
-- Content: {"name": "myagent", ...}
+❌ **WRONG - Invalid YAML indentation:**
+\`\`\`markdown
+---
+tools:
+bash:
+  type: builtin
+---
+\`\`\`
+(bash should be indented under tools)
 
 ❌ **WRONG - Invalid tool type:**
-\`\`\`json
-"tool1": {
-  "type": "custom",  // Invalid type
-  "name": "something"
-}
+\`\`\`yaml
+tools:
+  tool1:
+    type: custom
+    name: something
 \`\`\`
+(type must be builtin, mcp, or agent)
+
+❌ **WRONG - Unquoted strings containing colons:**
+\`\`\`yaml
+tools:
+  search:
+    description: Number of results (default: 8)
+\`\`\`
+(Strings with colons must be quoted: \`description: "Number of results (default: 8)"\`)
 
 ❌ **WRONG - MCP tool missing required fields:**
-\`\`\`json
-"search": {
-  "type": "mcp",
-  "name": "firecrawl_search"
-  // Missing: description, mcpServerName, inputSchema
-}
+\`\`\`yaml
+tools:
+  search:
+    type: mcp
+    name: firecrawl_search
+\`\`\`
+(Missing: description, mcpServerName, inputSchema)
+
+✅ **CORRECT - Minimal valid agent** (\`agents/simple_agent.md\`):
+\`\`\`markdown
+---
+model: gpt-5.1
+---
+# Simple Agent
+
+Do simple tasks as instructed.
 \`\`\`
 
-✅ **CORRECT - Minimal valid agent:**
-\`\`\`json
-{
-  "name": "simple_agent",
-  "description": "A simple agent",
-  "instructions": "Do simple tasks"
-}
-\`\`\`
+✅ **CORRECT - Agent with MCP tool** (\`agents/search_agent.md\`):
+\`\`\`markdown
+---
+model: gpt-5.1
+tools:
+  search:
+    type: mcp
+    name: firecrawl_search
+    description: Search the web
+    mcpServerName: firecrawl
+    inputSchema:
+      type: object
+      properties:
+        query:
+          type: string
+---
+# Search Agent
 
-✅ **CORRECT - Complete MCP tool:**
-\`\`\`json
-"search": {
-  "type": "mcp",
-  "name": "firecrawl_search",
-  "description": "Search the web",
-  "mcpServerName": "firecrawl",
-  "inputSchema": {
-    "type": "object",
-    "properties": {
-      "query": {"type": "string"}
-    }
-  }
-}
+Use the search tool to find information on the web.
 \`\`\`
 
 ## Capabilities checklist
 1. Explore \`agents/\` directory to understand existing agents before editing
-2. Read existing agents with \`readFile\` before making changes
-3. Validate all required fields are present before creating/updating agents
-4. Ensure filename matches the \`name\` field exactly
-5. Use \`analyzeAgent\` to verify agent structure after creation/update
-6. When creating multi-agent workflows, create an orchestrator agent
-7. Add other agents as tools with \`"type": "agent"\` for chaining
-8. Use \`listMcpServers\` and \`listMcpTools\` when adding MCP integrations
-9. Confirm work done and outline next steps once changes are complete
+2. Read existing agents with \`workspace-readFile\` before making changes
+3. Validate YAML frontmatter syntax before creating/updating agents
+4. Use \`analyzeAgent\` to verify agent structure after creation/update
+5. When creating multi-agent workflows, create an orchestrator agent
+6. Add other agents as tools with \`type: agent\` for chaining
+7. Use \`listMcpServers\` and \`listMcpTools\` when adding MCP integrations
+8. Confirm work done and outline next steps once changes are complete
 `;
 
 export default skill;