@keystrokehq/skills 0.0.1

package/keystroke-agent-authoring/references/sandbox-and-mcp.md

@@ -0,0 +1,214 @@
+# Sandbox And MCP Examples
+
+Read this file when the user asks about coding agents, filesystem access, MCP servers, or sandbox setup.
+
+Every Keystroke agent already gets a persistent sandbox by default. Create a custom `Sandbox` primitive only when the default sandbox needs customization such as extra dependencies, file sources, setup commands, or runtime options.
+
+## Bash and runtime boundary
+
+Teach this contrast explicitly:
+- agents can run bash commands when they have the appropriate agent tools and sandbox runtime
+- if an agent needs Python, `jq`, or another binary, that tool must already exist in the sandbox image or be installed through `setupCommands` or runtime preparation
+- if the user needs shell-heavy work, prefer an agent over a workflow or step
+
+File layout reminder:
+
+- keep each exported sandbox in its own `*.sandbox.ts` file
+- keep each exported MCP server in its own `*.mcp-server.ts` file
+- keep each exported agent in its own `*.agent.ts` file
+- keep any credential set used by an MCP server in its own `*.credential-set.ts` file
+
+## `Sandbox`
+
+```ts
+import { Sandbox } from '@keystrokehq/core';
+
+export const repoSandbox = new Sandbox({
+  id: 'repo-sandbox',
+  name: 'Repo Sandbox',
+  description: 'Checks out a repo and prepares it for a coding agent.',
+  fileSources: [
+    { type: 'git', url: 'https://github.com/acme/demo-repo.git', branch: 'main' },
+    { type: 'local', path: './fixtures/shared-files' },
+  ],
+  setupCommands: ['pnpm install'],
+  runtime: {
+    env: {
+      NODE_ENV: 'development',
+    },
+    runCommands: ['pnpm test:unit'],
+    workdir: '/workspace/demo-repo',
+  },
+});
+```
+
+What these fields do:
+
+- `id`: stable sandbox identifier
+- `name`: human-readable sandbox name
+- `description`: what the sandbox is for
+- `fileSources`: files or repos to place into the sandbox
+- `setupCommands`: commands to prepare the environment
+- `runtime.env`: environment variables inside the sandbox runtime
+- `runtime.runCommands`: commands the runtime may execute
+- `runtime.workdir`: default working directory in the sandbox
+
+## `Agent` with `sandbox`
+
+This example reuses `repoSandbox` from the previous snippet.
+
+```ts
+import { anthropic } from '@keystroke/integration-ai';
+import { Agent } from '@keystrokehq/core';
+
+export const codingAgent = new Agent({
+  id: 'coding-agent',
+  name: 'Coding Agent',
+  systemPrompt: 'Inspect the repo, make the requested change, and explain the result.',
+  model: 'anthropic/claude-sonnet-4-20250514',
+  credentialSets: [anthropic],
+  sandbox: repoSandbox,
+});
+```
+
+Use this shape when the default persistent sandbox is not enough and the agent should work inside a prepared project or coding environment.
+
+## `McpServer` with `stdio` transport
+
+```ts
+import { McpServer } from '@keystrokehq/core';
+
+export const localDocsServer = new McpServer({
+  id: 'local-docs',
+  name: 'Local Docs',
+  transport: {
+    type: 'stdio',
+    command: 'node',
+    args: ['./scripts/mcp-docs-server.js'],
+    env: {
+      DOCS_ROOT: '/workspace/docs',
+    },
+  },
+});
+```
+
+Use `stdio` transport when the MCP server is started as a local process.
+
+## `McpServer` with `http` transport
+
+```ts
+const remoteHttpServer = new McpServer({
+  id: 'remote-http',
+  transport: {
+    type: 'http',
+    url: 'https://mcp.example.com',
+    headers: {
+      Authorization: 'Bearer static-token',
+    },
+  },
+});
+```
+
+Use `http` transport when the MCP server is available at a normal HTTP endpoint.
+
+## `McpServer` with `sse` transport
+
+```ts
+const remoteSseServer = new McpServer({
+  id: 'remote-sse',
+  transport: {
+    type: 'sse',
+    url: 'https://mcp.example.com/sse',
+  },
+});
+```
+
+Use `sse` transport when the MCP server communicates over server-sent events.
+
+## `McpServer` with credentials
+
+```ts
+import { CredentialSet, McpServer } from '@keystrokehq/core';
+import { z } from 'zod';
+
+const apiCredentials = new CredentialSet({
+  id: 'mcpApi',
+  auth: z.object({
+    token: z.string(),
+  }),
+});
+
+export const securedServer = new McpServer({
+  id: 'secured-server',
+  transport: {
+    type: 'http',
+    url: 'https://mcp.example.com',
+  },
+  credentialSets: [apiCredentials],
+  credentialMapper: (credentials) => ({
+    headers: {
+      Authorization: `Bearer ${credentials.mcpApi.token}`,
+    },
+  }),
+});
+```
+
+`credentialMapper` is where typed Keystroke credentials are converted into the transport configuration the MCP server needs, such as headers or env vars.
+
+## `Agent` with `mcpServers`
+
+This example reuses `localDocsServer` and `securedServer` from the previous snippets.
+
+```ts
+import { anthropic } from '@keystroke/integration-ai';
+import { Agent } from '@keystrokehq/core';
+
+export const docsAgent = new Agent({
+  id: 'docs-agent',
+  name: 'Docs Agent',
+  systemPrompt: 'Use the MCP server before answering documentation questions.',
+  model: 'anthropic/claude-sonnet-4-20250514',
+  credentialSets: [anthropic],
+  mcpServers: [localDocsServer, securedServer],
+  maxSteps: 8,
+});
+```
+
+Use `mcpServers` when the agent should use MCP-exposed capabilities instead of only normal tools.
+
+## `Sandbox.configure(...)`
+
+```ts
+const ciSandbox = repoSandbox.configure({
+  name: 'Repo Sandbox CI',
+  setupCommands: ['pnpm install', 'pnpm build'],
+});
+```
+
+Use `configure(...)` to create a new sandbox instance with adjusted metadata or runtime setup.
+
+## `McpServer.configure(...)`
+
+```ts
+const renamedServer = securedServer.configure({
+  name: 'Secured Docs Server',
+  description: 'Authenticated MCP docs endpoint.',
+});
+```
+
+Use `configure(...)` to create a new MCP server instance with adjusted metadata.
+
+## `describe()` and `toManifest()`
+
+```ts
+const sandboxSummary = repoSandbox.describe();
+const sandboxManifest = repoSandbox.toManifest();
+const serverSummary = securedServer.describe();
+const serverManifest = securedServer.toManifest();
+```
+
+## Gotchas
+
+- Do not add both normal tools and MCP servers unless the task genuinely needs both.
+- Put sandbox details on the sandbox or agent config, not inside the system prompt.
+- Keep workflow orchestration outside the agent.

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

