Workflow Schema Tuning

You edit `workflow-schema.json` to fix cases where the AI editor consistently picks the wrong node type or cites constraints that don't actually exist. The schema isn't a runtime validator, it's a prompt delivered to the AI, so treat edits as prompt engineering. The core philosophy is "align direction, don't prescribe rules." When the AI misbehaves, the fix is almost never adding more guidance bullets, it's removing whatever description or example is biasing it wrong. Check the skill template first (strongest pull), then node descriptions, then examples. After editing, regenerate the TOON format the MCP actually serves. Useful when you see "AIが特定のノードタイプを選んでくれない" or need to add a node type without accidentally teaching the AI to overuse it.

GitHub stars: 5.1K
last updated: Jun 11, 2026

View on GitHub

Install

$ npx -y skills add breaking-brake/cc-wf-studio --skill workflow-schema-tuning --agent claude-code

Installs into .claude/skills of the current project.

Files

Workflow Schema Tuning

The schema (resources/workflow-schema.json) is the primary spec delivered to the AI editor at runtime via the get_workflow_schema MCP tool. It is not a runtime validator — the runtime barely validates anything. Whatever the schema says, the AI believes. Treat schema edits as prompt engineering, not type definitions.

Core principle: align direction, do not prescribe rules

AI agents already know how to choose between node types intuitively (e.g., when to delegate to a sub-agent vs. handle in-context). The fix for bad output is almost never "add more rules" — it is "remove what is biasing the AI in the wrong direction."

Defaults:

Prefer minimal description text that states each node's positional role (立ち位置). Example: "A step executed by the main orchestrating agent" vs. "A step executed by an isolated sub-agent." The contrast does the work.
Avoid aiGenerationGuidance lists of "when to use / when not to use / anti-patterns." They treat the AI as a rules engine, bloat tokens, and fail on unanticipated cases.
Test minimal first. Only add guidance after a concrete failure where the minimal change is provably insufficient.

SKILL.md on GitHub