From fcd87a5f2a1d3911630f7a49e60fede52b36e446 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 8 Sep 2026 19:51:26 +0000 Subject: [PATCH] sync: update skills from runtypelabs/core@c00bb56 --- skills/runtype-admin/SKILL.md | 7 +--- skills/runtype-build-product/SKILL.md | 7 +--- skills/runtype-external-agents/SKILL.md | 50 +++++++++++++++++-------- skills/runtype-persona/SKILL.md | 7 +--- skills/runtype-sdk-marathon/SKILL.md | 6 +-- skills/runtype-templates/SKILL.md | 6 +-- skills/runtype/SKILL.md | 11 +----- skills/tool-design-composition/SKILL.md | 11 +----- skills/tool-design-errors/SKILL.md | 9 +---- skills/tool-design-execution/SKILL.md | 8 +--- skills/tool-design-interface/SKILL.md | 10 +---- skills/tool-design-output/SKILL.md | 8 +--- skills/tool-design-security/SKILL.md | 10 +---- skills/tool-design/SKILL.md | 11 +----- 14 files changed, 47 insertions(+), 114 deletions(-) diff --git a/skills/runtype-admin/SKILL.md b/skills/runtype-admin/SKILL.md index bb3894d..9237aeb 100644 --- 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 index a9b9273..efe6fcb 100644 --- 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 index c41fccd..c2b89d2 100644 --- 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,23 @@ 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. Logs marks +recognized Cloudflare invocation, chat, and tool diagnostics as incomplete with +an unknown outcome. Missing usage stays unknown; reported usage may be partial. +A trace with no +GenAI operation, model or inference signal, or recognized Runtype execution +telemetry stays in Logs as a diagnostic and creates no Run. Do not promise complete output, usage, or cancellation +status from those exports. Recognized Cloudflare approval lifecycle spans with a valid captured state and real tool-call id have a durable, read-only trace-local history: requested, approved, denied, and conflicts remain captured under that call id and source span. Missing lifecycle halves, source-span conflicts, and bounded-history omissions remain visible. This never authorizes or resumes a tool, supplies a resolver, reason, or duration, or joins distinct traces. Newly recorded structural history survives logging off and ingest-fact expiry; older runs without recorded history show it as unavailable, not proof that no approval occurred. The chip is withheld. **Flue on Node / Cloud Run / anywhere else.** Point exactly ONE Flue instrumentation at Runtype (two would double tokens and cost): @@ -103,9 +110,15 @@ OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf ``` Runtype reads `gen_ai.operation.name` = `invoke_agent` / `chat` / `execute_tool` (an HTTP -root span above them is fine) and the GenAI content attributes. Attribution per trace: -`runtype.agent.id` resource attribute → `x-runtype-agent-id` header → `runtype.agent.id` -on the `invoke_agent` span. One agent invocation per trace. +root span above them is fine) and the GenAI content attributes. Any nonempty +`gen_ai.operation.name` preserves trace projection, including a producer-specific operation. +Attribution per trace: `runtype.agent.id` resource attribute → `x-runtype-agent-id` header → +`runtype.agent.id` on the `invoke_agent` span. One agent invocation per trace. + +For OTLP traces, content fidelity (t1) reflects content present on the run. It can return +to baseline (t0) if later spans show that content belongs to another invocation or contradict earlier +data. Accepted Runtype-extension evidence (t2) is retained even if other content becomes invalid. +Neither tier guarantees complete telemetry. ## Lane B recipe @@ -155,8 +168,13 @@ a capability, or `generate_persona_embed_code` for a chat widget. returns `200 {}` when key and endpoint are right; `403` means the key lacks `TELEMETRY:WRITE`. - Run stuck "in flight": the closing `invoke_agent` span was never flushed. -- `ambiguous_agent_attribution` or no run at all: two invocations in one trace, or no - attribution source; set the resource attribute or header. +- `ambiguous_agent_attribution`: two invocations in one trace, or no attribution source; + set the resource attribute or header. +- No Run after an attributed export: no GenAI operation, model or inference signal, + or recognized Runtype execution telemetry. Runtype retains the trace as a + diagnostic in Logs. +- `500` while exporting a diagnostic trace: Runtype could not retain it durably. + Retry the export; Runtype has not accepted the trace. - Doubled tokens and cost: two instrumentations export to the same endpoint. - "No tool content in this trace": content capture is off on the producer. - `partial_success` in the exporter log: some traces named an agent the key cannot use. diff --git a/skills/runtype-persona/SKILL.md b/skills/runtype-persona/SKILL.md index fedfb41..ce06da0 100644 --- 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 index 0d38bea..4bb80b2 100644 --- 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 index 7fc376e..069c416 100644 --- 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 index 25ff549..ddba848 100644 --- 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 index 67d4464..2ae69b9 100644 --- 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 index 613322c..a6924f2 100644 --- 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 index f76bcc6..d0dc07c 100644 --- 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 index 9fd4b49..fb48e36 100644 --- 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 index 4708a4c..4c86bac 100644 --- 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 index a17c446..0e381c7 100644 --- 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 index 1b82ab3..eb92d17 100644 --- 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]' ---