Drives the hosted Workflow Weaver service (weaver.vibingfun.com) through its workflow-weaver CLI and MCP server: create projects, upload API doc sources (OpenAPI specs, endpoint lists, code snippets), generate step-by-step workflow guides on the service, and export them as Markdown, SVG, PNG, PDF or JSON. Generation happens server-side and needs a Workflow Weaver account. Bundled smoke.sh checks that the CLI and MCP server are installed and authenticated and, when a token is set, reads the account's billing status (plan and quota, read-only). Use when the user asks to use Workflow Weaver or to turn their API docs into a Workflow Weaver guide; not for general diagramming or documentation requests.
Agent skill for driving the workflow-weaver CLI and MCP server headlessly. Works from any agent runtime that can invoke subprocesses or connect to an MCP host.
Pin these versions (the ones this skill is tested with) instead of installing the latest.
Authentication
Interactive (recommended for first-time setup):
bash
workflow-weaver auth login --email you@example.com
# Password is prompted interactively — omit --password to avoid exposing it in shell history
***
**Non-interactive (agents / CI):**
After an interactive login the CLI stores the refresh token in `~/.workflow-weaver/config.json` (chmod 600) and uses it from there, so a local agent needs nothing else.
For CI or a remote agent, store the refresh token in that platform's secret store and expose it as the `WORKFLOW_WEAVER_REFRESH_TOKEN` environment variable. Never print the token to the terminal, logs or chat to copy it.
The CLI automatically reads `WORKFLOW_WEAVER_REFRESH_TOKEN` from the environment. No prefix mapping is needed.
## Security
| Rule | Detail |
|------|--------|
| No hardcoded credentials | Never embed tokens, passwords, or keys in scripts, logs, or skill files |
| Refresh token via env var only | `WORKFLOW_WEAVER_REFRESH_TOKEN` — never interpolate into log lines or `echo` |
| Supabase credentials via env var only | `WORKFLOW_WEAVER_SUPABASE_URL` and `WORKFLOW_WEAVER_SUPABASE_KEY` — never in scripts |
| Config file path | `~/.workflow-weaver/config.json` (chmod 600) — document but never read directly in automation scripts; one-time setup extraction is acceptable |
| Stripe/billing URLs | Present to the user to open in a browser — never open programmatically |
| Confirm before acting | Ask the user before `delete_project`, `remove_source`, `set_provider_key`, `remove_provider_key`, `create_share_link`, `revoke_share_link` and `generate_workflow` (it uses the account's quota) |
| Share links are public | Anyone with a share link can view the project's workflow; review sources for internal endpoints or secrets and get the user's OK before creating one |
| Smoke placeholder | Use clearly-named placeholders like `smoke-test-invalid-token`, never real-looking values |
## Run (Agent Path)
### CLI subprocess pattern
All commands support `--json` for machine-readable NDJSON output:
```bash
workflow-weaver <command> [args] --json
Exit codes
Code
Meaning
0
Success
1
Domain error (WorkflowWeaverError) — check stderr for JSON
If byok_active: true, generation is unlimited regardless of plan or credits.
Token rotation gotcha
The refresh token in ~/.workflow-weaver/config.json may be rotated (invalidated and replaced) by the server. Never cache the token by reading the config file directly.
Always pass the token via WORKFLOW_WEAVER_REFRESH_TOKEN env var
If you must read from config, re-read before every operation — do not cache
The CLI handles token refresh internally; let it read from its config file
When using the env var, each CLI call may rotate the token server-side. The CLI writes the new token to ~/.workflow-weaver/config.json, but the env var still holds the old value. For long-running agent sessions, prefer letting the CLI read from its config file rather than setting the env var persistently
MCP Server Configuration
The MCP server requires three env vars: WORKFLOW_WEAVER_REFRESH_TOKEN, WORKFLOW_WEAVER_SUPABASE_URL, and WORKFLOW_WEAVER_SUPABASE_KEY.
The examples run the globally installed, pinned workflow-weaver-mcp binary rather than npx ...@latest. Hosts that cannot read your shell environment store these values in their config file in plain text: use the user-level config (not a project file that could be committed), keep it chmod 600, and revoke the token from your Workflow Weaver account if the file leaks. Cursor can reference environment variables with ${env:NAME}, as shown below.
Note:workflow-weaver-mcp comes from the pinned global install above (@workflow-weaver/mcp@0.1.0).
MCP Tools (23)
#
Tool
Description
1
get_auth_status
Verify the configured token
2
list_projects
List all projects
3
create_project
Create a new project
4
get_project
Get a project by ID
5
delete_project
Delete a project
6
add_source
Add an API doc source to a project
7
list_sources
List sources for a project
8
remove_source
Remove a source from a project
9
list_providers
List AI providers and key status
10
set_provider_key
Store a BYOK provider key
11
remove_provider_key
Remove a provider key
12
generate_workflow
Generate a workflow from sources
13
list_versions
List workflow versions
14
get_version
Get a specific version
15
patch_version
Apply a JSON Patch (RFC 6902) to a version
16
chat_edit
Edit a version via natural language
17
export_version
Export a version (svg/png/pdf/md/json)
18
create_share_link
Create a public share link (confirm with the user first)
19
list_share_links
List share links
20
revoke_share_link
Revoke a share link
21
get_billing_status
Check plan, usage, and quota
22
get_checkout_url
Get a Stripe checkout URL
23
get_portal_url
Get a Stripe customer portal URL
MCP error handling
All tool errors return isError: true with JSON in content[0].text:
json
{ "code": "INVALID_PARAMS", "message": "project_id is required" }
{ "code": "QUOTA_EXCEEDED", "message": "...", "resolution_paths": [...] }
{ "code": "AUTH_FAILED", "message": "Token is not authenticated" }
Smoke Test
Run offline checks (no token required):
bash
bash .claude/skills/run-workflow-weaver/smoke.sh
Run with live credentials. This adds two read-only account calls, auth status and billing status (plan, usage and quota); nothing is created or changed: