mirror of
https://github.com/rowboatlabs/rowboat.git
synced 2026-04-26 00:46:23 +02:00
fix assistant to use md for agents
This commit is contained in:
Arjun
Ramnique Singh
parent
8b02daab61
commit
d10a27c8eb
3 changed files with 374 additions and 340 deletions
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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
|
||||
\`\`\`
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue