Workflow Skills for npx skills#842
Merged
Merged
Conversation
Contributor
🦋 Changeset detectedLatest commit: 6006ba7 The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Contributor
📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express workflow with 1 step💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express | Nitro Promise.all with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro Promise.race with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Stream Benchmarks (includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
|
Contributor
🧪 E2E Test Results❌ Some tests failed Summary
❌ Failed Tests🌍 Community Worlds (161 failed)mongodb (40 failed):
redis (40 failed):
starter (41 failed):
turso (40 failed):
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
❌ 🌍 Community Worlds
✅ 📋 Other
|
johnlindquist
force-pushed
the
add-claude-code-skills-and-commands
branch
from
2a611a0 to
5aa4a0d
Compare
johnlindquist
changed the title
pranaygp
reviewed
Jan 23, 2026
| @@ -0,0 +1,434 @@ | |||
| # Complete API Reference | |||
Contributor
There was a problem hiding this comment.
this one particularly I'm worried about shipping since it will go outdated very fast as they're generated in the docs using tsdoc. were about to make big changes just in the next couple of days/weeks to the API and we constantly will
pranaygp
reviewed
Jan 23, 2026
Comment on lines
+277
to
+283
| **Verify connection:** | ||
| ```bash | ||
| # Check your app responds to workflow endpoints | ||
| curl -s http://localhost:3000/.well-known/workflow/v1/flow \ | ||
| -X POST -H "Content-Type: application/json" | ||
| # Should return: {"error": "Missing required headers"} (not 404) | ||
| ``` |
Contributor
There was a problem hiding this comment.
We now have a health command that's better for checking. npx health
cc @TooTallNate
pranaygp
reviewed
Jan 23, 2026
| writer.releaseLock(); | ||
| } | ||
| ``` | ||
|
|
Contributor
There was a problem hiding this comment.
for essential APIs we can also show usage of getRun with an example of getting status, seeing the returnValue, or cancelling a run (all in the docs)
pranaygp
reviewed
Jan 23, 2026
Comment on lines
+247
to
+251
| # Terminal 2: Open dashboard (connects to port 3000) | ||
| npx workflow web | ||
|
|
||
| # If app runs on different port: | ||
| npx workflow web --app-url http://localhost:3001 |
Contributor
There was a problem hiding this comment.
btw, the CLI can also be used to inspect all the runs/steps etc. without using the browser. npx workflow inspect runs, npx workflow inspect run wrun_sfnesf, npx workflow inspect --backend vercel etc.
this is specifically meant for agents to consume.
npx workflow web is mostly for humans, and the cli npx workflow inspect is meant for agents
can we please include that somewhere so it knows :)
pranaygp
reviewed
Jan 23, 2026
Contributor
pranaygp
left a comment
pranaygp
left a comment
There was a problem hiding this comment.
Left some comments I'd love to include/address before we ship the first version - but I'm generally happy to just put it and keep iterating once it's out there!
Add custom slash commands for Claude Code: - /pr command for creating PRs following repo conventions Add workflow skill with comprehensive documentation: - Main SKILL.md with core concepts and quick reference - Reference docs for frameworks, AI agents, patterns, errors, and API Signed-off-by: johnlindquist <johnlindquist@gmail.com> Signed-off-by: John Lindquist <johnlindquist@gmail.com>
Add documentation for custom class serialization using @workflow/serde symbols (WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE) and clarify what can and cannot be serialized based on recent PR #762. Signed-off-by: John Lindquist <johnlindquist@gmail.com>
- Update sleep() example date from 2025 to 2027 (future date) - Fix getWorkflowMetadata() to use correct properties: workflowRunId, workflowStartedAt, url (not runId, workflowName) - Fix getStepMetadata() to use correct property: attempt (not attemptNumber) Signed-off-by: John Lindquist <johnlindquist@gmail.com>
Reorganize skill files to support multiple skills under ./skill/<name>/ Signed-off-by: John Lindquist <johnlindquist@gmail.com>
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
- Update SKILL.md to direct agents to search node_modules/workflow/docs/ - Remove manually-maintained reference docs (ai-agents, api-reference, frameworks, patterns) - Keep common-errors.md for practical troubleshooting - Add prepack/postpack hooks to bundle docs in npm packages: - workflow: All docs from docs/content/docs/ - @workflow/ai: AI-specific docs - @workflow/core: foundations, how-it-works, api-reference - @workflow/next: Next.js setup docs Signed-off-by: John Lindquist <johnlindquist@gmail.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Signed-off-by: John Lindquist <johnlindquist@gmail.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Signed-off-by: John Lindquist <johnlindquist@gmail.com>
Use del-cli for postpack cleanup to match the AI SDK's cross-platform approach. This ensures consistent tooling across both projects. - Add del-cli ^5.1.0 to root devDependencies - Update postpack in @workflow/core, @workflow/next, @workflow/ai, and workflow packages from `rm -rf docs` to `del-cli docs` Signed-off-by: John Lindquist <johnlindquist@gmail.com>
Document the CLI health check command for verifying workflow/step endpoint connectivity during local development and production. Signed-off-by: John Lindquist <johnlindquist@gmail.com>
Contributor
Author
|
Added |
pranaygp
reviewed
Jan 27, 2026
Contributor
pranaygp
left a comment
pranaygp
left a comment
There was a problem hiding this comment.
gonna keep reviewing but leaving initial feedback
| "clean": "tsc --build --clean && rm -rf docs ||:", | ||
| "test": "vitest run", | ||
| "prepack": "mkdir -p docs && cp -r ../../docs/content/docs/ai ./docs/ && cp -r ../../docs/content/docs/api-reference/workflow-ai ./docs/", | ||
| "postpack": "del-cli docs" |
Contributor
There was a problem hiding this comment.
let's either use rm -rf OR del-cli, not both
|
|
||
| ## Critical workflow rules | ||
|
|
||
| 1. Always set `globalThis.fetch = fetch` when using AI SDK or HTTP libraries |
Contributor
There was a problem hiding this comment.
let's not do this. that was meant to be a specific example and actually with DurableAgent you don't need that
| ## Critical workflow rules | ||
|
|
||
| 1. Always set `globalThis.fetch = fetch` when using AI SDK or HTTP libraries | ||
| 2. Use `sleep()` instead of setTimeout/setInterval |
Contributor
There was a problem hiding this comment.
only in "workflow" context. in steps it should still use setTimeout/setInterval
maybe claude is smart enough but fyi
| 2. Use `sleep()` instead of setTimeout/setInterval | ||
| 3. Move Node.js modules (fs, crypto, etc.) to step functions | ||
| 4. Use `FatalError` for permanent failures, `RetryableError` for retries | ||
| 5. Use `use step` with AI SDK methods to avoid issues with OIDC |
Contributor
There was a problem hiding this comment.
not sure what this means and it seems weird to put this in the index/root of the skill
pranaygp
reviewed
Jan 27, 2026
pranaygp
reviewed
Jan 27, 2026
- Remove del-cli dependency, use rm -rf consistently in postpack scripts - Restructure SKILL.md to lead with "Prefer Step Functions" pattern - Add sandbox limitations table for workflow-context workarounds - Consolidate examples and remove duplication Signed-off-by: John Lindquist <johnlindquist@gmail.com>
Move useful tips (serialization, streaming, debugging) into main skill file and remove the separate common-errors.md reference file. Signed-off-by: John Lindquist <johnlindquist@gmail.com>
…s-and-commands * origin/main: fix(@workflow/ai): support provider-executed tools (AI SDK v6) (#734) Publish "workflow" and "@workflow/core" package versions in sync (#870) Add SDK version to workflow run executionContext for observability (#868) Allow recreateRun to accept an optional deploymentId parameter (#869) Add support for top-level `using` declarations inside of step / workflow functions (#866) docs: URL in docs was missing the docs/ prefix, 404 errors (#852) Add "classes" object to `manifest.json` file (#864) Fix Nest workbench app build (#865) Ignore Astro on local dev tests for source map e2e tests (#863) Enable custom class serialization transformations for "client" mode (#860) Submit request bodies with CBOR encoding (#844) [world-vercel] Update queue to use VQS v3 API (#799) NestJS framework support (#840) Fix resolve hook theming and token fetching. (#856) docs: rename Control Flow Patterns to Common Patterns and add new content (#846) docs: revamp World documentation pages (#763) Remove unused `getWritable` stub function (#855) # Conflicts: # packages/core/package.json # pnpm-lock.yaml
pranaygp
approved these changes
Jan 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds Claude Code skills for the Workflow DevKit, enabling AI agents to assist with workflow development.
Documentation Bundling
This PR implements a documentation bundling pattern (similar to
aiSDK) that includes docs in npm packages:How it works
docs/content/docs/to package's./docs/directorydocs/**/*in the tarball./docs/directoryPackages updated
workflownode_modules/workflow/docs/@workflow/ainode_modules/@workflow/ai/docs/@workflow/corenode_modules/@workflow/core/docs/@workflow/nextnode_modules/@workflow/next/docs/Skill changes
The
skills/workflow/SKILL.mdnow directs agents to search bundled docs instead of maintaining duplicate documentation:Removed manually-maintained reference files:
ai-agents.md→ now innode_modules/@workflow/ai/docs/api-reference.md→ now innode_modules/workflow/docs/api-reference/frameworks.md→ now innode_modules/workflow/docs/getting-started/patterns.md→ now innode_modules/workflow/docs/foundations/Kept
common-errors.mdfor practical troubleshooting (not typically in official docs).Test plan
npm pack --dry-runincludes docs in tarballnpm install workflow