From eef7e1d508926dfe9be6d01c0d8ac68bf0df56ba Mon Sep 17 00:00:00 2001 From: Arjun <6592213+arkml@users.noreply.github.com> Date: Wed, 4 Feb 2026 14:31:59 +0530 Subject: [PATCH] updated background agent skill --- .../skills/background-agents/skill.ts | 510 ++++++++++++++++++ .../src/application/assistant/skills/index.ts | 17 +- .../skills/workflow-authoring/skill.ts | 384 ------------- .../skills/workflow-run-ops/skill.ts | 95 ---- 4 files changed, 515 insertions(+), 491 deletions(-) create mode 100644 apps/x/packages/core/src/application/assistant/skills/background-agents/skill.ts delete mode 100644 apps/x/packages/core/src/application/assistant/skills/workflow-authoring/skill.ts delete mode 100644 apps/x/packages/core/src/application/assistant/skills/workflow-run-ops/skill.ts diff --git a/apps/x/packages/core/src/application/assistant/skills/background-agents/skill.ts b/apps/x/packages/core/src/application/assistant/skills/background-agents/skill.ts new file mode 100644 index 00000000..0b3fadd6 --- /dev/null +++ b/apps/x/packages/core/src/application/assistant/skills/background-agents/skill.ts @@ -0,0 +1,510 @@ +export const skill = String.raw` +# Background Agents + +Load this skill whenever a user wants to inspect, create, edit, or schedule background agents inside the Rowboat workspace. + +## Core Concepts + +**IMPORTANT**: In the CLI, there are NO separate "workflow" files. Everything is an agent. + +- **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 +- **Background agents run on schedules** defined in ` + "`~/.rowboat/config/agent-schedule.json`" + ` + +## How multi-agent workflows work + +1. **Create an orchestrator agent** that has other agents in its ` + "`tools`" + ` +2. **Schedule the orchestrator** in agent-schedule.json (see Scheduling section below) +3. The orchestrator calls other agents as tools when needed +4. Data flows through tool call parameters and responses + +## Scheduling Background Agents + +Background agents run automatically based on schedules defined in ` + "`~/.rowboat/config/agent-schedule.json`" + `. + +### Schedule Configuration File + +` + "```json" + ` +{ + "agents": { + "agent_name": { + "schedule": { ... }, + "enabled": true + } + } +} +` + "```" + ` + +### Schedule Types + +**1. Cron Schedule** - Runs at exact times defined by cron expression +` + "```json" + ` +{ + "schedule": { + "type": "cron", + "expression": "0 8 * * *" + }, + "enabled": true +} +` + "```" + ` + +Common cron expressions: +- ` + "`*/5 * * * *`" + ` - Every 5 minutes +- ` + "`0 8 * * *`" + ` - Every day at 8am +- ` + "`0 9 * * 1`" + ` - Every Monday at 9am +- ` + "`0 0 1 * *`" + ` - First day of every month at midnight + +**2. Window Schedule** - Runs once during a time window +` + "```json" + ` +{ + "schedule": { + "type": "window", + "cron": "0 0 * * *", + "startTime": "08:00", + "endTime": "10:00" + }, + "enabled": true +} +` + "```" + ` + +The agent will run once at a random time within the window. Use this when you want flexibility (e.g., "sometime in the morning" rather than "exactly at 8am"). + +**3. Once Schedule** - Runs exactly once at a specific time +` + "```json" + ` +{ + "schedule": { + "type": "once", + "runAt": "2024-02-05T10:30:00Z" + }, + "enabled": true +} +` + "```" + ` + +Use this for one-time tasks like migrations or setup scripts. + +### Complete Schedule Example + +` + "```json" + ` +{ + "agents": { + "daily_digest": { + "schedule": { + "type": "cron", + "expression": "0 8 * * *" + }, + "enabled": true + }, + "morning_briefing": { + "schedule": { + "type": "window", + "cron": "0 0 * * *", + "startTime": "07:00", + "endTime": "09:00" + }, + "enabled": true + }, + "one_time_setup": { + "schedule": { + "type": "once", + "runAt": "2024-12-01T12:00:00Z" + }, + "enabled": true + } + } +} +` + "```" + ` + +### Schedule State + +The runner tracks execution state in ` + "`~/.rowboat/config/agent-schedule-state.json`" + `: +- ` + "`status`" + `: scheduled, running, finished, failed, triggered (for once-schedules) +- ` + "`lastRunAt`" + `: When the agent last ran +- ` + "`nextRunAt`" + `: When the agent will run next +- ` + "`lastError`" + `: Error message if the last run failed +- ` + "`runCount`" + `: Total number of runs + +## Agent File Format + +Agent files are **Markdown files with YAML frontmatter**. The frontmatter contains configuration (model, tools), and the body contains the instructions. + +### Basic Structure +` + "```markdown" + ` +--- +model: gpt-5.1 +tools: + tool_key: + type: builtin + name: tool_name +--- +# Instructions + +Your detailed instructions go here in Markdown format. +` + "```" + ` + +### 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 + +### Instructions (Body) +The Markdown body after the frontmatter contains the agent's instructions. Use standard Markdown formatting. + +### Naming Rules +- 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 +- **The agent name in agent-schedule.json must match the filename** (without .md) + +### Agent Format Example +` + "```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 + +Tools in agents must follow one of three types. Each has specific required fields. + +### 1. Builtin Tools +Internal Rowboat tools (executeCommand, file operations, MCP queries, etc.) + +**YAML Schema:** +` + "```yaml" + ` +tool_key: + type: builtin + name: tool_name +` + "```" + ` + +**Required fields:** +- ` + "`type`" + `: Must be "builtin" +- ` + "`name`" + `: Builtin tool name (e.g., "executeCommand", "workspace-readFile") + +**Example:** +` + "```yaml" + ` +bash: + type: builtin + name: executeCommand +` + "```" + ` + +**Available builtin tools:** +- ` + "`executeCommand`" + ` - Execute shell commands +- ` + "`workspace-readFile`" + `, ` + "`workspace-writeFile`" + `, ` + "`workspace-remove`" + ` - File operations +- ` + "`workspace-readdir`" + `, ` + "`workspace-exists`" + `, ` + "`workspace-stat`" + ` - Directory operations +- ` + "`workspace-mkdir`" + `, ` + "`workspace-rename`" + `, ` + "`workspace-copy`" + ` - File/directory management +- ` + "`analyzeAgent`" + ` - Analyze agent structure +- ` + "`addMcpServer`" + `, ` + "`listMcpServers`" + `, ` + "`listMcpTools`" + ` - MCP management +- ` + "`loadSkill`" + ` - Load skill guidance + +### 2. MCP Tools +Tools from external MCP servers (APIs, databases, web scraping, etc.) + +**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:** +- ` + "`type`" + `: Must be "mcp" +- ` + "`name`" + `: Exact tool name from MCP server +- ` + "`description`" + `: What the tool does (helps agent understand when to use it) +- ` + "`mcpServerName`" + `: Server name from config/mcp.json +- ` + "`inputSchema`" + `: Full JSON Schema object for tool parameters + +**Example:** +` + "```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 + +### 3. Agent Tools (for chaining agents) +Reference other agents as tools to build multi-agent workflows + +**YAML Schema:** +` + "```yaml" + ` +tool_key: + type: agent + name: target_agent_name +` + "```" + ` + +**Required fields:** +- ` + "`type`" + `: Must be "agent" +- ` + "`name`" + `: Name of the target agent (must exist in agents/ directory) + +**Example:** +` + "```yaml" + ` +summariser: + type: agent + name: summariser_agent +` + "```" + ` + +**How it works:** +- 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.md`" + `) + +## Complete Multi-Agent Workflow Example + +**Podcast creation workflow** - This is all done through agents calling other agents: + +**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** (` + "`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** (` + "`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. +` + "```" + ` + +**4. Schedule the workflow** in ` + "`~/.rowboat/config/agent-schedule.json`" + `: +` + "```json" + ` +{ + "agents": { + "podcast_workflow": { + "schedule": { + "type": "cron", + "expression": "0 6 * * 1" + }, + "enabled": true + } + } +} +` + "```" + ` + +This schedules the podcast workflow to run every Monday at 6am. + +## Naming and organization rules +- **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 +- When scheduling an agent, use its filename without extension in agent-schedule.json +- Use relative paths (no \${BASE_DIR} prefixes) when giving examples to users + +## Best practices for background agents +1. **Single responsibility**: Each agent should do one specific thing well +2. **Clear delegation**: Agent instructions should explicitly say when to call other agents +3. **Autonomous operation**: Add "Don't ask for human input" for background agents +4. **Data passing**: Make it clear what data to extract and pass between agents +5. **Tool naming**: Use descriptive tool keys (e.g., "summariser", "fetch_data", "analyze") +6. **Orchestration**: Create a top-level agent that coordinates the workflow +7. **Scheduling**: Use appropriate schedule types - cron for recurring, window for flexible timing, once for one-time tasks +8. **Error handling**: Background agents should handle errors gracefully since there's no human to intervene + +## Validation & Best Practices + +### CRITICAL: Schema Compliance +- 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 valid Markdown + YAML frontmatter +2. When updating an agent, read it first with ` + "`workspace-readFile`" + `, modify, then use ` + "`workspace-writeFile`" + ` +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 frontmatter delimiters:** +` + "```markdown" + ` +model: gpt-5.1 +# My Agent +Instructions here +` + "```" + ` + +❌ **WRONG - Invalid YAML indentation:** +` + "```markdown" + ` +--- +tools: +bash: + type: builtin +--- +` + "```" + ` +(bash should be indented under tools) + +❌ **WRONG - Invalid tool type:** +` + "```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:** +` + "```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 - 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 + +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 ` + "`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. Configure schedules in ` + "`~/.rowboat/config/agent-schedule.json`" + ` +9. Confirm work done and outline next steps once changes are complete +`; + +export default skill; diff --git a/apps/x/packages/core/src/application/assistant/skills/index.ts b/apps/x/packages/core/src/application/assistant/skills/index.ts index 6ef19e8d..0d167a52 100644 --- a/apps/x/packages/core/src/application/assistant/skills/index.ts +++ b/apps/x/packages/core/src/application/assistant/skills/index.ts @@ -8,9 +8,8 @@ import mcpIntegrationSkill from "./mcp-integration/skill.js"; import meetingPrepSkill from "./meeting-prep/skill.js"; import organizeFilesSkill from "./organize-files/skill.js"; import slackSkill from "./slack/skill.js"; -import workflowAuthoringSkill from "./workflow-authoring/skill.js"; +import backgroundAgentsSkill from "./background-agents/skill.js"; import createPresentationsSkill from "./create-presentations/skill.js"; -import workflowRunOpsSkill from "./workflow-run-ops/skill.js"; const CURRENT_DIR = path.dirname(fileURLToPath(import.meta.url)); const CATALOG_PREFIX = "src/application/assistant/skills"; @@ -66,10 +65,10 @@ const definitions: SkillDefinition[] = [ content: slackSkill, }, { - id: "workflow-authoring", - title: "Workflow Authoring", - summary: "Creating or editing workflows/agents, validating schema rules, and keeping filenames aligned with JSON ids.", - content: workflowAuthoringSkill, + id: "background-agents", + title: "Background Agents", + summary: "Creating, editing, and scheduling background agents. Configure schedules in agent-schedule.json and build multi-agent workflows.", + content: backgroundAgentsSkill, }, { id: "builtin-tools", @@ -89,12 +88,6 @@ const definitions: SkillDefinition[] = [ summary: "Following the confirmation process before removing workflows or agents and their dependencies.", content: deletionGuardrailsSkill, }, - { - id: "workflow-run-ops", - title: "Workflow Run Operations", - summary: "Commands that list workflow runs, inspect paused executions, or manage cron schedules for workflows.", - content: workflowRunOpsSkill, - }, ]; const skillEntries = definitions.map((definition) => ({ 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 deleted file mode 100644 index bcd50258..00000000 --- a/apps/x/packages/core/src/application/assistant/skills/workflow-authoring/skill.ts +++ /dev/null @@ -1,384 +0,0 @@ -export const skill = String.raw` -# Agent and Workflow Authoring - -Load this skill whenever a user wants to inspect, create, or update agents inside the Rowboat workspace. - -## Core Concepts - -**IMPORTANT**: In the CLI, there are NO separate "workflow" files. Everything is an agent. - -- **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 - -## How multi-agent workflows work - -1. **Create an orchestrator agent** that has other agents in its \`tools\` -2. **Run the orchestrator**: \`rowboatx --agent orchestrator_name\` -3. The orchestrator calls other agents as tools when needed -4. Data flows through tool call parameters and responses - -## Agent File Format - -Agent files are **Markdown files with YAML frontmatter**. The frontmatter contains configuration (model, tools), and the body contains the instructions. - -### Basic Structure -\`\`\`markdown ---- -model: gpt-5.1 -tools: - tool_key: - type: builtin - name: tool_name ---- -# Instructions - -Your detailed instructions go here in Markdown format. -\`\`\` - -### 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 - -### Instructions (Body) -The Markdown body after the frontmatter contains the agent's instructions. Use standard Markdown formatting. - -### Naming Rules -- 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 -\`\`\`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 - -Tools in agents must follow one of three types. Each has specific required fields. - -### 1. Builtin Tools -Internal Rowboat tools (executeCommand, file operations, MCP queries, etc.) - -**YAML Schema:** -\`\`\`yaml -tool_key: - type: builtin - name: tool_name -\`\`\` - -**Required fields:** -- \`type\`: Must be "builtin" -- \`name\`: Builtin tool name (e.g., "executeCommand", "workspace-readFile") - -**Example:** -\`\`\`yaml -bash: - type: builtin - name: executeCommand -\`\`\` - -**Available builtin tools:** -- \`executeCommand\` - Execute shell commands -- \`workspace-readFile\`, \`workspace-writeFile\`, \`workspace-remove\` - File operations -- \`workspace-readdir\`, \`workspace-exists\`, \`workspace-stat\` - Directory operations -- \`workspace-mkdir\`, \`workspace-rename\`, \`workspace-copy\` - File/directory management -- \`analyzeAgent\` - Analyze agent structure -- \`addMcpServer\`, \`listMcpServers\`, \`listMcpTools\` - MCP management -- \`loadSkill\` - Load skill guidance - -### 2. MCP Tools -Tools from external MCP servers (APIs, databases, web scraping, etc.) - -**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:** -- \`type\`: Must be "mcp" -- \`name\`: Exact tool name from MCP server -- \`description\`: What the tool does (helps agent understand when to use it) -- \`mcpServerName\`: Server name from config/mcp.json -- \`inputSchema\`: Full JSON Schema object for tool parameters - -**Example:** -\`\`\`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 - -### 3. Agent Tools (for chaining agents) -Reference other agents as tools to build multi-agent workflows - -**YAML Schema:** -\`\`\`yaml -tool_key: - type: agent - name: target_agent_name -\`\`\` - -**Required fields:** -- \`type\`: Must be "agent" -- \`name\`: Name of the target agent (must exist in agents/ directory) - -**Example:** -\`\`\`yaml -summariser: - type: agent - name: summariser_agent -\`\`\` - -**How it works:** -- 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.md\`) - -## Complete Multi-Agent Workflow Example - -**Podcast creation workflow** - This is all done through agents calling other agents: - -**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** (\`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** (\`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/*.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 -1. **Single responsibility**: Each agent should do one specific thing well -2. **Clear delegation**: Agent instructions should explicitly say when to call other agents -3. **Autonomous operation**: Add "Don't ask for human input" for autonomous workflows -4. **Data passing**: Make it clear what data to extract and pass between agents -5. **Tool naming**: Use descriptive tool keys (e.g., "summariser", "fetch_data", "analyze") -6. **Orchestration**: Create a top-level agent that coordinates the workflow - -## Validation & Best Practices - -### CRITICAL: Schema Compliance -- 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 valid Markdown + YAML frontmatter -2. When updating an agent, read it first with \`workspace-readFile\`, modify, then use \`workspace-writeFile\` -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 frontmatter delimiters:** -\`\`\`markdown -model: gpt-5.1 -# My Agent -Instructions here -\`\`\` - -❌ **WRONG - Invalid YAML indentation:** -\`\`\`markdown ---- -tools: -bash: - type: builtin ---- -\`\`\` -(bash should be indented under tools) - -❌ **WRONG - Invalid tool type:** -\`\`\`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:** -\`\`\`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 - 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 - -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 \`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; diff --git a/apps/x/packages/core/src/application/assistant/skills/workflow-run-ops/skill.ts b/apps/x/packages/core/src/application/assistant/skills/workflow-run-ops/skill.ts deleted file mode 100644 index 25f62267..00000000 --- a/apps/x/packages/core/src/application/assistant/skills/workflow-run-ops/skill.ts +++ /dev/null @@ -1,95 +0,0 @@ -export const skill = String.raw` -# Agent Run Operations - -Package of repeatable commands for running agents, inspecting agent run history under ~/.rowboat/runs, and managing cron schedules. Load this skill whenever a user asks about running agents, execution history, paused runs, or scheduling. - -## When to use -- User wants to run an agent (including multi-agent workflows) -- User wants to list or filter agent runs (all runs, by agent, time range, or paused for input) -- User wants to inspect cron jobs or change agent schedules -- User asks how to set up monitoring for waiting runs - -## Running Agents - -**To run any agent**: -\`\`\`bash -rowboatx --agent -\`\`\` - -**With input**: -\`\`\`bash -rowboatx --agent --input "your input here" -\`\`\` - -**Non-interactive** (for automation/cron): -\`\`\`bash -rowboatx --agent --input "input" --no-interactive -\`\`\` - -**Note**: Multi-agent workflows are just agents that have other agents in their tools. Run the orchestrator agent to trigger the whole workflow. - -## Run monitoring examples -Operate from ~/.rowboat (Rowboat tools already set this as the working directory). Use executeCommand with the sample Bash snippets below, modifying placeholders as needed. - -Each run file name starts with a timestamp like '2025-11-12T08-02-41Z'. You can use this to filter for date/time ranges. - -Each line of the run file contains a running log with the first line containing information about the agent run. E.g. '{"type":"start","runId":"2025-11-12T08-02-41Z-0014322-000","agent":"agent_name","interactive":true,"ts":"2025-11-12T08:02:41.168Z"}' - -If a run is waiting for human input the last line will contain 'paused_for_human_input'. See examples below. - -1. **List all runs** - - ls ~/.rowboat/runs - - -2. **Filter by agent** - - grep -rl '"agent":""' ~/.rowboat/runs | xargs -n1 basename | sed 's/\.jsonl$//' | sort -r - - Replace with the desired agent name. - -3. **Filter by time window** - To the previous commands add the below through unix pipe - - awk -F'/' '$NF >= "2025-11-12T08-03" && $NF <= "2025-11-12T08-10"' - - Use the correct timestamps. - -4. **Show runs waiting for human input** - - awk 'FNR==1{if (NR>1) print fn, last; fn=FILENAME} {last=$0} END{print fn, last}' ~/.rowboat/runs/*.jsonl | grep 'pause-for-human-input' | awk '{print $1}' - - Prints the files whose last line equals 'pause-for-human-input'. - -## Cron management examples - -For scheduling agents to run automatically at specific times. - -1. **View current cron schedule** - \`\`\`bash - crontab -l 2>/dev/null || echo 'No crontab entries configured.' - \`\`\` - -2. **Schedule an agent to run periodically** - \`\`\`bash - (crontab -l 2>/dev/null; echo '0 10 * * * cd /path/to/cli && rowboatx --agent --input "input" --no-interactive >> ~/.rowboat/logs/.log 2>&1') | crontab - - \`\`\` - - Example (runs daily at 10 AM): - \`\`\`bash - (crontab -l 2>/dev/null; echo '0 10 * * * cd ~/rowboat-V2/apps/cli && rowboatx --agent podcast_workflow --no-interactive >> ~/.rowboat/logs/podcast.log 2>&1') | crontab - - \`\`\` - -3. **Unschedule/remove an agent** - \`\`\`bash - crontab -l | grep -v '' | crontab - - \`\`\` - -## Common cron schedule patterns -- \`0 10 * * *\` - Daily at 10 AM -- \`0 */6 * * *\` - Every 6 hours -- \`0 9 * * 1\` - Every Monday at 9 AM -- \`*/30 * * * *\` - Every 30 minutes -`; - -export default skill;