runtypelabs · bookernath · Sep 7, 2026
diff --git a/skills/runtype-admin/SKILL.md b/skills/runtype-admin/SKILL.md
@@ -1,11 +1,6 @@
 ---
 name: runtype-admin
-description: >-
-  Use when operating a live Runtype account through MCP or Code Mode MCP: inspect resources,
-  debug failed flows or agents, read logs and traces, manage products, surfaces, records,
-  schedules, secrets, models, evals, batches, conversations, client tokens, or make safe
-  account mutations. Includes search/execute patterns, read-before-write, validation,
-  pagination, and conservative destructive-change policy.
+description: 'Inspect, debug, or manage a live Runtype account through MCP or CLI; mutate only within the requested scope.'
 user-invocable: true
 argument-hint: '[live account operation or debugging task]'
 ---

diff --git a/skills/runtype-build-product/SKILL.md b/skills/runtype-build-product/SKILL.md
@@ -1,11 +1,6 @@
 ---
 name: runtype-build-product
-description: >-
-  Use when building, designing, validating, or deploying Runtype AI products with agents,
-  flows, tools, surfaces, records, secrets, schedules, evals, orchestration, webhooks,
-  Slack/email/SMS/Telegram/Discord/WhatsApp/iMessage/messaging/chat/API/MCP/A2A/hosted-page
-  surfaces, commerce tools, agent skills, or hosted product generation. Always fetch current MCP build
-  instructions before creating resources.
+description: 'Build or modify Runtype-hosted AI products, agents, flows, and surfaces using current platform instructions.'
 user-invocable: true
 argument-hint: '[product idea or build task]'
 ---

diff --git a/skills/runtype-external-agents/SKILL.md b/skills/runtype-external-agents/SKILL.md
@@ -1,13 +1,6 @@
 ---
 name: runtype-external-agents
-description: >-
-  Use when an agent runs outside Runtype's hosted execution (Flue, the Cloudflare Agents
-  SDK, Vercel AI SDK, LangChain, or a custom loop) and the user wants Runtype's
-  observability, traces, eval capture, Persona chat, surfaces, or the trace-to-eval
-  improvement loop for it. Covers OpenTelemetry/OTLP ingest, @runtypelabs/flue-otel vs
-  @flue/opentelemetry, Flue on Cloudflare Workers, telemetry API keys, registering a
-  runtype-stream or A2A endpoint so Runtype can call the agent, and which features each
-  path unlocks. Not for agents Runtype itself executes.
+description: 'Connect externally executed agents to Runtype traces, evals, or surfaces; not Runtype-hosted execution.'
 user-invocable: true
 argument-hint: '[framework and what you want from Runtype: traces, evals, chat UI]'
 ---
@@ -73,9 +66,18 @@ content on by default). Export to Runtype:
 
 To keep prompts and tool payloads out of the export, add
 `instrument(createCloudflareTracing({ content: false }))` from `@flue/runtime/cloudflare`
-at module scope in `app.ts`, and tell the user this also removes eval capture. Cloudflare
-Agents SDK and Think apps use the same destination; Think stores no payloads unless the
-agent class sets `storeMessages = true` and `storeTools = true`.
+at module scope in `app.ts`, and tell the user this also removes eval capture. Think apps
+use the same destination and store no payloads unless the agent class sets
+`storeMessages = true` and `storeTools = true`.
+
+**Cloudflare Agents SDK (`agents`): not zero-code; logical-run support is incomplete.** The app must call
+`wrapAISDK(ai, { storeMessages: true, storeTools: true })` from `agents/observability/ai`
+(content is off by default) and use the same Workers Observability destination as above.
+Local captures grouped WebSocket turns into one trace; deployed captures used distinct
+traces for turns and approval continuations. Runtype files one run per trace, so one
+request paused for approval can appear as multiple runs. Slow and cancelled deployed
+turns also emitted `span_not_ended` warnings with missing GenAI fields. Do not promise
+complete output, usage, or cancellation status from those exports. The chip is withheld.
 
 **Flue on Node / Cloud Run / anywhere else.** Point exactly ONE Flue instrumentation at
 Runtype (two would double tokens and cost):

diff --git a/skills/runtype-persona/SKILL.md b/skills/runtype-persona/SKILL.md
@@ -1,11 +1,6 @@
 ---
 name: runtype-persona
-description: >-
-  Use when embedding, deploying, configuring, styling, or debugging Runtype Persona chat
-  widgets, fullscreen AI assistant layouts, chat surfaces, client-token installs, theme
-  tokens, artifacts, tool/reasoning visibility, programmatic widget access, WebMCP page
-  tools, or browser-side local tools. Prefer generate_persona_embed_code and
-  get_persona_theme_reference over hand-written snippets.
+description: 'Embed, style, or debug Runtype Persona widgets and browser-side chat integrations.'
 user-invocable: true
 argument-hint: '[Persona widget or chat UI task]'
 ---

