@keystrokehq/skills 0.0.1

package/keystroke-credential-binding/references/source-map.md

@@ -0,0 +1,69 @@
+# Credential Feature Map
+
+Use only the public imports a user repo can rely on:
+
+```ts
+import { CredentialSet } from '@keystrokehq/core';
+```
+
+## `CredentialSet` fields
+
+- `id`
+- `namespace`
+- `resolvedCredentialSetId`
+- `name`
+- `description`
+- `auth`
+- `stored`
+- `resolve`
+- `needsResolve`
+
+### What they are used for
+
+- `id`: stable credential set identifier
+- `namespace`: optional namespace used for manifest and storage identity
+- `resolvedCredentialSetId`: computed namespaced id used for manifest and binding infrastructure
+- `name`: human-readable name
+- `description`: short explanation of what the credentials are for
+- `auth`: runtime credential schema
+- `stored`: stored credential schema when the stored shape differs from the runtime shape
+- `resolve`: async conversion from stored values to runtime auth values
+- `needsResolve`: tells you whether the credential set uses the stored-plus-resolve flow
+
+## `CredentialSet` instance methods
+
+- `describe()`
+- `toManifest()`
+
+## Where a credential set can be attached
+
+- `Operation.credentialSets`
+- `Step.credentialSets`
+- `Tool.credentialSets`
+- `Agent.credentialSets`
+- `CronTrigger.credentialSets`
+- `WebhookTrigger.credentialSets`
+- `PollingTrigger.credentialSets`
+- `MessagingGateway.credentialSet`
+- `McpServer.credentialSets`
+
+## Where credentials can be read
+
+- `Operation.run(..., ctx).credentials`
+- `Step.run(..., ctx).credentials`
+- `Tool.run(..., ctx).credentials`
+- trigger `verify` callback and polling trigger `poll` callback (`filter`, `idempotencyKey`, and `transform` do not receive credentials)
+- `McpServer.credentialMapper(credentials)`
+
+## Important rules
+
+- `Operation`, `Step`, and `Tool` are aliases for the same class
+- if `stored` is present, `resolve` must also be present
+- if `resolve` is present, `stored` must also be present
+- prefer typed access through runtime context rather than ad hoc env access inside primitives
+- runtime credential context keys use raw `id`, not `resolvedCredentialSetId`
+
+## Where to read next
+
+- `patterns.md` for code examples
+- `cli.md` for upload and inspection commands

package/keystroke-data-toolkit/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: keystroke-data-toolkit
+description: Use Keystroke workflow-tool refs and data companion tools. Use when an agent needs to author, explain, debug, or consume large workflow tool outputs with read_ref, slice_ref, describe_ref, truncation metadata, or deferred reducers.
+---
+
+# Keystroke Data Toolkit
+
+Use this skill when working with large workflow-tool outputs, ref envelopes, or auto-injected data companion tools.
+
+Keep this skill focused on workflow-tool data handling:
+- use `../keystroke-workflow-authoring/SKILL.md` for workflow code and replay-safe orchestration
+- use `../keystroke-agent-authoring/SKILL.md` for agent and tool registration
+- use `../keystroke-workflow-as-tool-debugging/SKILL.md` for debugging a failed workflow-tool run
+
+## Current Product Behavior
+
+Workflow tool outputs are capped before they enter LLM context. A workflow that may produce large output should opt into refs:
+
+```ts
+new Workflow({
+  id: 'export-audit-data',
+  name: 'Export Audit Data',
+  largeResultMode: 'ref',
+  // ...
+});
+```
+
+When the output exceeds the cap, the platform stores the result and returns a small ref envelope with `inline: false`, a `ref` URI, `mimeType`, `byteSize`, and a summary.
+
+## Companion Tools
+
+Agents with workflow tools get bounded ref inspection tools when eligible:
+- `describe_ref` returns shape, size, summary, and available ranges
+- `read_ref` reads a byte, line, or row range
+- `slice_ref` extracts a JSONPath-addressable subset from JSON refs
+
+Reads are bounded. If a requested slice is still too large, the response includes truncation metadata such as `truncated: true` and guidance to request a smaller range.
+
+## Rules
+
+- Prefer `describe_ref` before reading unknown large refs.
+- Use narrow `read_ref` ranges; do not ask for the full payload by default.
+- Treat `truncated: true` as a signal to request a smaller or more specific range.
+- Keep refs scoped to the current agent run; cross-run access is not supported.
+- Do not add or teach reducer tools as active behavior. Reducers are deferred; reducer calls return unsupported validation guidance.
+- Do not introduce DuckDB or native reducer dependencies unless the product explicitly reopens reducers.
+
+## Default Process
+
+1. Check whether the workflow should use `largeResultMode: 'ref'`.
+2. Inspect the ref with `describe_ref`.
+3. Read only the smallest useful slice with `read_ref` or `slice_ref`.
+4. If truncated, narrow the request and try again.
+5. If computation over large tabular refs is needed, explain that reducers are currently deferred and use bounded samples instead.
+
+## References
+
+Read these files as needed:
+- `references/usage.md` for examples of ref envelopes and companion tool usage

