Browse Apps
Apps · Build

Workflows and Skills

Ship durable workflows that agents and the App start and follow as runs, and skills that each deploy publishes to a read-only collection users can copy.

5 min read

An App can also ship workflows (scripts BotDojo runs step by step, with agent steps and pauses that wait for a person) and skills (instructions for agents, published with each deploy).

Preview

Names and options on this page can change before general availability.

Declare a workflow

Declare a workflow in botdojo.app.ts and permit it in a role by name, like a function:

import { defineApp, defineWorkflow } from "@botdojo/app";

export const weeklyProjectDigest = defineWorkflow({
  name: "weekly_project_digest",
  description: "Summarize open projects and overdue tasks for the week.",
  source: "workflows/weekly-digest.workflow.ts",
  // Optional:
  connections: { crm: ["search_contacts"] },
  limits: { max_duration_ms: 20 * 60_000, max_subagents: 1, max_total_cost_usd: 1 },
});

export default defineApp({
  // ...
  roles: [{ key: "editor", label: "Editor", permits: { operations: ["weekly_project_digest"] } }],
  workflows: [weeklyProjectDigest],
});

Workflow and function names share one namespace. Rename with renamedFrom. A run that reaches a limit stops with an error:

LimitDefaultMaximum
max_duration_ms30 minutes6 hours
max_steps5005,000
max_tool_calls1,00010,000
max_subagents (agent steps; 0 for none)550
max_total_cost_usd5100

Write the script

The script is plain TypeScript, cannot import modules, and exports inputSchema, workflow, and optionally outputSchema and resultCard:

export const inputSchema = {
  type: "object",
  properties: { asOf: { type: "string", description: "YYYY-MM-DD" } },
  additionalProperties: false,
};

export const outputSchema = {
  type: "object",
  properties: { openProjects: { type: "number" }, summary: { type: "string" } },
  required: ["openProjects", "summary"],
};

export async function workflow(ctx) {
  const projects = await ctx.step({ key: "open_projects_v1", label: "List open projects" }, () =>
    ctx.tool("app://self", "list_projects", { where: [{ field: "phase", operator: "in", value: ["Intake", "Active"] }] }),
  );
  const digest = await ctx.agent({
    key: "summarize_v1",
    label: "Write the digest",
    // The agent reads only the prompt.
    prompt: `Summarize these projects in under 100 words:\n${JSON.stringify(projects.items)}`,
    outputSchema: { type: "object", properties: { text: { type: "string" } }, required: ["text"] },
  });
  const approval = await ctx.halt("approve_v1", { message: "File this digest?", text: digest.output.text });
  if (!approval.approved) return { openProjects: projects.items.length, summary: "Not filed." };
  return { openProjects: projects.items.length, summary: digest.output.text };
}

export function resultCard(ctx) {
  return `<p>${ctx.result.openProjects} open projects</p>`;
}
  • ctx.step keeps each step's result, so a resumed run skips finished steps.
  • ctx.halt pauses the run until the person who started it answers.
  • ctx.agent takes an optional model. It does not throw: on failure it returns status: "error" with the reason in error.

A run reaches only these, as the person who started it:

AddressWhat it reaches
app://selfThe App's functions and table operations, with that person's roles.
app://connections/<alias>A declared connection, with that person's permission. Ask before the run starts.
ctx.agentThat person's Workspace agent, or the agent the App runs as.

Workflows run on BotDojo only: botdojo-app dev and botdojo-app test check the files without running them.

Where runs live

A run never lives in the App's project. Run as, under Advanced in App settings, decides whose it is:

Run asThe run lives in
The person using the App (the default)That person's personal project
An agent identityThe agent's own project, for everyone who uses the App
  • With the default, a person must open their Workspace once before starting runs.
  • Only an administrator of the agent's own project can choose that agent.
  • Only the person who started a run can open, answer, or stop it. Project administrators of the App's project see each run's summary on the App's Activity tab.

Start and follow runs

On an App connection, each workflow the caller's roles permit is a tool named after it. Calling it starts a run and returns its run_id at once. Every workflow shares these run tools:

ToolDoes
workflow_runsLists the runs you started.
workflow_run_statusA run's status, steps, pending question, and result.
workflow_run_waitWaits until the run pauses or finishes, up to 50 seconds.
workflow_run_resumeAnswers a paused run.
workflow_run_abortStops a run.
workflow_run_readReads a stored file or a step's input or output.
show_workflow_runShows live progress in the chat.

Agents ask before starting, answering, or stopping a run unless an administrator allows those tools in the connection's settings.

The App's UI uses app.workflows, which also has list, runs, status, and abort:

const handle = await app.workflows.start("weekly_project_digest", { asOf: "2026-11-11" });
let run = await app.workflows.wait(handle.run_id, { timeoutMs: 15000 });
if (run.status === "waiting") run = await app.workflows.resume(handle.run_id, { approved: true });

Ship skills

Put each skill in its own folder, such as skills/project-intake/SKILL.md, and declare the folder:

defineApp({ /* ... */ skills: { dir: "skills" } });
  • SKILL.md starts with YAML frontmatter: name (the folder's name: lowercase letters, digits, and hyphens) and description.
  • Files are text only, at most 1 MB each and 200 per skill.
  • Each deploy publishes the skills to the environment's read-only skills collection. If that fails, the deploy stands and the Skills tab can publish again.
  • People use the collection as is, or choose Copy to my skills and edit the copy. Update brings in the App's later changes and keeps their edits.

Next steps