diff --git a/skills/runtype-sdk-marathon/SKILL.md b/skills/runtype-sdk-marathon/SKILL.md
@@ -1,10 +1,6 @@
 ---
 name: runtype-sdk-marathon
-description: >-
-  Use when working with the Runtype TypeScript or Python SDK, FlowBuilder, BatchBuilder,
-  EvalBuilder, CLI commands, Marathon long-running agent tasks, playbooks, model fallback,
-  built-in CLI tools, sandboxes, code-first stored/upsert/virtual agents or flows, local
-  tools, hidden parameters, or source-controlled Runtype workflows.
+description: 'Build source-controlled Runtype workflows with the SDK or CLI, including Marathon tasks and playbooks.'
 user-invocable: true
 argument-hint: '[SDK, CLI, or Marathon task]'
 ---

diff --git a/skills/runtype-templates/SKILL.md b/skills/runtype-templates/SKILL.md
@@ -1,10 +1,6 @@
 ---
 name: runtype-templates
-description: >-
-  Use when creating, validating, exporting, importing, or improving Runtype Full Product
-  Object templates. Covers FPO and FPO template structure, template variables, pending
-  secrets, setup-required auth, validate_product and validate_product_* checks,
-  distributable product packaging, import readiness, and avoiding credential leakage.
+description: 'Create, validate, or package distributable Runtype FPO templates and their setup requirements.'
 user-invocable: true
 argument-hint: '[FPO or template task]'
 ---

diff --git a/skills/runtype/SKILL.md b/skills/runtype/SKILL.md
@@ -1,15 +1,6 @@
 ---
 name: runtype
-description: >-
-  Runtype umbrella skill for onboarding and routing. Use when the user mentions Runtype,
-  asks what Runtype can build, needs MCP/CLI/dashboard setup, or wants to scope an AI
-  product on Runtype. Route hands-on product builds to runtype-build-product, live account
-  ops to runtype-admin, Persona widgets to runtype-persona, FPO packaging to
-  runtype-templates, SDK/CLI/Marathon work to runtype-sdk-marathon, and agents that run
-  outside Runtype (Flue, Cloudflare Agents SDK, Vercel AI SDK, LangChain, custom loops;
-  OpenTelemetry traces, flue-otel, eval capture from external runs) to
-  runtype-external-agents. Do not use for generic LLM chat or non-AI infrastructure
-  unless Runtype is explicitly part of the request.
+description: 'Scope a Runtype project or set up platform access; route implementation to the relevant Runtype skill.'
 user-invocable: true
 argument-hint: '[Runtype goal or setup question]'
 ---

diff --git a/skills/tool-design-composition/SKILL.md b/skills/tool-design-composition/SKILL.md
@@ -1,15 +1,6 @@
 ---
 name: tool-design-composition
-description: >-
-  Use when shaping a set of agent tools rather than one tool: bundling common
-  sequences into task tools, batch variants, preview and dry-run modes, abstraction
-  ladders from raw to intent-level, explicit tool chains, scatter-gather across
-  sources, and how agents discover tools (registry, layered schema exploration,
-  dependency hints, capability search, health checks). Also covers gateways,
-  adapters for legacy APIs, canonical models, and versioning. Trigger phrases: "too
-  many tools", "agent calls the same three tools every time", "bundle these
-  operations", "batch tool", "dry run mode", "tool discovery", "wrap this legacy API",
-  "tool versioning".
+description: 'Compose and expose agent toolsets: task-level operations, batching, discovery, dry runs, and versioning.'
 user-invocable: true
 argument-hint: '[tool set to organize or extend]'
 ---

diff --git a/skills/tool-design-errors/SKILL.md b/skills/tool-design-errors/SKILL.md
@@ -1,13 +1,6 @@
 ---
 name: tool-design-errors
-description: >-
-  Use when designing how a tool fails for an AI agent: error messages that guide
-  recovery, classifying errors as retryable, permanent, needs-user-input, or
-  needs-auth, confirmation requests for ambiguous input, fuzzy-match thresholds,
-  graceful degradation with partial results, and fallback tools. Trigger phrases:
-  "tool error message", "agent keeps retrying", "agent gives up after an error",
-  "ambiguous match", "which user did it mean", "raw 429", "error handling for agent
-  tools", "recovery guidance".
+description: 'Design actionable agent tool errors, ambiguity handling, retry guidance, and fallback behavior.'
 user-invocable: true
 argument-hint: '[tool whose failure paths to design]'
 ---