@@ -0,0 +1,182 @@
+# Agent Feature Map
+
+Use only the public imports a user repo can rely on:
+
+```ts
+import { anthropic } from '@keystroke/integration-ai';
+import {
+  Agent,
+  CredentialSet,
+  McpServer,
+  MessagingGateway,
+  Operation,
+  Sandbox,
+  Tool,
+} from '@keystrokehq/core';
+```
+
+`Operation`, `Step`, and `Tool` are aliases for the same class. In this agent skill, prefer `Tool` for custom examples and explanations, but `Operation` is equally valid for shared or integration-oriented code.
+
+## `Agent` fields
+
+- `id`
+- `name`
+- `description`
+- `systemPrompt`
+- `model`
+- `sandbox`
+- `skills`
+- `tools`
+- `credentialSets`
+- `mcpServers`
+- `maxSteps`
+- `hooks`
+
+### What they are used for
+
+- `id`: stable agent identifier
+- `name`: human-readable name
+- `description`: short explanation of the agent's job
+- `systemPrompt`: operating instructions for the model
+- `model`: model selector
+- `sandbox`: attach a sandbox runtime
+- `skills`: make skills available to the agent runtime
+- `tools`: attach operations
+- `credentialSets`: credentials the agent itself needs
+- `mcpServers`: attach MCP servers
+- `maxSteps`: limit tool/model turns
+- `hooks`: observe or gate tool and step execution
+
+## Raw `Agent` fields
+
+- `id`
+- `name`
+- `description`
+- `systemPrompt`
+- `model`
+- `input`
+- `output`
+- `credentialSets`
+- `tools`
+- `mcpServers`
+- `sandbox`
+- `skills`
+- `maxSteps`
+- `hooks`
+- `run`
+- `stream`
+
+## `Agent` instance properties and methods
+
+- `credentialSets`
+- `allCredentialSets`
+- `tools`
+- `mcpServers`
+- `sandbox`
+- `messaging`
+- `skills`
+- `maxSteps`
+- `hooks`
+- `runtimeKind`
+- `workflowSafeReference`
+- `run(input, options?)`
+- `stream(input, options?)`
+- `configure(overrides)`
+- `describe()`
+- `toManifest()`
+
+### What they are used for
+
+- `credentialSets`: credentials attached directly to the agent
+- `allCredentialSets`: combined credential surface from the agent, its tools, its MCP servers, and its messaging gateways
+- `messaging`: `MessagingGateway[]` conversational entry configuration
+- `runtimeKind`: whether the agent is declarative-only or has `run` / `stream` implementations
+- `workflowSafeReference`: stable reference shape used by other primitives such as `Task`
+- `run(...)`: execute the agent and return an `AgentResult`
+- `stream(...)`: stream `AgentEvent` values during execution
+- `configure(...)`: create a new agent instance with changed metadata or hooks
+- `describe()`: return a human-readable summary string
+- `toManifest()`: return the agent manifest description
+
+## `Operation` / `Tool` fields
+
+- `name`
+- `description`
+- `input`
+- `output`
+- `needsApproval`
+- `credentialSets`
+- `workflowGlobals`
+- `run`
+
+## `Operation` / `Tool` instance methods
+
+- `run(input, ctx?)`
+- `withTimeout(duration)`
+- `retry(policy)`
+- `configure(overrides)`
+- `mapInput(schema, fn)`
+- `mapOutput(schema, fn)`
+- `describe()`
+- `toManifest()`
+
+## `MessagingGateway` fields
+
+- `id`
+- `name`
+- `description`
+- `provider`
+- `mode`
+- `credentialSet`
+- `credentialScope`
+- `appRef`
+
+## `MessagingGateway` instance methods
+
+- `describe()`
+- `toManifest()`
+
+## Messaging notes
+
+- `MessagingGateway` belongs on `Agent.messaging`
+- gateways are conversation entrypoints, not workflow triggers
+- default to `mode: 'platform'` (Keystroke-owned app the user installs) unless the user explicitly wants a custom app
+- use `mode: 'custom'` with `appRef` only when the user creates or manages their own app
+- use the agent skill plus `messaging-gateways.md` when the user asks for Slack, GitHub, or Linear conversational agent entry
+
+## `Sandbox` fields
+
+- `id`
+- `name`
+- `description`
+- `runtime`
+- `fileSources`
+- `setupCommands`
+
+## `Sandbox` instance methods
+
+- `configure(overrides)`
+- `describe()`
+- `toManifest()`
+
+## `McpServer` fields
+
+- `id`
+- `name`
+- `description`
+- `transport`
+- `credentialSets`
+- `credentialMapper`
+
+## `McpServer` instance methods
+
+- `configure(overrides)`
+- `describe()`
+- `toManifest()`
+
+## Where to read next
+
+- `patterns.md` for agent, raw `Agent`, and `Tool` / `Operation` examples
+- `messaging-gateways.md` for gateway-specific examples
+- `sandbox-and-mcp.md` for `Sandbox`, `McpServer`, bash/runtime setup, and hook examples
+- `testing.md` for agent and tool test patterns