package/keystroke-data-toolkit/evals/evals.json

@@ -0,0 +1,23 @@
+{
+  "skill_name": "keystroke-data-toolkit",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "My workflow tool can return a few megabytes of audit rows. How should I configure the workflow and how should the agent inspect the result?",
+      "expected_output": "Recommends largeResultMode: 'ref', explains the ref envelope, and uses describe_ref/read_ref/slice_ref with bounded ranges.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "The agent called read_ref and got truncated: true. What should it do next?",
+      "expected_output": "Explains that truncation is signaled and the agent should request a narrower range or targeted slice rather than assuming it saw all data.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Can we add DuckDB reducers for this large CSV workflow output?",
+      "expected_output": "States that reducers and DuckDB are deferred in the active product and recommends bounded ref reads or samples instead.",
+      "files": []
+    }
+  ]
+}

package/keystroke-data-toolkit/references/usage.md

@@ -0,0 +1,79 @@
+# Data Toolkit Usage
+
+Read this file when the user needs concrete patterns for large workflow-tool outputs.
+
+## Ref-Producing Workflow
+
+```ts
+import { Workflow } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const exportAuditData = new Workflow({
+  id: 'export-audit-data',
+  name: 'Export Audit Data',
+  description: 'Exports audit rows for an account.',
+  largeResultMode: 'ref',
+  input: z.object({
+    accountId: z.string(),
+  }),
+  output: z.array(
+    z.object({
+      accountId: z.string(),
+      eventType: z.string(),
+      createdAt: z.string(),
+    })
+  ),
+  run: async () => [],
+});
+```
+
+Use `largeResultMode: 'ref'` when large output is legitimate and useful. Do not use refs to hide unbounded or poorly scoped workflows; prefer narrower workflow inputs when possible.
+
+## Ref Envelope
+
+The LLM receives a small envelope instead of the full output:
+
+```json
+{
+  "inline": false,
+  "ref": "blob://run/wfr_abc/output",
+  "mimeType": "application/json",
+  "byteSize": 1048576,
+  "summary": {
+    "kind": "tabular",
+    "rows": 10000,
+    "columns": [
+      { "name": "accountId", "type": "string", "nullPct": 0 },
+      { "name": "eventType", "type": "string", "nullPct": 0 }
+    ]
+  }
+}
+```
+
+## Recommended Agent Flow
+
+1. Call the workflow tool.
+2. If the result has `inline: false`, call `describe_ref({ ref })`.
+3. Read a small sample such as `read_ref({ ref, rowRange: [0, 20] })`.
+4. Use `slice_ref` for targeted JSONPath extraction from JSON refs.
+5. If a response is truncated, reduce the requested range.
+
+## Bounded Reads
+
+Good requests are specific:
+
+```json
+{ "ref": "blob://run/wfr_abc/output", "rowRange": [0, 25] }
+```
+
+Avoid full-payload reads:
+
+```json
+{ "ref": "blob://run/wfr_abc/output", "rowRange": [0, 1000000] }
+```
+
+If a read returns `truncated: true`, the agent should not summarize as if it saw all data. It should either request a smaller range or explain that it has inspected only a sample.
+
+## Deferred Reducers
+
+Reducer tools are not part of the active product. Do not teach agents to call `reduce_ref`, `query_ref`, SQL-over-ref tools, or DuckDB-backed helpers. If a reducer-shaped payload appears, expect unsupported validation guidance and fall back to bounded reads and samples.

