apunkt/rowboat
1
0
Fork 0
mirror of https://github.com/rowboatlabs/rowboat.git synced 2026-05-25 18:55:19 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

fix assistant to use md for agents

Browse source
This commit is contained in:
Arjun 2026-01-12 20:57:53 +05:30 • committed by Ramnique Singh
parent 8b02daab61
commit d10a27c8eb
3 changed files with 374 additions and 340 deletions
Download patch file Download diff file Expand all files Collapse all files

162
apps/x/packages/core/src/application/assistant/skills/builtin-tools/skill.ts
View file

@ -5,21 +5,19 @@ Load this skill when creating or modifying agents that need access to Rowboat's
## Available Builtin Tools ## 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 ### executeCommand
**The most powerful and versatile builtin tool** - Execute any bash/shell command and get the output. **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. **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:** **Agent tool declaration (YAML frontmatter):**
\`\`\`json \`\`\`yaml
"tools": { tools:
"bash": { bash:
"type": "builtin", type: builtin
"name": "executeCommand" name: executeCommand
}
}
\`\`\` \`\`\`
**What it can do:** **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.) - Full bash shell features are available (variables, loops, conditionals, etc.)
- Tools like jq, yq, awk, sed can parse and transform data - Tools like jq, yq, awk, sed can parse and transform data
**Example agent with executeCommand:** **Example agent with executeCommand** (\`agents/arxiv-feed-reader.md\`):
\`\`\`json \`\`\`markdown
{ ---
"name": "arxiv-feed-reader", model: gpt-5.1
"description": "A feed reader for the arXiv", tools:
"model": "gpt-5.1", bash:
"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.", type: builtin
"tools": { name: executeCommand
"bash": { ---
"type": "builtin", # arXiv Feed Reader
"name": "executeCommand"
} 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:** **Another example - System monitoring agent** (\`agents/system-monitor.md\`):
\`\`\`json \`\`\`markdown
{ ---
"name": "system-monitor", model: gpt-5.1
"description": "Monitor system resources and processes", tools:
"model": "gpt-5.1", bash:
"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.", type: builtin
"tools": { name: executeCommand
"bash": { ---
"type": "builtin", # System Monitor
"name": "executeCommand"
} 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:** **Another example - Git automation agent** (\`agents/git-helper.md\`):
\`\`\`json \`\`\`markdown
{ ---
"name": "git-helper", model: gpt-5.1
"description": "Automate git operations", tools:
"model": "gpt-5.1", bash:
"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.", type: builtin
"tools": { name: executeCommand
"bash": { ---
"type": "builtin", # Git Helper
"name": "executeCommand"
} 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 ## 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. 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:** **Tool declaration (YAML frontmatter):**
\`\`\`json \`\`\`yaml
"tools": { tools:
"summariser": { summariser:
"type": "agent", type: agent
"name": "summariser_agent" name: summariser_agent
}
}
\`\`\` \`\`\`
**When to use:** **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 - Results are returned as tool output
- The calling agent can then continue processing or delegate further - The calling agent can then continue processing or delegate further
**Example - Agent that delegates to a summarizer:** **Example - Agent that delegates to a summarizer** (\`agents/paper_analyzer.md\`):
\`\`\`json \`\`\`markdown
{ ---
"name": "paper_analyzer", model: gpt-5.1
"model": "gpt-5.1", tools:
"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.", summariser:
"tools": { type: agent
"summariser": { name: summariser_agent
"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:** **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 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 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! Many tasks can be accomplished with just \`executeCommand\` and common Unix tools - it's incredibly powerful!
## Key Insight: Multi-Agent Workflows ## Key Insight: Multi-Agent Workflows
In the CLI, multi-agent workflows are built by: In the CLI, multi-agent workflows are built by:
1. Creating specialized agents for specific tasks (in \`agents/\` directory) 1. Creating specialized agents as Markdown files in the \`agents/\` directory
2. Creating an orchestrator agent that has other agents in its \`tools\` 2. Creating an orchestrator agent that has other agents in its \`tools\` (YAML frontmatter)
3. Running the orchestrator with \`rowboatx --agent orchestrator_name\` 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; export default skill;

99
apps/x/packages/core/src/application/assistant/skills/mcp-integration/skill.ts
View file

@ -359,70 +359,67 @@ Always use \`listMcpServers\` and \`listMcpTools\` to discover what's actually a
## Adding MCP Tools to Agents ## 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 ### MCP Tool Format in Agent (YAML frontmatter)
\`\`\`json \`\`\`yaml
"tools": { tools:
"descriptive_key": { descriptive_key:
"type": "mcp", type: mcp
"name": "actual_tool_name_from_server", name: actual_tool_name_from_server
"description": "What the tool does", description: What the tool does
"mcpServerName": "server_name_from_config", mcpServerName: server_name_from_config
"inputSchema": { inputSchema:
"type": "object", type: object
"properties": { properties:
"param1": {"type": "string", "description": "What param1 means"} param1:
}, type: string
"required": ["param1"] description: What param1 means
} required:
} - param1
}
\`\`\` \`\`\`
### Tool Schema Rules ### Tool Schema Rules
- Use \`listMcpTools\` to get the exact \`inputSchema\` from the server - Use \`listMcpTools\` to get the exact \`inputSchema\` from the server
- Copy the schema exactly as provided by the MCP 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 - Add descriptions to help the agent understand parameter usage
### Example snippets to reference ### Example snippets to reference
- Firecrawl search (required param): - Firecrawl search (required param):
\`\`\`json \`\`\`yaml
"tools": { tools:
"search": { search:
"type": "mcp", type: mcp
"name": "firecrawl_search", name: firecrawl_search
"description": "Search the web", description: Search the web
"mcpServerName": "firecrawl", mcpServerName: firecrawl
"inputSchema": { inputSchema:
"type": "object", type: object
"properties": { properties:
"query": {"type": "string", "description": "Search query"}, query:
"limit": {"type": "number", "description": "Number of results"} type: string
}, description: Search query
"required": ["query"] limit:
} type: number
} description: Number of results
} required:
- query
\`\`\` \`\`\`
- ElevenLabs text-to-speech (no required array): - ElevenLabs text-to-speech (no required array):
\`\`\`json \`\`\`yaml
"tools": { tools:
"text_to_speech": { text_to_speech:
"type": "mcp", type: mcp
"name": "text_to_speech", name: text_to_speech
"description": "Generate audio from text", description: Generate audio from text
"mcpServerName": "elevenLabs", mcpServerName: elevenLabs
"inputSchema": { inputSchema:
"type": "object", type: object
"properties": { properties:
"text": {"type": "string"} text:
} type: string
}
}
}
\`\`\` \`\`\`

453
apps/x/packages/core/src/application/assistant/skills/workflow-authoring/skill.ts
View file

@ -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. **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 - **All definitions live in \`agents/*.md\`** - Markdown files with YAML frontmatter
- Agents configure a model, instructions, and the tools they can use - Agents configure a model, tools (in frontmatter), and instructions (in the body)
- Tools can be: builtin (like \`executeCommand\`), MCP integrations, or **other agents** - Tools can be: builtin (like \`executeCommand\`), MCP integrations, or **other agents**
- **"Workflows" are just agents that orchestrate other agents** by having them as tools - **"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 3. The orchestrator calls other agents as tools when needed
4. Data flows through tool call parameters and responses 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 ### Basic Structure
\`\`\`json \`\`\`markdown
{ ---
"name": "string (REQUIRED, must match filename without .json)", model: gpt-5.1
"description": "string (REQUIRED, what this agent does)", tools:
"instructions": "string (REQUIRED, detailed instructions for the agent)", tool_key:
"model": "string (OPTIONAL, e.g., 'gpt-5.1', 'claude-sonnet-4-5')", type: builtin
"provider": "string (OPTIONAL, provider alias from models.json)", name: tool_name
"tools": { ---
"descriptive_key": { # Instructions
"type": "builtin | mcp | agent (REQUIRED)",
"name": "string (REQUIRED)", Your detailed instructions go here in Markdown format.
// Additional fields depend on type - see below
}
}
}
\`\`\` \`\`\`
### Required Fields ### Frontmatter Fields
- \`name\`: Agent identifier (must exactly match the filename without .json) - \`model\`: (OPTIONAL) Model to use (e.g., 'gpt-5.1', 'claude-sonnet-4-5')
- \`description\`: Brief description of agent's purpose - \`provider\`: (OPTIONAL) Provider alias from models.json
- \`instructions\`: Detailed instructions for how the agent should behave - \`tools\`: (OPTIONAL) Object containing tool definitions
### Optional Fields ### Instructions (Body)
- \`model\`: Model to use (defaults to model config if not specified) The Markdown body after the frontmatter contains the agent's instructions. Use standard Markdown formatting.
- \`provider\`: Provider alias from models.json (optional)
- \`tools\`: Object containing tool definitions (can be empty or omitted)
### Naming Rules ### Naming Rules
- Agent filename MUST match the \`name\` field exactly - Agent filename determines the agent name (without .md extension)
- Example: If \`name\` is "summariser_agent", file must be "summariser_agent.json" - Example: \`summariser_agent.md\` creates an agent named "summariser_agent"
- Use lowercase with underscores for multi-word names - Use lowercase with underscores for multi-word names
- No spaces or special characters in names - No spaces or special characters in names
### Agent Format Example ### Agent Format Example
\`\`\`json \`\`\`markdown
{ ---
"name": "agent_name", model: gpt-5.1
"description": "Description of the agent", tools:
"model": "gpt-5.1", search:
"instructions": "Instructions for the agent", type: mcp
"tools": { name: firecrawl_search
"descriptive_tool_key": { description: Search the web
"type": "mcp", mcpServerName: firecrawl
"name": "actual_mcp_tool_name", inputSchema:
"description": "What the tool does", type: object
"mcpServerName": "server_name_from_config", properties:
"inputSchema": { query:
"type": "object", type: string
"properties": { description: Search query
"param1": {"type": "string", "description": "What the parameter means"} 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 ## Tool Types & Schemas
@ -88,24 +88,22 @@ Tools in agents must follow one of three types. Each has specific required field
### 1. Builtin Tools ### 1. Builtin Tools
Internal Rowboat tools (executeCommand, file operations, MCP queries, etc.) Internal Rowboat tools (executeCommand, file operations, MCP queries, etc.)
**Schema:** **YAML Schema:**
\`\`\`json \`\`\`yaml
{ tool_key:
"type": "builtin", type: builtin
"name": "tool_name" name: tool_name
}
\`\`\` \`\`\`
**Required fields:** **Required fields:**
- \`type\`: Must be "builtin" - \`type\`: Must be "builtin"
- \`name\`: Builtin tool name (e.g., "executeCommand", "readFile") - \`name\`: Builtin tool name (e.g., "executeCommand", "workspace-readFile")
**Example:** **Example:**
\`\`\`json \`\`\`yaml
"bash": { bash:
"type": "builtin", type: builtin
"name": "executeCommand" name: executeCommand
}
\`\`\` \`\`\`
**Available builtin tools:** **Available builtin tools:**
@ -120,21 +118,21 @@ Internal Rowboat tools (executeCommand, file operations, MCP queries, etc.)
### 2. MCP Tools ### 2. MCP Tools
Tools from external MCP servers (APIs, databases, web scraping, etc.) Tools from external MCP servers (APIs, databases, web scraping, etc.)
**Schema:** **YAML Schema:**
\`\`\`json \`\`\`yaml
{ tool_key:
"type": "mcp", type: mcp
"name": "tool_name_from_server", name: tool_name_from_server
"description": "What the tool does", description: What the tool does
"mcpServerName": "server_name_from_config", mcpServerName: server_name_from_config
"inputSchema": { inputSchema:
"type": "object", type: object
"properties": { properties:
"param": {"type": "string", "description": "Parameter description"} param:
}, type: string
"required": ["param"] description: Parameter description
} required:
} - param
\`\`\` \`\`\`
**Required fields:** **Required fields:**
@ -145,36 +143,35 @@ Tools from external MCP servers (APIs, databases, web scraping, etc.)
- \`inputSchema\`: Full JSON Schema object for tool parameters - \`inputSchema\`: Full JSON Schema object for tool parameters
**Example:** **Example:**
\`\`\`json \`\`\`yaml
"search": { search:
"type": "mcp", type: mcp
"name": "firecrawl_search", name: firecrawl_search
"description": "Search the web", description: Search the web
"mcpServerName": "firecrawl", mcpServerName: firecrawl
"inputSchema": { inputSchema:
"type": "object", type: object
"properties": { properties:
"query": {"type": "string", "description": "Search query"} query:
}, type: string
"required": ["query"] description: Search query
} required:
} - query
\`\`\` \`\`\`
**Important:** **Important:**
- Use \`listMcpTools\` to get the exact inputSchema from the server - Use \`listMcpTools\` to get the exact inputSchema from the server
- Copy the schema exactly—don't modify property types or structure - 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) ### 3. Agent Tools (for chaining agents)
Reference other agents as tools to build multi-agent workflows Reference other agents as tools to build multi-agent workflows
**Schema:** **YAML Schema:**
\`\`\`json \`\`\`yaml
{ tool_key:
"type": "agent", type: agent
"name": "target_agent_name" name: target_agent_name
}
\`\`\` \`\`\`
**Required fields:** **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) - \`name\`: Name of the target agent (must exist in agents/ directory)
**Example:** **Example:**
\`\`\`json \`\`\`yaml
"summariser": { summariser:
"type": "agent", type: agent
"name": "summariser_agent" name: summariser_agent
}
\`\`\` \`\`\`
**How it works:** **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 - The target agent will be invoked with the parameters you pass
- Results are returned as tool output - Results are returned as tool output
- This is how you build multi-agent workflows - 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 ## Complete Multi-Agent Workflow Example
**Podcast creation workflow** - This is all done through agents calling other agents: **Podcast creation workflow** - This is all done through agents calling other agents:
**1. Task-specific agent** (does one thing): **1. Task-specific agent** (\`agents/summariser_agent.md\`):
\`\`\`json \`\`\`markdown
{ ---
"name": "summariser_agent", model: gpt-5.1
"description": "Summarises an arxiv paper", tools:
"model": "gpt-5.1", bash:
"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.", type: builtin
"tools": { name: executeCommand
"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**: **2. Agent that delegates to other agents** (\`agents/summarise-a-few.md\`):
\`\`\`json \`\`\`markdown
{ ---
"name": "summarise-a-few", model: gpt-5.1
"description": "Summarises multiple arxiv papers", tools:
"model": "gpt-5.1", summariser:
"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.", type: agent
"tools": { name: summariser_agent
"summariser": { ---
"type": "agent", # Summarise Multiple Papers
"name": "summariser_agent"
} 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): **3. Orchestrator agent** (\`agents/podcast_workflow.md\`):
\`\`\`json \`\`\`markdown
{ ---
"name": "podcast_workflow", model: gpt-5.1
"description": "Create a podcast from arXiv papers", tools:
"model": "gpt-5.1", bash:
"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.", type: builtin
"tools": { name: executeCommand
"bash": {"type": "builtin", "name": "executeCommand"}, summarise_papers:
"summarise_papers": { type: agent
"type": "agent", name: summarise-a-few
"name": "summarise-a-few" text_to_speech:
}, type: mcp
"text_to_speech": { name: text_to_speech
"type": "mcp", mcpServerName: elevenLabs
"name": "text_to_speech", description: Generate audio from text
"mcpServerName": "elevenLabs", inputSchema:
"description": "Generate audio", type: object
"inputSchema": { "type": "object", "properties": {...}} 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\` **To run this workflow**: \`rowboatx --agent podcast_workflow\`
## Naming and organization rules ## Naming and organization rules
- **All agents live in \`agents/*.json\`** - no other location - **All agents live in \`agents/*.md\`** - Markdown files with YAML frontmatter
- Agent filenames must match the \`"name"\` field exactly - Agent filename (without .md) becomes the agent name
- When referencing an agent as a tool, use its \`"name"\` value - When referencing an agent as a tool, use its filename without extension
- Always keep filenames and \`"name"\` fields perfectly aligned
- Use relative paths (no \${BASE_DIR} prefixes) when giving examples to users - Use relative paths (no \${BASE_DIR} prefixes) when giving examples to users
## Best practices for multi-agent design ## Best practices for multi-agent design
@ -273,85 +280,105 @@ Reference other agents as tools to build multi-agent workflows
## Validation & Best Practices ## Validation & Best Practices
### CRITICAL: Schema Compliance ### CRITICAL: Schema Compliance
- Agent files MUST have \`name\`, \`description\`, and \`instructions\` fields - Agent files MUST be valid Markdown with YAML frontmatter
- Agent filename MUST exactly match the \`name\` field - Agent filename (without .md) becomes the agent name
- Tools MUST have valid \`type\` ("builtin", "mcp", or "agent") - Tools in frontmatter MUST have valid \`type\` ("builtin", "mcp", or "agent")
- MCP tools MUST have all required fields: name, description, mcpServerName, inputSchema - MCP tools MUST have all required fields: name, description, mcpServerName, inputSchema
- Agent tools MUST reference existing agent files - Agent tools MUST reference existing agent files
- Invalid agents will fail to load and prevent workflow execution - Invalid agents will fail to load and prevent workflow execution
### File Creation/Update Process ### 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\` 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 3. Validate YAML syntax in frontmatter before writing—malformed YAML breaks the agent
4. Test agent loading after creation/update by using \`analyzeAgent\` 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 ### Common Validation Errors to Avoid
❌ **WRONG - Missing required fields:** ❌ **WRONG - Missing frontmatter delimiters:**
\`\`\`json \`\`\`markdown
{ model: gpt-5.1
"name": "my_agent" # My Agent
// Missing description and instructions Instructions here
}
\`\`\` \`\`\`
❌ **WRONG - Filename mismatch:** ❌ **WRONG - Invalid YAML indentation:**
- File: agents/my_agent.json \`\`\`markdown
- Content: {"name": "myagent", ...} ---
tools:
bash:
type: builtin
---
\`\`\`
(bash should be indented under tools)
❌ **WRONG - Invalid tool type:** ❌ **WRONG - Invalid tool type:**
\`\`\`json \`\`\`yaml
"tool1": { tools:
"type": "custom", // Invalid type tool1:
"name": "something" 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:** ❌ **WRONG - MCP tool missing required fields:**
\`\`\`json \`\`\`yaml
"search": { tools:
"type": "mcp", search:
"name": "firecrawl_search" type: mcp
// Missing: description, mcpServerName, inputSchema 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:** ✅ **CORRECT - Agent with MCP tool** (\`agents/search_agent.md\`):
\`\`\`json \`\`\`markdown
{ ---
"name": "simple_agent", model: gpt-5.1
"description": "A simple agent", tools:
"instructions": "Do simple tasks" 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:** Use the search tool to find information on the web.
\`\`\`json
"search": {
"type": "mcp",
"name": "firecrawl_search",
"description": "Search the web",
"mcpServerName": "firecrawl",
"inputSchema": {
"type": "object",
"properties": {
"query": {"type": "string"}
}
}
}
\`\`\` \`\`\`
## Capabilities checklist ## Capabilities checklist
1. Explore \`agents/\` directory to understand existing agents before editing 1. Explore \`agents/\` directory to understand existing agents before editing
2. Read existing agents with \`readFile\` before making changes 2. Read existing agents with \`workspace-readFile\` before making changes
3. Validate all required fields are present before creating/updating agents 3. Validate YAML frontmatter syntax before creating/updating agents
4. Ensure filename matches the \`name\` field exactly 4. Use \`analyzeAgent\` to verify agent structure after creation/update
5. Use \`analyzeAgent\` to verify agent structure after creation/update 5. When creating multi-agent workflows, create an orchestrator agent
6. When creating multi-agent workflows, create an orchestrator agent 6. Add other agents as tools with \`type: agent\` for chaining
7. Add other agents as tools with \`"type": "agent"\` for chaining 7. Use \`listMcpServers\` and \`listMcpTools\` when adding MCP integrations
8. Use \`listMcpServers\` and \`listMcpTools\` when adding MCP integrations 8. Confirm work done and outline next steps once changes are complete
9. Confirm work done and outline next steps once changes are complete
`; `;
export default skill; export default skill;