@keystrokehq/skills 0.0.1

package/AGENTS-blurb.md

@@ -0,0 +1,123 @@
+# Keystroke Project Context
+
+You are working inside a Keystroke project. Keystroke is a code-first workflow and agent automation platform. Authors define workflows, agents, operations, tasks, triggers, messaging gateways, MCP servers, sandboxes, and credential bindings in TypeScript, then build and deploy them with the Keystroke CLI.
+
+When reasoning about authored code, use this top-level split:
+
+- A `Workflow` is deterministic orchestration. Its `run(...)` method coordinates steps, child workflows, waits, hooks, and agents.
+- An `Agent` is model-driven execution. It runs with agent tools, can use sandboxes, MCP servers, and messaging gateways, and is the right place for llm driven work.
+- A `Task` is the trigger-driven agent path. It combines triggers, a prompt, and an agent run.
+- A workflow can also be registered as an agent tool. Sync workflow tools return inline results; suspending workflow tools yield and resume later; large outputs can return refs inspected with bounded data toolkit tools.
+
+Triggers, tasks, and agent conversations are different entry models:
+
+- a workflow is started by a trigger or direct invocation
+- a trigger is a code-based primitive you author in TypeScript and attach to a workflow
+- a trigger attaches to a workflow and resolves external payload into validated workflow input
+- a trigger is not a chat session; it is an ingress boundary that transforms payload and starts a workflow
+- a task is not attached with `trigger.attach(...)`; it lists triggers inline and resolves a prompt for an agent run
+- an agent conversation is a chat session, not a code-authored primitive like `CronTrigger`, `WebhookTrigger`, or `PollingTrigger`
+- conversations can be started from the UI, from messaging adapters such as Slack, Linear, or GitHub, or from a workflow when the workflow runs an agent
+- messaging gateways configure conversational entry on agents; they are not workflow triggers
+- an agent keeps full context of the conversation session while the workflow side stays replay-safe and stateless between execution boundaries
+
+Keystroke also has one shared unit-of-work primitive: `Operation`.
+
+- `Operation`, `Step`, and `Tool` are aliases for the same class from `@keystrokehq/core`.
+- Use the `Step` name when teaching workflow-side usage.
+- Use the `Tool` name when teaching agent-side usage.
+- Use the `Operation` name when describing shared infrastructure, integrations, or a reusable unit that can be used in both places.
+- The runtime behavior comes from context, not from which alias name was used in the constructor.
+
+Runtime boundary:
+
+- workflows and steps are authored as TypeScript control-flow and unit-of-work code
+- workflows do not run bash commands as part of the workflow authoring model
+- agents are the correct place for bash, filesystem work, and sandbox-managed dependencies such as Python
+
+Keystroke workflow execution is replay-based and stateless at the workflow layer:
+
+- Keystroke does not persist live in-memory workflow state.
+- Instead, it persists execution events and terminal results for execution boundaries, then replays the workflow code from the top with that saved state.
+- The workflow body itself is re-executed during replay. Local variables and control flow are recomputed, not resumed from memory.
+- Because of that, workflow code must be replay-safe and deterministic.
+
+Treat these calls inside `Workflow.run(...)` as execution boundaries:
+
+- `await step.run(...)`
+- `await operation.run(...)`
+- `await childWorkflow.run(...)`
+- `await agent.run(...)`
+
+What gets persisted:
+
+- For steps, Keystroke persists created/completed/failed state and reuses the saved result during workflow replay.
+- For child workflows, Keystroke persists the child run and its terminal result, then resumes the parent workflow with that saved outcome.
+- For agents, Keystroke persists agent execution state and terminal output, then resumes the workflow with that saved result.
+- The workflow's own in-memory logic is not persisted. The platform saves boundary state, not the live workflow stack.
+
+Where code runs:
+
+- Operations used as workflow steps are low-level units of work and run in separate worker executions.
+- Child workflows run as separate workflow executions in their own workers, using the same replay model as parent workflows.
+- Agents run outside the workflow replay worker. They run in persisted sandboxes with a persistent filesystem, where they can use files, shell commands, installed skills, MCP servers, and other runtime tools. The filesystem persists over all agent runs for a deployed agent.
+- Operations used as agent tools are not top-level orchestration units. A tool runs inside the agent runtime when the agent chooses to call it, inside that persisted sandbox context.
+
+Workflow triggers versus agent conversations:
+
+- use code-authored triggers when external schedules, webhook requests, or polling results should become workflow input
+- use agent conversations when a user or system is chatting with an agent over time
+- author triggers in code; do not think of conversations as authored primitives in the same way
+- messaging adapters normalize inbound events into thread-based conversations, and the agent responds inside that conversation context
+- a workflow can still start an agent-backed conversation by running an agent, but that is different from a workflow trigger boundary
+
+Authoring implications:
+
+- Put orchestration, branching, loops, waits, and composition in workflows.
+- Put deterministic side effects and integration calls in operations used as steps.
+- Put LLM-driven reasoning and tool selection in agents.
+- Put concrete callable actions in operations used as tools.
+- Use `largeResultMode: 'ref'` plus `describe_ref`, `read_ref`, and `slice_ref` for large workflow-tool outputs. Reducers and DuckDB-backed data tools are deferred.
+- Use `midSessionSnapshot: true` only for measured workflow-tool cases that need Phase D replay. Current snapshot behavior is conversation-log replay, not native Pi process restore.
+- Do not depend on workflow-local mutable state, random values, direct network I/O, or filesystem mutations in the workflow body itself unless they happen behind a Keystroke execution boundary.
+- Never assume workflow-local memory or filesystem state survives between replays. If state must survive, return it from an operation, agent, or child workflow, or persist it externally.
+
+## Workflow Builder File Structure
+
+The workflow builder now relies on explicit file structure. Teach and author Keystroke code with one exported primitive per typed file:
+
+- `*.workflow.ts` for one `Workflow`
+- `*.step.ts`, `*.tool.ts`, or `*.operation.ts` for one exported `Operation`
+- `*.agent.ts` for one `Agent`
+- `*.gateway.ts` for one `MessagingGateway`
+- `*.trigger.ts` for one trigger
+- `*.credential-set.ts` for one `CredentialSet`
+- `*.mcp-server.ts` for one `McpServer`
+
+Builder note:
+
+- `*.step.ts`, `*.tool.ts`, and `*.operation.ts` all validate as the same operation convention
+- choose the suffix that communicates intent to the reader
+
+Required structure:
+
+- exported primitives should be top-level and statically visible
+- helper files such as `schemas.ts`, `utils.ts`, or `prompts.ts` should not export primitives
+- a `*.trigger.ts` file may also export that trigger's `TriggerAttachment` values
+- tests are exempt, but authored project code should follow the typed-file convention everywhere
+
+Example layout:
+
+```text
+customer-support/
+  crm-api.credential-set.ts
+  lookup-customer.tool.ts
+  support.agent.ts
+  support.gateway.ts
+  triage.step.ts
+  support.workflow.ts
+  support.trigger.ts
+  coding.sandbox.ts
+  docs.mcp-server.ts
+  schemas.ts
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keystroke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# @keystrokehq/skills
+
+Canonical Keystroke-authored agent skills live in this package.
+
+## Purpose
+
+This package is the source of truth for Keystroke-specific skills that teach agents how to author Keystroke projects and write code for Keystroke primitives.
+
+The packaged skills are:
+
+- `keystroke-workflow-authoring`
+- `keystroke-agent-authoring`
+- `keystroke-data-toolkit`
+- `keystroke-workflow-as-tool-debugging`
+- `keystroke-credential-binding`
+- `keystroke-trigger-authoring`
+- `keystroke-task-authoring`
+- `keystroke-cli-workspace`
+
+## Editing
+
+Edit the source files in `packages/skills/`.
+
+Do not treat local editor skill directories as the source of truth for these packaged skills. Edit the canonical files in `packages/skills/` first, then use the Keystroke CLI skill sync flow when local `.cursor/skills` or `.claude/skills` copies need to be refreshed.
+
+## Structure
+
+Each skill follows this structure:
+
+```text
+<skill-name>/
+├── SKILL.md
+├── references/
+│   ├── source-map.md
+│   └── ...
+└── evals/
+    └── evals.json
+```
+
+- `SKILL.md` stays concise and procedural.
+- `references/` holds longer examples, source maps, and gotchas.
+- `evals/evals.json` stores the initial evaluation prompts used with `.agents/skills/skill-creator/`.
+
+## Wiring
+
+These packaged skills are intended to be copied into local editor skill directories through the Keystroke CLI:
+
+- packaged skills are authored here
+- `keystroke skills sync` copies them into `.cursor/skills` and `.claude/skills`
+
+If the discovery story changes later, update this package and the sync flow together. Until then, edit the packaged skills here first.
+
+Because these are repo-authored local skills rather than externally installed skills, they do not require new `skills-lock.json` entries.
+
+## Authoring Process
+
+Draft and refine these skills with the existing `.agents/skills/skill-creator/` workflow:
+
+1. Draft the skill
+2. Add realistic eval prompts to `evals/evals.json`
+3. Run at least one evaluation pass
+4. Revise the skill based on results
+5. Improve the `description` once the body is stable

package/keystroke-agent-authoring/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: keystroke-agent-authoring
+description: Build Keystroke agents with @keystrokehq/core plus provider credentials from @keystroke/integration-ai. Use when the user wants to author, refactor, explain, or test Keystroke agent code, tool code, messaging gateways, sandboxed coding agents, MCP servers, or agent credential wiring.
+---
+
+# Keystroke Agent Authoring
+
+Use this skill when an agent needs to write or change Keystroke agent code or tool code.
+
+Keep this skill focused on authored agent code:
+- use `../keystroke-workflow-authoring/SKILL.md` for workflow orchestration
+- use `../keystroke-data-toolkit/SKILL.md` for refs and large workflow-tool outputs
+- use `../keystroke-workflow-as-tool-debugging/SKILL.md` for workflow-tool run/debug workflows
+- use `../keystroke-task-authoring/SKILL.md` for trigger-driven agent tasks
+- use `../keystroke-trigger-authoring/SKILL.md` for trigger authoring
+- use `../keystroke-credential-binding/SKILL.md` for credential design and binding
+- use `../keystroke-cli-workspace/SKILL.md` for setup, build, deploy, and logs
+
+## Quick start
+
+Author one exported primitive per typed file.
+
+`crm-api.credential-set.ts`
+
+```ts
+import { CredentialSet } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const crmCredentials = new CredentialSet({
+  id: 'crmApi',
+  name: 'CRM API',
+  auth: z.object({
+    apiKey: z.string(),
+  }),
+});
+```
+
+`lookup-customer.tool.ts`
+
+```ts
+import { Tool } from '@keystrokehq/core';
+import { z } from 'zod';
+import { crmCredentials } from './crm-api.credential-set';
+
+export const lookupCustomerTool = new Tool({
+  id: 'lookup_customer',
+  name: 'Lookup Customer',
+  description: 'Returns a customer record by email address.',
+  credentialSets: [crmCredentials],
+  input: z.object({
+    email: z.email(),
+  }),
+  output: z.object({
+    customerId: z.string(),
+    email: z.email(),
+  }),
+  run: async (input, ctx) => ({
+    customerId: `customer:${ctx.credentials.crmApi.apiKey}:${input.email}`,
+    email: input.email,
+  }),
+});
+```
+
+`support.agent.ts`
+
+```ts
+import { anthropic } from '@keystroke/integration-ai';
+import { Agent } from '@keystrokehq/core';
+import { lookupCustomerTool } from './lookup-customer.tool';
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  description: 'Looks up a customer and drafts a response.',
+  systemPrompt:
+    'Look up the customer first. Use the tool result in the answer. Do not guess missing data.',
+  model: 'anthropic/claude-sonnet-4-20250514',
+  credentialSets: [anthropic],
+  tools: [lookupCustomerTool],
+  maxSteps: 8,
+});
+```
+
+## Authoring model
+
+Teach this mental model clearly:
+- an agent is an LLM-driven worker
+- a `Tool` is the agent-facing alias for `Operation`
+- authored agents use `new Agent({...})` from `@keystrokehq/core`
+- AI provider credentials such as `anthropic` and `openai` come from `@keystroke/integration-ai`
+- agents operate through conversations and agent runs, not workflow trigger attachments
+- workflows can call agents, but workflows still own orchestration
+- agents can use workflows as tools; sync workflows return inline and suspending workflows yield/resume
+
+## Workflows as tools
+
+An agent `tools` array can contain both operations and workflows:
+
+```ts
+new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  systemPrompt: 'Help users',
+  model: 'anthropic/claude-sonnet-4-20250514',
+  credentialSets: [anthropic],
+  tools: [lookupCustomerTool, auditAccountWorkflow],
+});
+```
+
+Workflow tools are classified during build/enrichment. Non-suspending workflows return inline results. Suspending workflows return a `pending: true` yield receipt, end the model's turn, and resume later with the resolved workflow result. If a workflow opts into `midSessionSnapshot: true`, the current Phase D path resumes through scoped conversation-log replay rather than native Pi process restore.
+
+Workflow tool outputs are capped before entering LLM context. Workflows with `largeResultMode: 'ref'` can return a small ref envelope for large results; the data toolkit tools `describe_ref`, `read_ref`, and `slice_ref` are auto-injected when workflow tools are present. Reducer tools are not auto-injected.
+
+When any yield-mode workflow tool is present, the platform also injects companion tools such as `provide_workflow_response`, `cancel_workflow`, and `check_workflow_status` so the model can resolve hooks, cancel in-flight workflow tools, or check status safely.
+
+## Manual API Execution
+
+Agents can be interacted with on-demand via the Keystroke API.
+
+### Executing an Agent Conversation
+Users can start a new agent conversation directly.
+- **Endpoint**: `POST /api/v1/agents/[agentId]/conversations`
+- **Body requirements**: Needs a `title`.
+- **Response**: Returns the `conversationId` for subsequent interactions.
+
+## Conversations, tasks, and gateways
+
+Use the right entry language:
+- workflows are entered by triggers
+- tasks are entered by triggers and then resolve a prompt for an agent run
+- agents can also be entered through messaging gateways and conversations
+- a `MessagingGateway` is not a trigger
+- `Agent.messaging` is where agent conversation entrypoints are configured
+
+Teach MessagingGateway inside the agent surface:
+- use `MessagingGateway` when the user wants Slack, GitHub, or Linear conversational entry for an agent
+- default to `mode: 'platform'` — a platform app is a Keystroke-owned app that the user installs into their workspace
+- use `mode: 'custom'` only when the user explicitly says they want to create their own app or use an app they already manage
+- do not use `appRef` on platform gateways
+- use `Task` when the user wants “trigger -> prompt -> agent run”
+- use a workflow when the user wants durable orchestration across multiple steps or agents
+
+## Runtime boundary
+
+Agents are the right place for shell and filesystem-oriented work.
+
+Teach these rules explicitly:
+- workflows do not run bash commands as part of their authoring model
+- agents can execute bash commands when they have the appropriate tools and sandbox runtime
+- if the agent needs Python or another binary, it must exist in the sandbox or be installed during sandbox setup
+
+## Default agent process
+
+1. Decide whether the job really needs an agent.
+2. Write the agent’s job in one sentence.
+3. Look for a prebuilt integration operation before writing a custom tool.
+4. Author the agent with `new Agent({...})`.
+5. Keep each exported primitive in its own typed file.
+6. Add only the tools, credentials, MCP servers, skills, and messaging gateways the job actually needs.
+7. If the agent belongs inside a larger automation, call it from a workflow or task instead of moving orchestration into the agent.
+
+## Agent rules
+
+- Prefer `new Agent({...})` from `@keystrokehq/core` for authored agents.
+- Prefer `Tool` for custom agent operations.
+- Every custom `Tool` / `Operation` must include a stable `id`.
+- Tool ids must be unique within an agent after integration namespacing.
+- Keep each exported messaging gateway in its own `*.gateway.ts` file.
+- Keep tool selection aligned with the agent’s job.
+- Do not wrap an existing integration operation in a redundant custom tool.
+- Use `CredentialSet` for custom secrets and use provider credential sets from `@keystroke/integration-ai` for model auth.
+- Do not use `process.env` in authored agent or tool code.
+- Expect the default agent sandbox to be persistent.
+- Create a custom `Sandbox` only when the default sandbox needs customization.
+- Follow Zod v4 syntax in examples and authored code. See `../../../.agents/rules/zod-v4-requirements.md`.
+
+## Agent Guidelines for Custom Tools & Operations
+
+When an agent needs to write custom tools or operations, it must follow these rules:
+1. **Always use prebuilt tools/operations** if they exist before writing custom ones.
+2. **Collect context first**: Do you have all the information you need from the user? If not, ask the user to clarify what they are looking for. **Do Not Guess**.
+3. **Understand API payloads**: If using an API endpoint to fetch data, search the provider's docs to understand the payloads. If possible, hit available endpoints to inspect the actual payloads.
+4. **Always write and run tests**: You must always write tests for new tools and operations. Always run the tests to make sure that the new tools run (see `references/testing.md`).
+5. **Handle missing credentials**: If you cannot run tests because of missing credentials, ask the user to configure them following the `../keystroke-credential-binding/SKILL.md` skill. The user will need to upload credentials before deploying anyway.
+
+## Important agent fields
+
+Teach these first:
+- `id`
+- `name`
+- `description`
+- `systemPrompt`
+- `model`
+- `tools`
+- `credentialSets`
+- `mcpServers`
+- `sandbox`
+- `messaging`
+- `skills`
+- `maxSteps`
+
+Call out these runtime details when relevant:
+- `allCredentialSets` includes credentials from the agent, tools, MCP servers, and messaging gateways
+- `runtimeKind` distinguishes declarative-only agents from runnable or streamable agents
+
+## When to choose an agent
+
+Choose an agent when the job needs:
+- LLM reasoning in a loop
+- dynamic tool selection
+- coding-agent behavior in a sandbox
+- filesystem work that persists through the agent runtime
+- messaging-based conversational entry
+
+Do not choose an agent when a normal workflow step is enough.
+
+## References
+
+Read these files as needed:
+- `references/source-map.md` for the public agent, tool, sandbox, MCP, and messaging surface
+- `references/patterns.md` for field-by-field agent and tool examples
+- `references/messaging-gateways.md` for gateway authoring
+- `references/sandbox-and-mcp.md` for sandbox runtime, bash, files, MCP, and dependency setup
+- `references/testing.md` for agent and tool testing patterns
+- `references/prebuilt-integrations.md` for integration operations to use in `tools`

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

@@ -0,0 +1,29 @@
+{
+  "skill_name": "keystroke-agent-authoring",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I need a Keystroke agent that can look up Slack users and DM one of them. What fields should I set up, and where do tools and credentials go?",
+      "expected_output": "Explains the canonical Keystroke agent path, the important agent fields, tool configuration, and the credential relationship between the agent and its tools.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Should this be a Step or an agent? The task is to inspect some repo files, decide what changed, and then call a couple of tools depending on what it finds.",
+      "expected_output": "Explains when an agent is appropriate, when a normal step would be better, and how workflow orchestration relates to agent scope.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Show me how to build a sandboxed Keystroke coding agent that can work in a checked-out repo and maybe use MCP later if needed.",
+      "expected_output": "Uses the public sandbox and MCP patterns, points to MCP references when needed, and keeps workflow orchestration separate.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "I want my Keystroke agent to answer messages from GitHub conversations. Should I use a trigger or something else?",
+      "expected_output": "Explains that conversational entry belongs on Agent.messaging with a MessagingGateway, not on workflow triggers, and keeps the distinction between tasks, triggers, and conversations clear.",
+      "files": []
+    }
+  ]
+}