@keystrokehq/skills 0.0.3 → 0.0.4

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# @keystrokehq/skills
+
+## 0.0.4
+
+### Patch Changes
+
+- bb9fea0: Fix: Removing callbacks from triggers (except polling)
+
+## 0.0.3
+
+### Patch Changes
+
+- c4870ce: Update public package references and authoring guidance for the provider-name integration packages.
+
+## 0.0.2
+
+### Patch Changes
+
+- 761d44e: Add `keystroke workflows run` for manually invoking workflows from a project's current deployment, including input and workflow globals parsing plus wait/follow support.
+
+  Update Keystroke CLI and workflow authoring skills with guidance for deployed workflow manual runs.
+
+## 0.0.1
+
+### Patch Changes
+
+- 2ff9004: Publish Keystroke skills as an npm package and let the CLI use its installed skills package as a fallback when syncing skills into projects.

package/README.md

@@ -19,34 +19,42 @@ The packaged skills are:
 
 ## Editing
 
-Edit the source files in `packages/skills/`.
+Edit shipped skill content in `packages/skills/src/`.
 
-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.
+Do not treat local editor skill directories as the source of truth for these packaged skills. Edit the canonical files in `packages/skills/src/` first, then use the Keystroke CLI skill sync flow when project-installed skill copies need to be refreshed.
+
+Evaluation prompts and notes live in `packages/skills/evals/`. They are repo-only authoring assets and are not published to npm or copied into user projects.
 
 ## Structure
 
-Each skill follows this structure:
+The publishable package content follows this structure:
 
 ```text
-<skill-name>/
-├── SKILL.md
-├── references/
-│   ├── source-map.md
-│   └── ...
-└── evals/
-    └── evals.json
+src/
+├── AGENTS.md
+├── <skill-name>/
+│   ├── SKILL.md
+│   └── references/
+│       ├── source-map.md
+│       └── ...
+└── ...
 ```
 
+- `src/AGENTS.md` is the Keystroke project context written or appended to project-root `AGENTS.md` by `keystroke init`.
 - `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/`.
+- `evals/<skill-name>/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:
+These packaged skills are installed into project agent skill directories through the Keystroke CLI:
 
-- packaged skills are authored here
-- `keystroke skills sync` copies them into `.cursor/skills` and `.claude/skills`
+- packaged skills are authored in `src/`
+- `keystroke init` always copies them into the canonical project path `.agents/skills`
+- `keystroke init --agent <agent> --method symlink` provisions selected agent-specific paths by linking back to `.agents/skills`
+- `keystroke init --agent <agent> --method copy` provisions selected agent-specific paths with independent copies
+- `keystroke skills sync` refreshes an existing project using the same `--agent` and `--method` flags
+- eval assets stay in `evals/` and are excluded from published packages and synced project skills
 
 If the discovery story changes later, update this package and the sync flow together. Until then, edit the packaged skills here first.
 
@@ -57,7 +65,7 @@ Because these are repo-authored local skills rather than externally installed sk
 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`
+2. Add realistic eval prompts to `evals/<skill-name>/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keystrokehq/skills",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "private": false,
   "type": "module",
   "publishConfig": {
@@ -9,15 +9,8 @@
   },
   "files": [
     "README.md",
-    "AGENTS-blurb.md",
-    "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"
+    "CHANGELOG.md",
+    "src"
   ],
   "scripts": {
     "build": "node -e \"process.exit(0)\"",

package/{keystroke-agent-authoring → src/keystroke-agent-authoring}/references/testing.md

@@ -17,7 +17,7 @@ Default testing targets:
 
 ```ts
 import { defineConfig } from 'vitest/config';