diff --git a/skills/tool-design-execution/SKILL.md b/skills/tool-design-execution/SKILL.md
@@ -1,12 +1,6 @@
 ---
 name: tool-design-execution
-description: >-
-  Use when deciding how an agent tool executes: synchronous versus async job with
-  polling, idempotency keys so retries are safe, transactional boundaries,
-  compensation for cross-system multi-step operations, and timeout boundaries with
-  partial results. Trigger phrases: "long-running tool", "tool times out", "agent
-  retried and created a duplicate", "idempotent tool", "job id and poll", "rollback
-  when a step fails", "async tool for the agent", "saga".
+description: 'Design agent tool execution: async jobs, idempotency, timeouts, transactions, and compensation.'
 user-invocable: true
 argument-hint: '[tool whose execution semantics to design]'
 ---

diff --git a/skills/tool-design-interface/SKILL.md b/skills/tool-design-interface/SKILL.md
@@ -1,14 +1,6 @@
 ---
 name: tool-design-interface
-description: >-
-  Use when writing or fixing the contract an AI agent sees for a tool: the name, the
-  description, and the parameter schema. Covers descriptions written for model
-  comprehension, enums and ranges instead of free-form strings, smart defaults,
-  natural identifiers resolved internally, exactly-one-of parameter rules, performance
-  hints, flexible input coercion, and marking query versus command tools. Trigger
-  phrases: "tool description", "write the tool schema", "parameter names for the
-  agent", "agent passes the wrong format", "agent picks the wrong tool", "too many
-  required parameters", "JSON schema for an MCP tool".
+description: 'Design agent-facing tool names, descriptions, and parameter schemas; diagnose incorrect tool selection or inputs.'
 user-invocable: true
 argument-hint: '[tool whose name, description, or parameters to design]'
 ---

diff --git a/skills/tool-design-output/SKILL.md b/skills/tool-design-output/SKILL.md
@@ -1,12 +1,6 @@
 ---
 name: tool-design-output
-description: >-
-  Use when deciding what a tool should return to an AI agent: shaping raw API
-  responses, keeping results token-efficient, cursor pagination, summary-versus-full
-  detail, per-item results for batch calls, GUI links, next-action hints, resource
-  references for large payloads, and canonical data models across a tool set. Trigger
-  phrases: "tool response shape", "response too large", "context window blown by tool
-  output", "pagination for the agent", "what should the tool return", "partial success".
+description: 'Design agent tool results, including pagination, partial success, context size, and actionable next steps.'
 user-invocable: true
 argument-hint: '[tool whose result shape to design]'
 ---

diff --git a/skills/tool-design-security/SKILL.md b/skills/tool-design-security/SKILL.md
@@ -1,14 +1,6 @@
 ---
 name: tool-design-security
-description: >-
-  Use when deciding how an agent tool handles identity, credentials, permissions,
-  scope, and state: injecting secrets server-side instead of through the model,
-  permission gates enforced in code, declared OAuth scopes, audit trails, a
-  who-am-i identity anchor, session context, automatic context injection, and
-  context boundaries such as tenant scope or root paths. Trigger phrases: "API key
-  as a tool parameter", "the agent leaked a secret", "prompt says the agent can't
-  delete", "tenant isolation for tools", "who_am_i tool", "audit log for tool
-  calls", "OAuth scopes per tool".
+description: 'Design tool identity, credential injection, authorization, tenant scope, and audit boundaries.'
 user-invocable: true
 argument-hint: '[tool or toolkit whose trust boundary to design]'
 ---

diff --git a/skills/tool-design/SKILL.md b/skills/tool-design/SKILL.md
@@ -1,15 +1,6 @@
 ---
 name: tool-design
-description: >-
-  Use when designing, building, or reviewing tools that an AI agent will call: MCP
-  server tools, function-calling schemas, agent toolkits, runtime tools, or an API
-  being wrapped for an LLM. Covers classifying a tool (query, command, discovery;
-  sync or async; atomic to orchestrated), the four rules every tool must satisfy, a
-  pre-ship checklist, and an audit procedure for an existing tool set. Routes deeper
-  work to tool-design-interface, tool-design-output, tool-design-errors,
-  tool-design-composition, tool-design-execution, and tool-design-security. Trigger
-  phrases: "design a tool", "tool schema", "MCP tool", "function calling", "agent
-  can't figure out which tool", "review my tools", "why does the agent keep retrying".
+description: 'Design or audit an AI agent toolset; route naming, schemas, output, errors, execution, and security to focused guides.'
 user-invocable: true
 argument-hint: '[tool or tool set to design or review]'
 ---