package/keystroke-agent-authoring/references/testing.md

@@ -0,0 +1,85 @@
+# Agent Testing Patterns
+
+Read this file when the user asks how to test Keystroke agents or tools.
+
+## What to test
+
+Default testing targets:
+- tool input and output behavior
+- credential access in tools
+- agent construction and configuration
+- gateway wiring when an agent uses `messaging`
+- sandbox or MCP setup when the authored config depends on them
+
+## Vitest setup
+
+`keystrokeTestPlugin()` adds the core test setup file to Vitest, which is required for credential resolution and sandbox mocks.
+
+```ts
+import { defineConfig } from 'vitest/config';
+import { keystrokeTestPlugin } from '@keystrokehq/core/vitest';
+
+export default defineConfig({
+  plugins: [keystrokeTestPlugin()],
+});
+```
+
+## Test tools directly
+
+For testing tools in isolation, use the specialized `runTool` helper from `@keystrokehq/core/vitest` which automatically creates the appropriate tool context.
+
+```ts
+import { runTool } from '@keystrokehq/core/vitest';
+
+const result = await runTool(
+  lookupCustomerTool,
+  { email: 'user@example.com' },
+  {
+    credentials: {
+      crmApi: {
+        apiKey: 'secret',
+      },
+    },
+  }
+);
+```
+
+## Test agent construction
+
+For many agent changes, the high-value test is verifying the configured agent surface:
+- `id`
+- `model`
+- `tools`
+- `credentialSets`
+- `allCredentialSets`
+- `messaging`
+- `sandbox`
+- `mcpServers`
+
+This is especially useful when the task is about wiring rather than full runtime execution.
+
+## Test prompt shaping separately
+
+If the agent depends on complex prompt assembly, test the prompt-building helpers directly instead of overfitting a full model-runtime test.
+
+## Test sandbox or MCP config
+
+When the change is about runtime configuration, assert the authored configuration rather than trying to reproduce the full hosted runtime:
+- sandbox `runtime`
+- sandbox `setupCommands`
+- MCP transport shape
+- MCP credential mapper behavior
+
+## Gateway tests
+
+When an agent uses `messaging`, test:
+- the gateway config fields
+- the chosen `provider`
+- the chosen `mode`
+- credential scope or `appRef` when relevant
+
+## Gotchas
+
+- Do not invent an unrelated custom harness if direct primitive tests are enough.
+- Test custom tools directly before reaching for a full agent runtime test.
+- Keep workflow-orchestration tests in the workflow skill.