-import { keystrokeTestPlugin } from '@keystrokehq/testing/vitest';
+import { keystrokeTestPlugin } from '@keystrokehq/testing';
 
 export default defineConfig({
   plugins: [keystrokeTestPlugin()],

package/{keystroke-cli-workspace → src/keystroke-cli-workspace}/SKILL.md

@@ -87,7 +87,7 @@ Important distinctions:
 - 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.
-- Use `keystroke workflows run <authoredWorkflowId>` for deployed-workflow manual invocation; use `try-deploy` only when testing a temporary build artifact.
+- Use `keystroke workflows run <authoredWorkflowId>` for deployed-workflow manual invocation; use `keystroke workflows test <workflow>` when testing a temporary build artifact.
 
 ## References
 

package/{keystroke-cli-workspace → src/keystroke-cli-workspace}/references/command-map.md

@@ -36,8 +36,8 @@ Root help shows these directly. Subcommand help focuses on the local flags for t
 - `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, run, try-deploy
-- `test`: test workflows and agent-callable tools
+- `workflows`: build, validate, inspect, diff, env, logs, paused, test, run
+- `test`: test agent-callable tools
 - `deploy`: deploy workflows, agents, tasks, or focused targets via `--target <file>`
 - `sync`: local sync operations
 - `skills`: Keystroke skills sync flows
@@ -47,7 +47,7 @@ Root help shows these directly. Subcommand help focuses on the local flags for t
 
 - `keystroke workflows logs` is different from `keystroke logs`
 - `keystroke workflows run <authoredWorkflowId>` executes the current deployed workflow snapshot via the workflow execute API; it does not build or upload local code
-- `keystroke workflows try-deploy <workflow>` builds local code, uploads or references a test bundle, and runs that temporary artifact
+- `keystroke workflows test <workflow>` builds local code, uploads or references a test bundle, and runs that temporary artifact
 - `keystroke deploy --target <file>` is the focused deploy path
 - many commands support `--json`
 

package/{keystroke-cli-workspace → src/keystroke-cli-workspace}/references/project-lifecycle.md

@@ -77,7 +77,7 @@ keystroke workflows run wf_onboard_user --input '{"email":"user@example.com"}'
 
 Notes:
 - `workflows run` executes the current deployed snapshot through `client.workflows.execute()` / `POST /api/v1/workflows/execute`
-- it does not build or upload local source; use `workflows try-deploy` for temporary local artifact testing
+- it does not build or upload local source; use `workflows test` for temporary local artifact testing
 - pass `--project-id <uuid>` outside a project checkout, otherwise the CLI resolves `projectId` from `keystroke.config.ts`
 - pass `--workflow-globals` or `--workflow-globals-file` when the deployed manifest declares required workflow globals without defaults
 - use `--wait` to poll to a terminal status and `--follow` to poll logs/events while waiting

package/{keystroke-trigger-authoring → src/keystroke-trigger-authoring}/references/patterns.md

@@ -202,12 +202,16 @@ triggers: [
 
 Call the trigger as a function with `{ transform }` when the trigger payload and workflow input are different shapes. This returns a `BoundTrigger`.
 
-## Bound trigger with additional `filter`
+## Narrow a trigger for per-workflow filtering
 
 ```ts
+const largePayments = paymentWebhook.narrow({
+  name: 'large-payments',
+  filter: z.object({ amount: z.number().gt(100) }),
+});
+
 triggers: [
-  paymentWebhook({
-    filter: (payload) => payload.amount > 100,
+  largePayments({
     transform: (payload) => ({
       eventId: payload.id,
       amount: payload.amount,
@@ -216,7 +220,7 @@ triggers: [
 ]
 ```
 
-An additional filter on the binding composes with the trigger's own filter.
+Filtering and idempotency live on the trigger or its `.narrow()` derivatives — never on the attachment. Bindings accept only `transform`. Use `.narrow()` to produce a filtered child trigger and attach that to the workflow.
 
 ## Task trigger note
 

package/{keystroke-trigger-authoring → src/keystroke-trigger-authoring}/references/source-map.md

@@ -101,14 +101,13 @@ All factory-created triggers are callable. Calling one returns a `BoundTrigger`:
 
 - `trigger()` — bare binding (no transform)
 - `trigger({ transform })` — bound with payload-to-input mapping
-- `trigger({ filter })` — bound with additional filter
-- `trigger({ transform, filter })` — bound with both
+
+Bindings carry only `transform`. To filter events for a specific workflow, derive a child with `trigger.narrow({ name, filter })` and attach that — `.narrow()` is the only authoring path for per-target filtering. Binding-level `filter` and `idempotencyKey` are intentionally not part of the API.
 
 ## `BoundTrigger`
 
 - `.isBoundTrigger` — always `true`
 - `.trigger` — reference to the underlying trigger instance
-- `.filter?` — composed filter (trigger's filter + binding filter)
 - `.transform?` — payload-to-workflow-input mapping function
 
 ## Workflow `triggers` array

package/{keystroke-trigger-authoring → src/keystroke-trigger-authoring}/references/testing.md

@@ -10,7 +10,7 @@ Assume `paymentWebhook`, `orderPolling`, and `paymentWorkflow` are the public tr
 
 ```ts
 import { defineConfig } from 'vitest/config';
-import { keystrokeTestPlugin } from '@keystrokehq/testing/vitest';
+import { keystrokeTestPlugin } from '@keystrokehq/testing';
 
 export default defineConfig({
   plugins: [keystrokeTestPlugin()],

package/{keystroke-workflow-authoring → src/keystroke-workflow-authoring}/SKILL.md

@@ -123,7 +123,7 @@ Teach these rules:
    - waits and hooks
 5. Put operational work in steps, shared operations, or agents.
 6. Keep each exported primitive in its own typed file.
-7. Finish with tests using `@keystrokehq/testing/vitest`.
+7. Finish with tests using `@keystrokehq/testing`.
 
 ## Workflow rules
 
@@ -202,7 +202,7 @@ keystroke workflows run <authoredWorkflowId> --input '{}' --wait
 keystroke workflows run <authoredWorkflowId> --input '{}' --follow
 ```
 
-`workflows run` executes the current deployed snapshot. It is different from `workflows try-deploy`, which builds local code and runs a temporary artifact.
+`workflows run` executes the current deployed snapshot. It is different from `workflows test`, which builds local code and runs a temporary artifact.
 
 To explicitly start a workflow via API:
 - **Endpoint**: `POST /api/v1/workflows/execute`

package/{keystroke-workflow-authoring → src/keystroke-workflow-authoring}/references/runtime-helpers.md

@@ -239,7 +239,7 @@ Use these when operation behavior depends on retry state or when you want the st
 
 ## Public testing helpers
 
-Import these from `@keystrokehq/testing/vitest`:
+Import these from `@keystrokehq/testing`:
 
 - `keystrokeTestPlugin`
 - `createTestRuntime`
@@ -256,7 +256,7 @@ Import these from `@keystrokehq/testing/vitest`:
 Example:
 
 ```ts
-import { createMockHook } from '@keystrokehq/testing/vitest';
+import { createMockHook } from '@keystrokehq/testing';
 
 const hook = createMockHook();
 await hook;

package/{keystroke-workflow-authoring → src/keystroke-workflow-authoring}/references/source-map.md

@@ -9,7 +9,7 @@ import {
   createTestRuntime,
   createTestStepContext,
   keystrokeTestPlugin,
-} from '@keystrokehq/testing/vitest';
+} from '@keystrokehq/testing';
 ```
 
 `Operation`, `Step`, and `Tool` are aliases for the same class. In this workflow skill, prefer `Step` for examples and explanations, but `Operation` is equally valid for shared or integration-oriented code.

package/{keystroke-workflow-authoring → src/keystroke-workflow-authoring}/references/testing.md

@@ -10,7 +10,7 @@ Assume `helloWorkflow`, `accountSyncWorkflow`, `loadCustomer`, `paymentWebhook`,
 
 ```ts
 import { defineConfig } from 'vitest/config';
-import { keystrokeTestPlugin } from '@keystrokehq/testing/vitest';
+import { keystrokeTestPlugin } from '@keystrokehq/testing';
 
 export default defineConfig({
   plugins: [keystrokeTestPlugin()],
@@ -40,7 +40,7 @@ Use it when a workflow test needs more than plain input data.
 
 ```ts
 import { createTestRuntime } from '@keystrokehq/testing';
-import { createMockHook } from '@keystrokehq/testing/vitest';
+import { createMockHook } from '@keystrokehq/testing';
 
 const runtime = createTestRuntime({
   workflowGlobals: {

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

@@ -1,29 +0,0 @@
-{
-  "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": []
-    }
-  ]
-}

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

@@ -1,23 +0,0 @@
-{
-  "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-credential-binding/evals/evals.json

@@ -1,29 +0,0 @@
-{
-  "skill_name": "keystroke-credential-binding",
-  "evals": [
-    {
-      "id": 1,
-      "prompt": "I need to add a credential set for a new API integration in Keystroke. Can you show me how to define the CredentialSet and how a step would read it safely?",
-      "expected_output": "Explains CredentialSet authoring, typed schemas, and step context access through ctx.credentials.",
-      "files": []
-    },
-    {
-      "id": 2,
-      "prompt": "Before I deploy these workflows, how do I figure out which credentials are required and upload them from env vars with the Keystroke CLI?",
-      "expected_output": "Uses the tested credential requirements and upload flows, including the KEYSTROKE_<KEY> convention.",
-      "files": []
-    },
-    {
-      "id": 3,
-      "prompt": "Does the same credential model work for steps, tools, agents, and triggers, or are there important differences I need to know?",
-      "expected_output": "Explains the shared CredentialSet model and the differences in where credentials are attached and consumed across primitives.",
-      "files": []
-    },
-    {
-      "id": 4,
-      "prompt": "How do I upload official GitHub credentials with the current Keystroke CLI? Please use the real command surface, not an outdated one.",
-      "expected_output": "Uses the current credentials upload syntax, including --integration and the KEYSTROKE_<KEY> convention, and avoids stale flags such as --from-workflows or --no-verify.",
-      "files": []
-    }
-  ]
-}

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

@@ -1,23 +0,0 @@
-{
-  "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-task-authoring/evals/evals.json

@@ -1,23 +0,0 @@
-{
-  "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-trigger-authoring/evals/evals.json

@@ -1,29 +0,0 @@
-{
-  "skill_name": "keystroke-trigger-authoring",
-  "evals": [
-    {
-      "id": 1,
-      "prompt": "How do I create a Keystroke webhook trigger for a Stripe event and map the incoming payload into my workflow input?",
-      "expected_output": "Explains webhookTrigger() factory setup, required and optional fields, and the bound trigger transform pattern via Workflow({ triggers: [trigger({ transform })] }).",
-      "files": []
-    },
-    {
-      "id": 2,
-      "prompt": "I need a polling trigger that checks an external API every 15 minutes and only launches the workflow for new items. What should that look like?",
-      "expected_output": "Explains pollingTrigger() factory setup, schedule, poll/response, optional filter and idempotency behavior, and listing the trigger in Workflow({ triggers: [...] }) with optional transform binding.",
-      "files": []
-    },
-    {
-      "id": 3,
-      "prompt": "What is the right way to test a Keystroke trigger? I want to validate webhook verify/filter logic and the input transform into the workflow.",
-      "expected_output": "Points to trigger-specific callback tests (verify, filter, payload.parse) plus bound trigger transform testing via bound.transform?.(payload).",
-      "files": []
-    },
-    {
-      "id": 4,
-      "prompt": "I want a cron-driven agent job. Do I attach a trigger to the agent, attach it to a task, or something else?",
-      "expected_output": "Explains that workflow triggers are listed in Workflow({ triggers: [...] }), task triggers are listed inline on Task.triggers, and messaging gateways are not triggers.",
-      "files": []
-    }
-  ]
-}

package/keystroke-workflow-as-tool-debugging/evals/evals.json

@@ -1,23 +0,0 @@
-{
-  "skill_name": "keystroke-workflow-as-tool-debugging",
-  "evals": [
-    {
-      "id": 1,
-      "prompt": "A workflow tool with ctx.wait returned pending: true and the agent tried to call it again. What should I inspect and what behavior is expected?",
-      "expected_output": "Explains yield receipt behavior, turn ending, idempotency, pending yield state, child workflow run, and agent_continue resume path.",
-      "files": []
-    },
-    {
-      "id": 2,
-      "prompt": "My midSessionSnapshot workflow tool is suspended_snapshotted. When the child workflow completes, which worker should resume it?",
-      "expected_output": "States that agent_resume handles current snapshots through Path B conversation-log replay and does not claim native Pi process restore.",
-      "files": []
-    },
-    {
-      "id": 3,
-      "prompt": "A workflow tool returned a ref and the model wants to query it with a reducer. What should I do?",
-      "expected_output": "Recommends describe_ref/read_ref/slice_ref with bounded ranges and states reducers/DuckDB are deferred and unsupported.",
-      "files": []
-    }
-  ]
-}

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

@@ -1,29 +0,0 @@
-{
-  "skill_name": "keystroke-workflow-authoring",
-  "evals": [
-    {
-      "id": 1,
-      "prompt": "I'm building a Keystroke workflow that checks a few upstream APIs, waits 10 minutes between retries, and then posts the result to Slack. Can you show me how to structure the workflow and what should be steps versus workflow orchestration?",
-      "expected_output": "Explains workflow planning, step boundaries, replay-safe orchestration, the durable wait path, and where Slack or other external work belongs.",
-      "files": []
-    },
-    {
-      "id": 2,
-      "prompt": "I have a workflow that uses Math.random() and Date.now() inside Workflow.run to make request ids. Why is that a problem in Keystroke, and how should I rewrite it?",
-      "expected_output": "Explains workflow replay safety, why nondeterministic logic should not live in the workflow body, and how to move it into a step or agent boundary.",
-      "files": []
-    },
-    {
-      "id": 3,
-      "prompt": "How do I test a Keystroke workflow that uses workflowGlobals and a webhook trigger? I want the recommended testing path, not a random custom harness.",
-      "expected_output": "Uses core Vitest helpers, covers workflowGlobals, and points to bound trigger transform testing via bound.transform?.(payload, ctx).",
-      "files": []
-    },
-    {
-      "id": 4,
-      "prompt": "Can my Keystroke workflow run bash to call a Python script, or should I structure this differently?",
-      "expected_output": "Explains that workflows are authored as TypeScript orchestration and do not run bash as part of the workflow model, then routes shell-heavy work to an agent sandbox.",
-      "files": []
-    }
-  ]
-}