Run a skill and poll for the result

The job

Run one of the organisation's skills, a packaged way of doing a task, wait for it in the background, and give the person what it produced.

Prerequisites

The person who connected is an admin or staff user. A member's connection never has skill tools.
The connection holds skills:run.
The skill is enabled for external use, so its skill_<name> tool is in your tool list. See the skill tools for the conditions.

Steps

The example skill is weekly-digest. It declares one parameter, weekStart.

Find the skill tool in your tool list, skill_weekly-digest, and read its description. The description says what the skill does and which arguments it takes. To read about skills in general, call:
```
{ "section": "skills" }
```

Start the run. Call the skill tool once.

{ "weekStart": "2026-09-28" }

{
  "executionId": "3f2b9c1e-7a4d-4e8b-9c61-2d5f0a8b7e14",
  "status": "running",
  "note": "The skill is running in the background. Call checkExecution with this executionId (wait a minute or two between polls); results may also be written into the knowledge base."
}

Keep the executionId. Each call to the skill tool starts a new run, so do not call it again to check on this run. Tell the person that the run started and that it usually takes 1 to 10 minutes.

Wait a minute or two, then poll the run.

{ "executionId": "3f2b9c1e-7a4d-4e8b-9c61-2d5f0a8b7e14" }

While status is running, wait a minute or two and poll again. When the run ends, the result looks like this:

{
  "executionId": "3f2b9c1e-7a4d-4e8b-9c61-2d5f0a8b7e14",
  "skill": "weekly-digest",
  "status": "completed",
  "resultStatus": "completed",
  "summary": "Wrote the digest for the week of 28 September from the meeting notes and the proposal log.",
  "outputPath": "northwind-advisory/digests/2026-09-28-weekly-digest.md",
  "error": null,
  "startedAt": "2026-10-02T09:14:05.112Z",
  "completedAt": "2026-10-02T09:18:22.406Z",
  "durationMs": 257294
}

Read the output. Pass outputPath to readDoc as path, with no project.
```
{ "path": "northwind-advisory/digests/2026-09-28-weekly-digest.md" }
```
If outputPath is null, the skill saved no document in the knowledge base. Give the person the summary. If the skill description says that it writes somewhere else, use searchKnowledge to find the output.

What can go wrong

status is failed or timeout: this is not a refusal. Read error, tell the person, and start the skill again only if the cause is gone.
MCP error -32602: Input validation error: Invalid arguments for tool skill_weekly-digest: …: an argument has the wrong type, or a required parameter is missing. No run started. Read the tool's input schema and call again. An argument that the schema does not name is removed without an error, so check the spelling of each argument.
Error in checkExecution: Execution not found: <executionId>: no skill run has that id. Pass the executionId exactly as the skill tool returned it.
MCP error -32602: Tool skill_weekly-digest not found: the connection does not hold skills:run, or the skill is not enabled for external use, or it does not exist. Read the permissions section of getDocs. Only admin and staff can hold skills:run.

Run a skill and poll for the result

The job

Prerequisites

Steps

What can go wrong

Related notes