workflow-validate — Claude Code skill: Notion Worker Workflow checks
Walks through src/workflows/ and flags trigger typing mistakes and retry hazards. Useful before a workflow ships.
npx skills add makenotion/notion-cookbook --skill workflow-validate -a claude-codeWhat workflow-validate does
The skill reads every file under src/workflows/ plus the modules those files pull in. Each finding comes back with a file, a line, the impact and a suggested fix. A workflow that is not a direct file, or whose default export is missing createWorkflow, counts as an error.
Six more patterns land in the same list. Event fields tied to a specific trigger used without type narrowing. Work that is not deterministic sitting outside an awaited step. Step order or names that shift between retries. A step result that will not survive JSON serialization, or later code that mutates it in memory. A retry-sensitive write with no idempotency key and no duplicate guard.
Swallowed external failures are errors too, as are credentials written into the source or pushed into logs. With dependencies in place the skill runs npm run check and npm run build. Neither command works on a bare checkout, so install the packages first.
What it helps with
- catch a workflow that skips the
createWorkflowdefault export - spot trigger event fields used without type narrowing
- move non-deterministic work inside an awaited step
- add an idempotency key to a retry-sensitive write
- strip hard-coded and logged credentials
Example prompts for the agent
- Review the workflows in
src/workflows/and report findings with file, line and fix - Find step results that are not JSON-serializable
- Run
npm run checkandnpm run buildand walk me through the failures
How to install workflow-validate
1Skills CLI (Vercel)
npx skills add makenotion/notion-cookbook --skill workflow-validate -a claude-code2Manually: put the files in place
~/.claude/skills/workflow-validate/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/workflow-validate/
1Skills CLI (Vercel)
npx skills add makenotion/notion-cookbook --skill workflow-validate -a codex2Manually: put the files in place
.agents/skills/workflow-validate/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add makenotion/notion-cookbook --skill workflow-validate -a cursor2Manually: put the files in place
.cursor/skills/workflow-validate/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install makenotion/notion-cookbook workflow-validate2Manually: put the files in place
.github/skills/workflow-validate/SKILL.md1Skills CLI (Vercel)
npx skills add makenotion/notion-cookbook --skill workflow-validate -a gemini-cli2Platform CLI
gemini skills install https://github.com/makenotion/notion-cookbook --path workers/agents/skills/workflow-validateManually: put the files in place
.devin/skills/workflow-validate/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add makenotion/notion-cookbook --skill workflow-validate -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about workflow-validate
How do I install workflow-validate in Claude Code?
Run npx skills add makenotion/notion-cookbook --skill workflow-validate -a claude-code. The skill file then sits at ~/.claude/skills/workflow-validate/SKILL.md.
What does workflow-validate do?
It reviews src/workflows/ and the modules behind them for trigger typing, retry safety, JSON-serializable step results and credential handling, reporting file, line, impact and fix for each issue.
Which commands does the skill run?
npm run check and npm run build, and only once dependencies are installed.
Source text
SKILL.md · MIT
--- name: workflow-validate description: Review Notion Worker Workflows for trigger typing and retry safety. user-invocable: true disable-model-invocation: true --- # Workflow validation Review every file in `src/workflows/` and any modules it calls. Report each finding with its file, line, impact, and fix. Treat these as errors: 1. A Workflow is not a direct file or does not default-export `createWorkflow`. 2. Trigger-specific event fields are used without type narrowing. 3. Non-deterministic work occurs outside an awaited step. 4. Step order or names can change between retries. 5. A step result is not JSON-serializable or later code needs an in-memory mutation. 6. A retry-sensitive write lacks an idempotency key or duplicate guard. 7. External failures are ignored, or credentials are hard-coded or logged. Run `npm run check` and `npm run build` when dependencies are installed.
© makenotion · MIT · makenotion/notion-cookbook