package/keystroke-cli-workspace/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: keystroke-cli-workspace
+description: Use the Keystroke CLI to initialize projects, inspect commands, build workflows, deploy workflows or tasks, manage credentials, connect integrations, and debug authoring work. Use when the user needs Keystroke CLI usage or project lifecycle guidance.
+---
+
+# Keystroke CLI Workspace
+
+Use this skill when an agent needs to use the Keystroke CLI while authoring or operating a Keystroke project.
+
+This skill is operational and procedural:
+- use it for project setup, build, validate, deploy, connect, credentials, logs, and skills sync
+- use the workflow, agent, task, and trigger skills for the authored code itself
+
+## First rule: inspect `--help`
+
+Before running a Keystroke CLI command, inspect the live command surface first.
+
+Teach this as a hard rule:
+- run `keystroke --help` before exploring the CLI
+- run `keystroke <command> --help` before using a specific command
+- run `keystroke <command> <subcommand> --help` before using a nested command
+- treat `--help` as the source of truth for supported flags and subcommands
+
+Common examples:
+
+```bash
+keystroke --help
+keystroke workflows --help
+keystroke deploy --help
+keystroke credentials upload --help
+keystroke connect --help
+```
+
+## What the CLI is for
+
+Teach the CLI as the operational companion to authored code:
+- initialize a project
+- inspect and validate workflows
+- deploy workflows, agents, and tasks
+- connect official integrations
+- inspect and upload credentials
+- sync Keystroke-authored skills into local IDE skill directories
+
+The CLI does not replace primitive authoring:
+- workflow code still lives in workflow and step files
+- agent code still lives in agent and tool files
+- trigger, task, and messaging-gateway code still live in authored project files
+
+## Command groups to teach
+
+Teach these groups first:
+- `auth`
+- `api-keys`
+- `org`
+- `init`
+- `projects`
+- `connect`
+- `credentials`
+- `workflows`
+- `deploy`
+- `sync`
+- `skills`
+- `logs`
+
+Important distinctions:
+- `keystroke deploy` is the unified project deployment flow for workflows, agents, and tasks
+- `keystroke deploy --target <file>` deploys a focused workflow, agent, or task source file
+- `keystroke logs` is CLI diagnostics
+- `keystroke workflows logs` is workflow run inspection
+
+## Default CLI process
+
+1. Inspect the command with `--help`.
+2. Initialize the project if needed.
+3. Build or validate authored workflows.
+4. Check credentials or connect integrations when required.
+5. Deploy the project or focused target with the right command.
+6. Use logs and inspect commands for debugging.
+
+## CLI rules
+
+- Prefer exact commands shown by `--help` over stale prose or memory.
+- Use `--json` when machine-readable output helps the current task.
+- Use `keystroke connect <integration>` for official integration connection flows.
+- Use `keystroke credentials ...` for credential inspection and upload flows.
+- Use `keystroke skills sync` to copy `@keystrokehq/skills` into local editor skill directories.
+
+## References
+
+Read these files as needed:
+- `references/command-map.md` for the command tree
+- `references/project-lifecycle.md` for common setup, build, deploy, and debug flows
+- `references/credentials-and-connect.md` for connection and credential workflows

