Custom Agent Integration

You have access to SkillzDrive skills via MCP tools.
The skill catalog is dynamic — new skills are added regularly.

To find skills for a task:
- Call skills_searchSkills with a relevant query to find specific skills (e.g. "pdf", "image")
- Call skills_listSkills to browse all available skills

Then follow the execution workflow:
1. Call skills_listScripts on the skill slug to see available scripts
2. Call skills_runScript with reuseSession: true to execute
3. Read output via skills_readFile, then close the session with skills_closeSession

NEVER guess skill slugs or script names — always discover via searchSkills or listSkills first.
Always use reuseSession: true and read output via skills_readFile.
Always close sessions with skills_closeSession when done.

// On agent startup — run once, cache for the session
const { results } = await mcpClient.callTool("skills_listSkills", {});

const skillList = results
  .map((s) => `- ${s.slug}: ${s.description} (${s.hasScripts ? "has scripts" : "template-based"})`)
  .join("\n");

const systemPrompt = `You have access to SkillzDrive skills via MCP.

Available skills:
${skillList}

When the user asks for help with these tasks, use the appropriate skill.
Always call skills_listScripts before skills_runScript.`;

// Orchestrator: discover dynamically, then delegate
const { results } = await mcpClient.callTool("skills_searchSkills", {
  query: userTask, // e.g. "merge these PDFs"
});
const skill = results[0]; // best match

// Pin the skill slug to a sub-agent's context
const subAgentPrompt = `You are a ${skill.name} specialist.
Use skill slug: ${skill.slug}
Go directly to skills_listScripts → skills_runScript → skills_readFile → skills_closeSession.
Do NOT call searchSkills or listSkills — your skill is already assigned.`;

// Sub-agent now runs with zero discovery overhead
await spawnSubAgent(subAgentPrompt);

// Hook into MCP tool call events for real-time UI feedback
agent.onToolCall((toolName, args) => {
  switch (toolName) {
    case "skills_searchSkills":
      showStatus("Searching for skills...");
      break;
    case "skills_listScripts":
      showStatus(`Loading scripts for ${args.skillSlug}...`);
      break;
    case "skills_runScript":
      showStatus(`Running ${args.scriptName}...`);
      break;
    case "skills_readFile":
      showStatus("Reading results...");
      break;
    case "skills_closeSession":
      // No UI needed — cleanup is silent
      break;
  }
});

agent.onToolResult((toolName, result) => {
  if (toolName === "skills_runScript") {
    if (result.exitCode === 0) {
      showStatus("Script completed successfully", "success");
    } else {
      showStatus(result.error || "Script failed", "error");
    }
  }
});

// Error response structure
{
  "error": "skill_not_found",           // Machine-readable code
  "message": "No skill with slug 'pdff'", // Show this to users
  "suggestions": [                       // Show as recovery options
    "Did you mean 'pdf'?",
    "Use skills_searchSkills to find skills"
  ],
  "_workflow": {                         // Use for automatic recovery
    "nextSteps": [
      { "tool": "skills_searchSkills", "example": { "query": "pdf" } }
    ]
  }
}

// Display pattern:
// 1. Show `message` as the error text
// 2. Show `suggestions[0]` as a clickable recovery action
// 3. Use `_workflow.nextSteps` to auto-recover if possible
// 4. NEVER show raw JSON-RPC errors to users

async function executeSkillAsync(
  mcpClient: McpClient,
  skillSlug: string,
  scriptName: string,
  args?: string[]
) {
  // 1. Show immediate feedback
  notify("Starting skill execution...", "loading");

  // 2. Run the script
  const runResult = await mcpClient.callTool("skills_runScript", {
    skillSlug,
    scriptName,
    args,
    reuseSession: true,
  });

  // 3. Handle failure
  if (runResult.exitCode !== 0) {
    notify(`Error: ${runResult.error}`, "error");
    return null;
  }

  // 4. Read the output
  const output = await mcpClient.callTool("skills_readFile", {
    sessionId: runResult.sessionId,
    filePath: "/tmp/last_run.out",
  });

  // 5. Show results
  notify("Skill completed!", "success");
  displayOutput(output.content);

  // 6. Clean up
  await mcpClient.callTool("skills_closeSession", {
    sessionId: runResult.sessionId,
  });

  return output.content;
}