package/keystroke-task-authoring/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: keystroke-task-authoring
+description: Build Keystroke tasks with @keystrokehq/core. Use when the user wants to author a trigger-driven agent task, define task prompts with trigger templates, configure task lifecycle, or run focused task deploys instead of full workflows.
+---
+
+# Keystroke Task Authoring
+
+Use this skill when an agent needs to write or change Keystroke task code.
+
+Keep this skill focused on authored task code:
+
+- use `../keystroke-agent-authoring/SKILL.md` for the agent itself
+- use `../keystroke-trigger-authoring/SKILL.md` for trigger authoring details
+- use `../keystroke-workflow-authoring/SKILL.md` when the automation needs durable orchestration
+- use `../keystroke-cli-workspace/SKILL.md` for `deploy --target`, build, and debugging flows
+
+## Quick start
+
+```ts
+import { Task, webhookTrigger } from '@keystrokehq/core';
+import { z } from 'zod';
+import { welcomeAgent } from './welcome.agent';
+
+const welcomeWebhookTrigger = webhookTrigger({
+  name: 'Welcome Webhook',
+  description: 'Receives welcome payloads.',
+  source: {
+    type: 'custom',
+    method: 'POST',
+    path: '/welcome',
+  },
+  payload: z.object({
+    name: z.string(),
+  }),
+});
+
+export const welcomeWebhookTask = new Task({
+  id: 'welcome-webhook-task',
+  name: 'Welcome Webhook Task',
+  description: 'Uses a webhook payload to drive one agent run.',
+  agent: welcomeAgent,
+  prompt:
+    'Write a greeting for this webhook payload: {{trigger.payload}}. Trigger name: {{trigger.name}}.',
+  triggers: [welcomeWebhookTrigger],
+  lifecycle: {
+    maxExecutions: 1,
+  },
+  tags: ['welcome', 'webhook', 'task'],
+});
+```
+
+## Authoring model
+
+Teach this mental model clearly:
+
+- a task is a trigger-driven agent run
+- a task combines an `agent`, a `prompt`, and one or more `triggers`
+- a task is not a workflow-lite wrapper
+- a task does not replace a workflow when durable orchestration is needed
+
+Use a task when the real job is:
+
+- external event or schedule arrives
+- prompt is resolved from trigger context
+- agent runs once for that task execution
+
+## Trigger model
+
+Task triggers are authored as normal triggers but attached differently than workflow triggers.
+
+Teach these rules:
+
+- define the trigger normally in `*.trigger.ts`
+- place the trigger in `Task.triggers`
+- do not call `trigger.attach(task, ...)`
+- use workflow attachments only for workflows
+
+## Prompt templating
+
+Teach the supported task prompt variables:
+
+- `{{trigger.payload}}`
+- `{{trigger.name}}`
+- `{{trigger.type}}`
+
+Use prompt templating when the agent prompt should include structured trigger context without inventing a separate payload mapping layer.
+
+## Lifecycle
+
+Use task lifecycle when execution limits matter:
+
+- `maxExecutions`
+- `expiresAt`
+- `expiresAfter`
+
+## Task vs workflow
+
+Choose a task when:
+
+- the automation is one agent run driven by triggers
+- the user wants a prompt-first agent execution path
+- durable workflow orchestration is not the main requirement
+
+Choose a workflow when:
+
+- the automation needs multiple steps
+- the automation needs waits or hooks
+- the automation needs branching or child workflows
+- the automation coordinates multiple agents or agent-plus-step flows
+
+## Task rules
+
+- Keep each exported task in its own `*.task.ts` file.
+- Keep the referenced agent in its own `*.agent.ts` file.
+- Keep triggers in their own `*.trigger.ts` files.
+- Use Zod v4 syntax in all examples and authored code. See `../../../.agents/rules/zod-v4-requirements.md`.
+- Keep task prompts explicit about what the agent should do with trigger data.
+
+## References
+
+Read these files as needed:
+
+- `references/source-map.md` for the public task surface
+- `references/patterns.md` for task examples and the task-vs-workflow decision guide

package/keystroke-task-authoring/evals/evals.json

@@ -0,0 +1,23 @@
+{
+  "skill_name": "keystroke-task-authoring",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I want a Keystroke task that runs an agent every time a webhook fires and includes the webhook payload in the prompt. How should I author that?",
+      "expected_output": "Explains Task authoring, inline triggers, prompt templating with trigger context, and keeps workflow attachments out of the task path.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Should this be a workflow or a task? The job is just: cron fires, agent writes a summary, then stop.",
+      "expected_output": "Chooses Task, explains why the task model fits better than workflow orchestration, and mentions deploy --target for focused task deploys.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "How do I limit a Keystroke task to run once and expire after a week?",
+      "expected_output": "Explains task lifecycle fields such as maxExecutions and expiresAfter with authored code examples.",
+      "files": []
+    }
+  ]
+}

package/keystroke-task-authoring/references/patterns.md