package/keystroke-cli-workspace/evals/evals.json

@@ -0,0 +1,23 @@
+{
+  "skill_name": "keystroke-cli-workspace",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I need to deploy a Keystroke task. What command should I use, and how should I inspect the available flags before running it?",
+      "expected_output": "Uses the CLI skill, chooses `keystroke deploy --target <task.task.ts>`, and tells the agent to inspect `keystroke deploy --help` first.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "How do I set up a new Keystroke project and make the Keystroke-authored skills available in Cursor?",
+      "expected_output": "Uses `keystroke init`, explains `keystroke skills sync`, and tells the agent to inspect command help first.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "I need to figure out which CLI options exist for uploading credentials. What should I do before running the upload command?",
+      "expected_output": "Explicitly uses `keystroke credentials upload --help` before describing the upload flow.",
+      "files": []
+    }
+  ]
+}

package/keystroke-cli-workspace/references/command-map.md

@@ -0,0 +1,50 @@
+# Keystroke CLI Command Map
+
+Use this file when the user needs a quick map of the Keystroke CLI surface.
+
+## Root rule
+
+Always inspect the live command surface first:
+
+```bash
+keystroke --help
+```
+
+Then inspect the exact command:
+
+```bash
+keystroke workflows --help
+keystroke deploy --help
+```
+
+## Global flags
+
+Global flags are defined at the root program and include:
+- `--api-key`
+- `--server-url`
+- `--org`
+- `--debug`
+
+Root help shows these directly. Subcommand help focuses on the local flags for that command.
+
+## Command groups
+
+- `auth`: sign in, clear credentials, inspect auth status
+- `api-keys`: list and delete API keys
+- `org`: list, inspect, and switch organization context
+- `init`: initialize a Keystroke project
+- `projects`: inspect cached project state
+- `connect`: connect official integrations through OAuth
+- `credentials`: list requirements and upload credentials
+- `workflows`: build, validate, inspect, diff, env, logs, paused, try-deploy
+- `test`: test workflows and agent-callable tools
+- `deploy`: deploy workflows, agents, tasks, or focused targets via `--target <file>`
+- `sync`: local sync operations
+- `skills`: Keystroke skills sync flows
+- `logs`: CLI diagnostic logs
+
+## Command notes
+
+- `keystroke workflows logs` is different from `keystroke logs`
+- `keystroke deploy --target <file>` is the focused deploy path
+- many commands support `--json`