@@ -0,0 +1,132 @@
+# Task Patterns
+
+Read this file when the user wants concrete task-authoring examples.
+
+## Webhook-driven task
+
+```ts
+import { Task, webhookTrigger } from '@keystrokehq/core';
+import { z } from 'zod';
+import { triageAgent } from './triage.agent';
+
+const inboundWebhook = webhookTrigger({
+  name: 'Inbound Webhook',
+  description: 'Receives inbound payloads.',
+  source: {
+    type: 'custom',
+    method: 'POST',
+    path: '/inbound',
+  },
+  payload: z.object({
+    message: z.string(),
+    priority: z.enum(['low', 'high']),
+  }),
+});
+
+export const inboundTask = new Task({
+  id: 'inbound-task',
+  name: 'Inbound Task',
+  agent: triageAgent,
+  prompt:
+    'Triage this inbound payload: {{trigger.payload}}. Trigger type: {{trigger.type}}.',
+  triggers: [inboundWebhook],
+});
+```
+
+## Cron-driven task
+
+```ts
+import { cronTrigger, Task } from '@keystrokehq/core';
+import { z } from 'zod';
+import { reportAgent } from './report.agent';
+
+const dailyReportTrigger = cronTrigger({
+  name: 'Daily Report Trigger',
+  description: 'Runs each morning.',
+  input: z.object({
+    mode: z.literal('daily'),
+  }),
+  payload: {
+    mode: 'daily',
+  },
+  schedule: '0 9 * * *',
+});
+
+export const dailyReportTask = new Task({
+  id: 'daily-report-task',
+  name: 'Daily Report Task',
+  agent: reportAgent,
+  prompt: 'Generate the daily report for {{trigger.name}} using {{trigger.payload}}.',
+  triggers: [dailyReportTrigger],
+});
+```
+
+## Polling-driven task
+
+```ts
+import { pollingTrigger, Task } from '@keystrokehq/core';
+import { z } from 'zod';
+import { followUpAgent } from './follow-up.agent';
+
+const staleTicketPolling = pollingTrigger({
+  name: 'Stale Ticket Polling',
+  description: 'Polls for stale tickets.',
+  schedule: '*/15 * * * *',
+  response: z.object({
+    ticketId: z.string(),
+    status: z.string(),
+  }),
+  poll: async () => ({
+    ticketId: 'ticket_123',
+    status: 'stale',
+  }),
+  filter: (payload) => payload.status === 'stale',
+});
+
+export const staleTicketTask = new Task({
+  id: 'stale-ticket-task',
+  name: 'Stale Ticket Task',
+  agent: followUpAgent,
+  prompt: 'Follow up on stale ticket data: {{trigger.payload}}.',
+  triggers: [staleTicketPolling],
+});
+```
+
+## Lifecycle examples
+
+```ts
+lifecycle: {
+  maxExecutions: 1,
+}
+```
+
+```ts
+lifecycle: {
+  expiresAfter: '7d',
+}
+```
+
+```ts
+lifecycle: {
+  expiresAt: new Date('2026-12-31T23:59:59.000Z'),
+}
+```
+
+## Task vs workflow
+
+Choose a task when:
+- the job is one agent run from trigger input
+- prompt templating is the main input mapping layer
+- there is no need for durable orchestration across multiple steps
+
+Choose a workflow when:
+- the automation has multiple step boundaries
+- waits or hooks are required
+- orchestration logic is as important as the agent run
+- the automation mixes steps, child workflows, and agents
+
+## Gotchas
+
+- Do not use `trigger.attach(...)` for tasks.
+- Do not explain tasks as conversation entrypoints. Messaging gateways handle conversations.
+- Do not move workflow orchestration into the task prompt.

package/keystroke-task-authoring/references/source-map.md

@@ -0,0 +1,61 @@
+# Task Feature Map
+
+Use only the public imports a user repo can rely on:
+
+```ts
+import { Task, type TaskConfig, type TaskLifecycle } from '@keystrokehq/core';
+```
+
+## `Task` fields
+
+- `id`
+- `name`
+- `description`
+- `agent`
+- `prompt`
+- `triggers`
+- `lifecycle`
+- `tags`
+
+## `Task` instance methods
+
+- `describe()`
+- `toManifest()`
+
+## `TaskLifecycle`
+
+- `maxExecutions`
+- `expiresAt`
+- `expiresAfter`
+
+## `TriggerContext`
+
+- `payload`
+- `name`
+- `type`
+
+The current public trigger context `type` values are:
+- `cron`
+- `polling`
+- `provider`
+- `webhook`
+
+## Prompt template tokens
+
+Task prompts support a small set of template tokens that the platform resolves
+at run time (just before the agent is invoked). Authors write the tokens
+directly into the `prompt` string — there is no function to call.
+
+Supported tokens:
+- `{{trigger.payload}}` — resolved to `JSON.stringify` of the trigger payload
+- `{{trigger.name}}` — resolved to the trigger name
+- `{{trigger.type}}` — resolved to the trigger type (one of `cron`, `polling`, `provider`, `webhook`)
+
+Unknown `{{...}}` tokens are left as-is in the resolved prompt.
+
+## Task notes
+
+- tasks reference an agent through `agent`
+- tasks list triggers directly in `triggers`
+- tasks do not use `TriggerAttachment`
+- tasks are deployed through `keystroke deploy` or focused with `keystroke deploy --target <task.task.ts>`